GlobalDataStore

This function retrieves the values of multiple keys in a single request.

This method is currently only supported on OrderedDataStore. Calling it on a standard GlobalDataStore or DataStore will throw an error.

Unlike GlobalDataStore:GetAsync(), this method does not return DataStoreKeyInfo since ordered data stores do not support versioning or metadata.

The returned dictionary maps each key to a table with a value field. For example, if you request keys {"coins", "gems"}, the result might look like:

{
    coins = { value = 100 },
    gems = { value = 50 }
}

Keys that do not exist in the data store or have empty values are omitted from the result rather than returning nil values.

Limits#

The keys array must contain at least one key and no more than the server-configured maximum (default 100). Exceeding the limit will throw an error. Each call counts against the ordered data store read budget based on the number of keys requested.

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().

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.

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.

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.

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

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 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().