GlobalDataStore
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, etc.
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.
Summary
Properties
Methods
Returns the value of a key in a specified data store and a DataStoreKeyInfo instance.
- IncrementAsync(key : string,delta : number,userIds : Array,options : DataStoreIncrementOptions):Variant
Increments the value of a key by the provided amount (both must be integers).
Removes the specified key while also retaining an accessible version.
Sets the value of the data store for the given key.
Updates a key's value with a new value from the specified callback function.
Properties
Methods
GetAsync
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().
Parameters
The key name for which the value is requested. If DataStoreOptions.AllScopes was set to true when accessing the data store through DataStoreService:GetDataStore(), this key name must be prepended with the original scope as in "scope/key".
Returns
The value of the entry in the data store with the given key and a DataStoreKeyInfo instance that includes the version number, date and time the version was created, and functions to retrieve UserIds and metadata.
IncrementAsync
This function increments the value of a key by the provided amount (both must be integers).
OrderedDataStore does not support versioning, so calling this method on an OrderedDataStore key will overwrite the current value with the incremented value and make previous versions inaccessible.
Parameters
Key name for which the value should be updated. If DataStoreOptions.AllScopes was set to true when accessing the data store through DataStoreService:GetDataStore(), this key name must be prepended with the original scope as in "scope/key".
Amount to increment the current value by.
(Optional) DataStoreIncrementOptions instance that combines multiple additional parameters as custom metadata and allows for future extensibility.
Returns
The updated value of the entry in the data store with the given key.
RemoveAsync
This function marks the specified key as deleted by creating a new "tombstone" version of the key. Prior to this, it returns the latest version prior to the remove call.
After a key is removed via this function, GlobalDataStore:GetAsync() calls for the key will return nil. Older versions of the key remain accessible through DataStore:ListVersionsAsync() and DataStore:GetVersionAsync(), assuming they have not expired.
OrderedDataStore does not support versioning, so calling RemoveAsync() on an OrderedDataStore key will permanently delete it.
Removed objects will be deleted permanently after 30 days.
If the previous values were already deleted via GlobalDataStore:RemoveAsync() or DataStore:RemoveVersionAsync(), the function will return nil, nil for value and DataStoreKeyInfo respectively.
Parameters
Key name to be removed. If DataStoreOptions.AllScopes was set to true when accessing the data store through DataStoreService:GetDataStore(), this key name must be prepended with the original scope as in "scope/key".
Returns
The value of the data store prior to deletion and a DataStoreKeyInfo instance that includes the version number, date and time the version was created, and functions to retrieve UserIds and metadata.
SetAsync
This function sets the latest value, UserIds, and metadata for the given key.
Values in data stores are versioned, meaning GlobalDataStore:SetAsync() will create a new version every time it is called. Prior versions can be accessed through DataStore:ListVersionsAsync()/DataStore:GetVersionAsync() for up to 30 days at which point they are permanently deleted.
OrderedDataStore does not support versioning, so calling this method on an OrderedDataStore 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 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.
Parameters
Key name for which the value should be set. If DataStoreOptions.AllScopes was set to true when accessing the data store through DataStoreService:GetDataStore(), this key name must be prepended with the original scope as in "scope/key".
The value that the data store key will be set to.
Table of UserIds, highly recommended to assist with GDPR tracking/removal.
(Optional) DataStoreSetOptions instance that allows for metadata specification on the key.
Returns
The version identifier of the newly created version. It can be used to retrieve key info using GetVersionAsync() or to remove it using RemoveVersionAsync().
UpdateAsync
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.
If the update succeeds, a new version of the value will be created and prior versions will remain accessible through DataStore:ListVersionsAsync() and DataStore:GetVersionAsync().
OrderedDataStore does not support versioning, so calling this function on an OrderedDataStore 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 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 Lua 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().
Parameters
Key name for which the value should be updated. If DataStoreOptions.AllScopes was set to true when accessing the data store through DataStoreService:GetDataStore(), this key name must be prepended with the original scope as in "scope/key".
Transform function that takes the current value and DataStoreKeyInfo as parameters and returns the new value along with optional UserIds and metadata.
Returns
The updated value of the entry in the data store with the given key and a DataStoreKeyInfo instance that includes the version number, date and time the version was created, and functions to retrieve UserIds and metadata.