GlobalDataStore¶
An object that exposes methods to access a single data store.
Note: GetAsync, SetAsync, IncrementAsync, UpdateAsync, and OnUpdate are implemented.
Description¶
A GlobalDataStore exposes functions for saving and loading data for the DataStoreService.
See Data stores for an in-depth guide on data structure, management, error handling, limits, and more.
Ordered data stores do not support versioning and metadata, so
DataStoreKeyInfo is always nil for keys in an
OrderedDataStore. If you need versioning and metadata support, use a
DataStore.
Inheritance¶
Object → Instance → GlobalDataStore
Nova inheritance: Instance → GlobalDataStore
Known subclasses: DataStore, OrderedDataStore
Methods¶
GetAsync Supported Function Returns the value of a key in a specified data store and a DataStoreKeyInfo instance.
Returns the value of a key in a specified data store and a DataStoreKeyInfo instance.
This function returns the latest value of the provided key and a
DataStoreKeyInfo instance. If the key does not exist or if the
latest version has been marked as deleted, both return values will be
nil.
Keys are cached locally for 4 seconds after the first read. A GlobalDataStore.GetAsync() call within these 4 seconds returns a value from the cache. Modifications to the key by GlobalDataStore.SetAsync() or GlobalDataStore.UpdateAsync() apply to the cache immediately and restart the 4 second timer.
To get a specific version, such as a version before the latest, use DataStore.GetVersionAsync().
Roblox reference signature
IncrementAsync Supported Function Increments the value of a key by the provided amount (both must be integers).
This function increments the value of a key by the provided amount (both must be integers).
Values in GlobalDataStores are versioned as outlined in versioning. OrderedDataStores do not support versioning, so calling this method on an ordered data store key will overwrite the current value with the incremented value and make previous versions inaccessible.
Roblox reference signature
OnUpdate Supported Function Deprecated Sets a callback function to be executed any time the value associated with a key is changed.
Sets a callback function to be executed any time the value associated with a key is changed.
This function sets callback as the function to be run any time the value
associated with the key changes. Once every minute, OnUpdate polls for
changes by other servers. Changes made on the same server will run the
function immediately. In other words, functions like
IncrementAsync(),
SetAsync(), and
UpdateAsync() change the key's value
in the data store and will cause the function to run.
It's recommended that you disconnect the connection when the subscription to the key is no longer needed.
Roblox reference signature
SetAsync Supported Function Sets the value of the data store for the given key.
Sets the value of the data store for the given key.
This function sets the latest value, UserIds, and metadata for the given key.
Values in GlobalDataStores are versioned as outlined in versioning. OrderedDataStores do not support versioning, so calling this method on an ordered data store key will overwrite the current value and make previous versions inaccessible.
Metadata definitions must always be updated with a value, even if there are no changes to the current value; otherwise the current value will be lost.
Any string being stored in a data store must be valid
Library.utf8|UTF-8. In UTF-8, values greater than 127 are used
exclusively for encoding multi-byte codepoints, so a single byte greater
than 127 will not be valid UTF-8 and the
GlobalDataStore.SetAsync() attempt will fail.
Set vs. Update¶
GlobalDataStore.SetAsync() is best for a quick update of a specific key, and it only counts against the write limit. However, it may cause data inconsistency if two servers attempt to set the same key at the same time. GlobalDataStore.UpdateAsync() is safer for handling multi-server attempts because it reads the current key value (from whatever server last updated it) before making any changes. However, it's somewhat slower because it reads before it writes, and it also counts against both the read and write limit.
Roblox reference signature
UpdateAsync Supported Function Updates a key's value with a new value from the specified callback function.
Updates a key's value with a new value from the specified callback function.
This function retrieves the value and metadata of a key from the data
store and updates it with a new value determined by the callback function
specified through the second parameter. If the callback returns nil, the
write operation is cancelled and the value remains unchanged.
Values in GlobalDataStores are versioned as outlined in versioning. OrderedDataStores do not support versioning, so calling this method on an ordered data store key will overwrite the current value and make previous versions inaccessible.
In cases where another game server updated the key in the short timespan
between retrieving the key's current value and setting the key's value,
GlobalDataStore.UpdateAsync() will call the function again,
discarding the result of the previous call. The function will be called as
many times as needed until the data is saved or until the callback
function returns nil. This can be used to ensure that no data is
overwritten.
Any string being stored in a data store must be valid
Library.utf8|UTF-8. In UTF-8, values greater than 127 are used
exclusively for encoding multi-byte codepoints, so a single byte greater
than 127 will not be valid UTF-8 and the
GlobalDataStore.UpdateAsync() attempt will fail.
Set vs. Update¶
GlobalDataStore.SetAsync() is best for a quick update of a specific key, and it only counts against the write limit. However, it may cause data inconsistency if two servers attempt to set the same key at the same time. GlobalDataStore.UpdateAsync() is safer for handling multi-server attempts because it reads the current key value (from whatever server last updated it) before making any changes. However, it's somewhat slower because it reads before it writes, and it also counts against both the read and write limit.
Callback Function¶
The callback function accepts two arguments:
- Current value of the key prior to the update.
- DataStoreKeyInfo instance that contains the latest version information (this argument can be ignored if metadata is not being used).
In turn, the callback function returns up to three values:
- The new value to set for the key.
- An array of UserIds to associate with the key. DataStoreKeyInfo.GetUserIds() should be returned unless the existing IDs are being changed; otherwise all existing IDs will be cleared.
- A Luau table containing metadata to associate with the key. DataStoreKeyInfo.GetMetadata() should be returned unless the existing metadata is being changed; otherwise all existing metadata will be cleared.
If the callback returns nil instead, the current server will stop
attempting to update the key.
The callback function cannot yield, so do not include calls like task.wait().
Roblox reference signature
Inherited members¶
Inherited from Instance: 8 properties, 36 methods, 7 events. They are documented on the base class page.
2 modern Roblox member(s) are not implemented yet — expand to inspect
Members declared by Roblox's GlobalDataStore class (or by a missing base class) that Nova does not expose. Use this list to scope a migration; the compatibility guide has the recommended workaround.
Methods¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
BatchGetAsync |
GlobalDataStore:BatchGetAsync(keys: Array, options: Dictionary = nil): Dictionary |
Not yet | Returns the values of multiple keys from the data store in a single request. | Yields |
RemoveAsync |
GlobalDataStore:RemoveAsync(key: string): Tuple |
Not yet | Removes the specified key while also retaining an accessible version. | Yields |
Roblox reference: GlobalDataStore
Generated from Nova's API dump and Roblox creator-docs. Nova-only members come from the engine's reflection metadata.