GlobalDataStore

Show Deprecated
Not Creatable
Not Replicated

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.

Summary

Properties

Events

Methods

GetAsync(key: string): Tuple  YIELDS

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  YIELDS

Increments the value of a key by the provided amount (both must be integers).

RemoveAsync(key: string): Tuple  YIELDS

Removes the specified key while also retaining an accessible version.

SetAsync(key: string, value: Variant, userIds: Array, options: DataStoreSetOptions): Variant  YIELDS

Sets the value of the data store for the given key.

UpdateAsync(key: string, transformFunction: function): Tuple  YIELDS

Updates a key's value with a new value from the specified callback function.

Properties

Events

Methods

GetAsync

Yields

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.

OrderedDataStore does not support versioning and metadata, so DataStoreKeyInfo will always be nil for keys in an OrderedDataStore.

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

key: string

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

Yields

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: string

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".

delta: number

Amount to increment the current value by.

Default Value: "1"
userIds: Array

(Optional) A table of UserIds to associate with the key.

Default Value: "{}"

(Optional) DataStoreIncrementOptions instance that combines multiple additional parameters as custom metadata and allows for future extensibility.

Default Value: "nil"

Returns

The updated value of the entry in the data store with the given key.

RemoveAsync

Yields

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: string

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

Yields

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: string

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".

value: Variant

The value that the data store key will be set to.

userIds: Array

Table of UserIds, highly recommended to assist with GDPR tracking/removal.

Default Value: "{}"

(Optional) DataStoreSetOptions instance that allows for metadata specification on the key.

Default Value: "nil"

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

Yields

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 to ensure that no data is overwritten. The function will be called as many times as needed until the data is saved or until the callback function returns nil.

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.

The callback function cannot yield, so do not include calls like wait().

Parameters

key: string

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".

transformFunction: function

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.