DataStore

Methods

GetVersionAsync(key : string,version : string):Tuple
Yields
Retrieves the specified key version.
GetVersionAtTimeAsync(key : string,timestamp : number):Tuple
Yields
Retrieves the key version that was current at a given time.
ListKeysAsync(prefix : string,pageSize : number,cursor : string,excludeDeleted : boolean):DataStoreKeyPages
Yields
Returns a DataStoreKeyPages object for enumerating through keys of a data store.
ListVersionsAsync(key : string,sortDirection : Enum.SortDirection,minDate : number,maxDate : number,pageSize : number):DataStoreVersionPages
Yields
Enumerates all versions of a key.
RemoveVersionAsync(key : string,version : string):()
Yields
Permanently deletes the specified version of a key.

Methods inherited from GlobalDataStore

GetAsync(key : string,options : DataStoreGetOptions):Tuple
Yields
Returns the value of a key in a specified data store and a DataStoreKeyInfo instance.
IncrementAsync(key : string,delta : number,userIds : Array,options : DataStoreIncrementOptions):Variant
Yields
Increments the value of a key by the provided amount (both must be integers).
RemoveAsync(key : string):Tuple
Yields
Removes the specified key while also retaining an accessible version.
SetAsync(key : string,value : Variant,userIds : Array,options : DataStoreSetOptions):Variant
Yields
Sets the value of the data store for the given key.
UpdateAsync(key : string,transformFunction : function):Tuple
Yields
Updates a key's value with a new value from the specified callback function.

Events

Properties

Methods

GetVersionAsync

Yields

This function retrieves the specified key version as well as a DataStoreKeyInfo instance. A version identifier can be found through DataStore:ListVersionsAsync() or alternatively be the identifier returned by GlobalDataStore:SetAsync().

Parameters

key: string

Key name for which the version info is requested. 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".

Default Value: ""

version: string

Version number of the key for which the version info is requested.

Default Value: ""

Returns

The value of the key at the specified version and a DataStoreKeyInfo instance that includes the version number, date and time the version was created, and functions to retrieve UserIds and metadata.

GetVersionAtTimeAsync

Yields

This function retrieves the key version that was current at a given time as well as a DataStoreKeyInfo instance.

Parameters

key: string

Default Value: ""

timestamp: number

Unix timestamp in milliseconds for which the requested version was current. Must be greater than zero. Must not be more than ten minutes in the future.

Default Value: ""

Returns

The value of the key that was current at the specified time and a DataStoreKeyInfo instance that includes the version number, date and time the version was created, and functions to retrieve UserIds and metadata. nil if no available version was current at the requested time.

Code Samples

Retrieving DataStore Versions by Time

local DataStoreService = game:GetService("DataStoreService")
local dataStore = DataStoreService:GetDataStore("DataStore")
local key = "key-123"

function setData(data)
	local success, result = pcall(function()
		dataStore:SetAsync(key, data)
	end)
	if not success then
		warn(result)
	end
end

function getVersionAtTime(timestamp)
	local success, result, keyInfo = pcall(function()
		return dataStore:GetVersionAtTimeAsync(key, timestamp.UnixTimestampMillis)
	end)
	if success then
		if result == nil then
			print("No version found at time")
		else
			print(result, keyInfo.Version)
		end
	else
		warn(result)
	end
end

-- Previously ran at 2024/12/02 6:00 UTC
setData("version 1")

-- Previously ran at 2024/12/02 9:00 UTC
setData("version 2")

-- Prints "No version found at time"
local time1 = DateTime.fromUniversalTime(2024, 12, 02, 05, 00)
getVersionAtTime(time1)

-- Prints "version 1 <version>"
local time2 = DateTime.fromUniversalTime(2024, 12, 02, 07, 00)
getVersionAtTime(time2)

-- Prints "version 2 <version>"
local time3 = DateTime.fromUniversalTime(2024, 12, 02, 10, 00)
getVersionAtTime(time3)

ListKeysAsync

DataStoreKeyPages

Yields

This function returns a DataStoreKeyPages object for enumerating through keys of a data store. It accepts an optional prefix parameter to only locate keys whose names start with the provided prefix.

If DataStoreOptions.AllScopes was set to true when accessing the data store through DataStoreService:GetDataStore(), keys will be returned with all scopes as prefixes.

Parameters

prefix: string

(Optional) Prefix to use for locating keys.

Default Value: ""

pageSize: number

(Optional) Number of items to be returned in each page. If no value is given, the engine sends a default value of 0 to the data store web service, which in turn defaults to 50 items per page.

Default Value: 0

cursor: string

(Optional) Cursor to continue iteration.

Default Value: ""

excludeDeleted: boolean

(Optional) Exclude deleted keys from being returned.

When enabled ListKeys will check up to 512 keys. If all checked keys are deleted then it will return an empty list with a cursor to continue iteration.

Default Value: false

Returns

DataStoreKeyPages

A DataStoreKeyPages instance that enumerates the keys as DataStoreKey instances.

ListVersionsAsync

DataStoreVersionPages

Yields

This function enumerates versions of the specified key in either ascending or descending order specified by a Enum.SortDirection parameter. It can optionally filter the returned versions by minimum and maximum timestamp.

Parameters

key: string

Key name for the versions to list. 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".

Default Value: ""

sortDirection: Enum.SortDirection

(Optional) Enum specifying ascending or descending sort order.

Default Value: "Ascending"

minDate: number

(Optional) Unix timestamp in milliseconds after which the versions should be listed.

Default Value: 0

maxDate: number

(Optional) Unix timestamp in milliseconds up to which the versions should be listed.

Default Value: 0

pageSize: number

(Optional) Number of items to be returned in each page. If no value is given, the engine sends a default value of 0 to the data store web service, which in turn defaults to 1024 items per page.

Default Value: 0

Returns

DataStoreVersionPages

A DataStoreVersionPages instance that enumerates all the versions of the key as DataStoreObjectVersionInfo instances.

Code Samples

Retrieving DataStore Versions With A Date Filter

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local time = DateTime.fromUniversalTime(2020, 10, 09, 01, 42)

local listSuccess, pages = pcall(function()
	return experienceStore:ListVersionsAsync("User_1234", nil, time.UnixTimestampMillis)
end)

if listSuccess then
	local items = pages:GetCurrentPage()

	for key, info in pairs(items) do
		print("Key:", key, "; Version:", info.Version, "; Created:", info.CreatedTime, "; Deleted:", info.IsDeleted)
	end
end

RemoveVersionAsync

()

Yields

This function permanently deletes the specified version of a key. Version identifiers can be found through DataStore:ListVersionsAsync().

Unlike GlobalDataStore:RemoveAsync(), this function does not create a new "tombstone" version and the removed value cannot be retrieved later.

Parameters

key: string

Key name for which a version is to be removed. 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".

Default Value: ""

version: string

Version number of the key to remove.

Default Value: ""

Returns

()

Properties inherited from GlobalDataStore

Events