UpdateAsync

Yields

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts.

Unsafe

For thread safety, this property is not safe to read in an unsynchronized thread.

Function of:

GlobalDataStore

Description:

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 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 Articles/Lua Libraries/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 Player/UserId|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

Name	Type	Default	Description
Name key	Type string	Default	Summary 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”.
Name transformFunction	Type Function	Default	Summary Transform function that takes the current value and `DataStoreKeyInfo` as parameters and returns the new value along with optional `Player/UserId\|UserIds` and metadata.

Returns

Return Type	Summary
Return Type Tuple	Summary 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 `Player/UserId\|UserIds` and metadata.

Code Samples

Update Data Store Value

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName, keyInfo)
	local nameUpper = string.upper(currentName)
	local userIDs = keyInfo:GetUserIds()
	local metadata = keyInfo:GetMetadata()
	return nameUpper, userIDs, metadata
end

local success, updatedName, keyInfo = pcall(function()
	return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
	print(updatedName)
	print(keyInfo.CreatedTime)
	print(keyInfo:GetMetadata())
end