GlobalDataStore

GlobalDataStore : Instance

Overview

Provides features used to save and load data.

Properties

Methods

GetAsync

Returns DataStoreKeyInfo, which contains the value stored to a specified key and information of the item.

These two values return nil if the key doesn’t exist.

Parameters

string InKey	The key storing data.
DataStoreGetOptions InOptions	Currently not supported

Return

Tuple	Returns the DataStoreKeyInfo object, which contains information such as version timestamp, along with the value of the specified key.

Code Samples

local DataStoreService = game:GetService("DataStoreService") 
local GoldStore = DataStoreService:GetDataStore("PlayerGold") 

local success, errorMessageOrLoadValue = pcall(function()
    return GoldStore:GetAsync(player.UserId)
end)

IncrementAsync

Provides a feature used to increase or decrease the value stored in a key by a specified integer value. Both exiting value and value used to adjust must be integer for this feature to be processed properly.

Because IncrementAsync performs atomic calculation internally, unlike SetAsync, a value is safely accrued even when multiple users are updating the value at the same time. Due to this nature, IncrementAsync is the simplest and most effective option when processing accrued number data such as coin, EXP, or score.

Parameters

string InKey	The key of which value will be updated.
number InDelta	Represents the integer value to be added to existing value; currently stored value will be increased by this number.
array InUserIds	(Optional) Metadata used to track who updated data or ID of the users affected by the change.
DataStoreIncrementOptions InOptions	(Optional) An object used to store additional information or metadata.

Return

Value	The stored final key value.

Code Samples

local DataStoreService = game:GetService("DataStoreService") 
local GoldStore = DataStoreService:GetDataStore("PlayerGold") 

local success, errorMessageOrLoadValue = pcall(function()
    return GoldStore:IncrementAsync(player.UserId, 1)
end)

RemoveAsync

Converts a certain key into the deleted status.

Once deletion is complete, GetAsync retrieving the key returns nil.

Parameters

string InKey	The key to be deleted.

Return

void

Code Samples

local DataStoreService = game:GetService("DataStoreService") 
local GoldStore = DataStoreService:GetDataStore("PlayerGold") 

local success, errorMessage = pcall(function()
    GoldStore:RemoveAsync(player.UserId)
end)

SetAsync

Overwrites the value stored in a specific key with a specified value.

SetAsync is useful when quickly updating individual keys, but when multiple servers are trying to change the same key, the values overwrite each other, resulting in an unexpected value may be stored.

For this reason, when race condition needs to be prevented while multiple users are reading and writing data simultaneously, it is safer to use methods such as IncrementAsync or UpdateAsync that support atomic process.

Parameters

string InKey	The key of which value will be updated.
Value InValue	The value to be changed.
Value InUserIds	(Optional) Metadata used to track who updated data or ID of the users affected by the change.
DataStoreSetOptions InOptions	(Optional) An object used to store additional information or metadata.

Return

Value	The stored final key value.

Code Samples

local DataStoreService = game:GetService("DataStoreService") 
local GoldStore = DataStoreService:GetDataStore("PlayerGold") 

local success, errorMessageOrLoadValue = pcall(function()
    GoldStore:SetAsync(player.UserId, 100) 
end)

UpdateAsync

It reads a specific key and updates data with a new value decided by the callback function. If nil is returned during callback, task is canceled and existing data will be maintained.

If multiple requests come in simultaneously and a data conflict occurs, UpdateAsync automatically fetches the latest value and reruns the callback to resolve the conflict. This process repeats until the data is safely updated.

The value of a callback function must be single Table form instead of Tuple. A new value, UserIds, and metadata must be included in this table in the order and returned.

Parameters

string InKey	The key of which value will be updated.
Value InTransformFunction	A callback function that takes DataStoreKeyInfo containing currently stored value and its version information as a factor and converts values to be updated, and if necessary, UserIds and metadata to be stored together into a single table. UpdateAsync updates data based on the content of the table returned by this callback.

Return

Tuple	Returns the DataStoreKeyInfo object, which contains information such as version timestamp, along with the value of the specified key.

Code Samples

local DataStoreService = game:GetService("DataStoreService") 
local GoldStore = DataStoreService:GetDataStore("PlayerGold") 

local success, errorMessageOrLoadValue, keyInfo = pcall(function()
    return GoldStore:UpdateAsync(player.UserId, function(currentGold, keyInfo)
        local newGold = (currentGold or 0) + 10		
        return { newGold, keyInfo:GetUserIds(), keyInfo:GetMetadata() }
    end)
end)

Events

See also

Saving & Loading Data