SetAsync
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.
For thread safety, this property is not safe to read in an unsynchronized thread.
This function sets the latest value, Player/UserId|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.
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/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.
See Also
Articles/Data store|Data Stores, an in-depth guide on data structure, management, error handling, etc.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
|
|
Key name for which the value should be set. If |
||
|
|
The value that the data store key will be set to. |
||
|
{}
|
Table of |
||
|
nil
|
(Optional) |
Returns
| Return Type | Summary |
|---|---|
|
The version identifier of the newly created version. It can be used to retrieve key info using |
Code Samples
Set Data Store Key/Value
The following code sample demonstrates how to set a key’s value and include an optional table of Player/UserId|UserIds along with a DataStoreSetOptions instance that defines metadata for the key.
local DataStoreService = game:GetService("DataStoreService")
local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
local setOptions = Instance.new("DataStoreSetOptions")
setOptions:SetMetadata({["ExperienceElement"] = "Fire"})
local success, errorMessage = pcall(function()
experienceStore:SetAsync("User_1234", 50, {1234}, setOptions)
end)
if not success then
print(errorMessage)
end