GlobalDataStore

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

Returns

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

Returns

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

Returns

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

Returns

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

Returns