GlobalDataStore

GlobalDataStore : Instance

Overview

Provides features used to save and load data.

When you use these methods on an OrderedDataStore, the storable values, return values, and callback format differ, so refer to the OrderedDataStore page as well.

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 key	The key storing data.
DataStoreGetOptions options	(Optional) An options object used to control retrieval behavior. If the UseCache property is set to true and a valid cached value remains, the cached value is returned as-is without sending a new request to the server.

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 key	The key of which value will be updated.
number delta	Represents the integer value to be added to existing value; currently stored value will be increased by this number.
Array userIds	(Optional) Metadata used to track who updated data or ID of the users affected by the change.
DataStoreIncrementOptions options	(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 key	The key to be deleted.

Return

Tuple	Returns the value and DataStoreKeyInfo of the removed key prior to deletion.

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 key	The key of which value will be updated.
Value value	The value to be changed.
Value userIds	(Optional) Metadata used to track who updated data or ID of the users affected by the change.
DataStoreSetOptions options	(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 key	The key of which value will be updated.
Value transformFunction	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