DataStoreService lets you store data that needs to persist between sessions, such as items in a player’s inventory or skill points. Data stores are shared per experience, so any place in an experience, including places on different servers, can access and change the same data.

Enabling Studio Access

By default, experiences tested in Studio cannot access data stores, so you must first enable them.

1. Make sure your experience is published (File → Publish to Roblox) to enable Studio access.
2. From the Home tab, open the Game Settings window.
3. In the Security section, turn on Enable Studio Access to API Services.

4. Click Save to register your changes.

Accessing a Data Store

Once you include DataStoreService in a script, access a data store by name using the DataStoreService/GetDataStore|GetDataStore() function. For example:

Managing a Data Store

Setting Data

A data store is essentially a dictionary, similar to a Lua table. A unique key indexes each value in the data store, such as a player’s unique Player/UserId or a named string for a game promo.

To create a new entry, call GlobalDataStore/SetAsync|SetAsync() with the key name and a value.

Reading Data

The GlobalDataStore/GetAsync|GetAsync() function reads the value of a data store entry. It requires just the key name of the entry.

Incrementing Data

GlobalDataStore/IncrementAsync|IncrementAsync() changes a numerical value in a data store. This function requires the key name of the entry and a number indicating how much to change the value.

Updating Data

GlobalDataStore/UpdateAsync|UpdateAsync() changes any stored value in a data store. This function requires the key name of the entry plus a callback function which defines how the entry should be updated. This callback takes the current value and returns the new value, based on whatever logic you define.

Removing Data

GlobalDataStore/RemoveAsync|RemoveAsync() removes an entry and returns the value that was associated with the key.

Ordered Data Stores

By default, data stores do not sort their content, but sometimes it’s necessary to get data in an ordered fashion, such as persistent leaderboard stats. You can achieve this by calling DataStoreService/GetOrderedDataStore|GetOrderedDataStore() instead of DataStoreService/GetDataStore|GetDataStore().

Ordered data stores support the same basic functions as default data stores, plus the unique OrderedDataStore/GetSortedAsync|GetSortedAsync() function. This retrieves multiple sorted keys based on a specific sorting order, page size, and minimum/maximum values.

The following example sorts character data into pages with three entries each in descending order, then loops through the pages and outputs each character’s name/age.

Metadata

There are two types of metadata associated with keys:

Metadata is managed by expanding the GlobalDataStore/SetAsync|SetAsync(), GlobalDataStore/GetAsync|GetAsync(), GlobalDataStore/UpdateAsync|UpdateAsync(), GlobalDataStore/IncrementAsync|IncrementAsync(), and GlobalDataStore/RemoveAsync|RemoveAsync() functions.

• GlobalDataStore/SetAsync|SetAsync() accepts optional third and fourth arguments:
  • Table of Player/UserId|UserIds, highly recommended to assist with articles/managing personal information|GDPR tracking/removal.
  • A DataStoreSetOptions object on which you can define custom metadata using its DataStoreSetOptions/SetMetadata|SetMetadata() function.

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

• GlobalDataStore/GetAsync|GetAsync(), GlobalDataStore/IncrementAsync|IncrementAsync(), and GlobalDataStore/RemoveAsync|RemoveAsync() return a second value (DataStoreKeyInfo object) that contains both service-defined properties and functions to fetch user-defined metadata:
  • DataStoreKeyInfo/GetUserIds|DataStoreKeyInfo:GetUserIds() — Fetches the table of Player/UserId|UserIds that was passed to GlobalDataStore/SetAsync|SetAsync().
  • DataStoreKeyInfo/GetMetadata|DataStoreKeyInfo:GetMetadata() — Fetches user-defined metadata that was passed to GlobalDataStore/SetAsync|SetAsync() through DataStoreSetOptions/SetMetadata|SetMetadata().
  • DataStoreKeyInfo/Version — Version of the key.
  • DataStoreKeyInfo/CreatedTime — Time the key was created, formatted as the number of milliseconds since epoch.
  • DataStoreKeyInfo/UpdatedTime — Last time the key was updated, formatted as the number of milliseconds since epoch.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
 
local success, currentExperience, keyInfo = pcall(function()
	return experienceStore:GetAsync("User_1234")
end)
if success then
	print(currentExperience)
	print(keyInfo.Version)
	print(keyInfo.CreatedTime)
	print(keyInfo.UpdatedTime)
	print(keyInfo:GetUserIds())
	print(keyInfo:GetMetadata())
end

• The callback function of GlobalDataStore/UpdateAsync|UpdateAsync() takes an additional parameter (DataStoreKeyInfo object) that describes the current key state. It returns the modified value, the key’s associated Player/UserId|UserIds, and the key’s metadata.

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.Version)
	print(keyInfo.CreatedTime)
	print(keyInfo.UpdatedTime)
	print(keyInfo:GetUserIds())
	print(keyInfo:GetMetadata())
end

User-defined metadata has the following limits:

• Key length: up to 50 characters.
• Value length: up to 250 characters.
• No limit for the total number of key-value pairs but the total size cannot exceed 300 characters.

Versioning

With versioning, GlobalDataStore/SetAsync|SetAsync() and GlobalDataStore/UpdateAsync|UpdateAsync() create new versions instead of overwriting existing data, and GlobalDataStore/GetAsync|GetAsync() reads the latest version. DataStoreService periodically checks the timestamps of each version and removes versions older than 30 days, but retains the latest version indefinitely.

There are three new APIs for versioning operations:

Versioning is convenient for user support. For example, if a user reports that a problem occurred at 2020-10-09T01:42, you can revert to a previous version using the code below.

Listing and Prefixes

Data stores allow for listing by prefix (the first n characters of a name, such as “d”, “do”, or “dog” for any key or data store with a prefix of “dog”).

You can specify a prefix when listing all data stores or keys, and only objects matching that prefix will be returned. Both functions return a DataStoreListingPages object that you can use to enumerate the list.

Error Codes

Requests to data stores may occasionally fail due to poor connectivity or other issues. Wrapping data store functions in pcall() will handle any errors and return a message with an error code.

Limits

There are also limits applied to the data store model. If an experience exceeds these limits, the service will automatically throttle the experience’s data store usage, causing requests to be placed in a queue.

When a limit is reached, further requests are placed into one of four queues: set, ordered set, get, and ordered get. Requests in a queue are handled in the order they are received and the called function continues to yield as long as its request is queued. If the data store key itself is throttled, the request is temporarily skipped but still in the queue. Each queue has a limit of 30 requests and, when this limit is exceeded, the requests fail with an error code in the 301–306 range indicating that the request was dropped entirely.

Caching

Keys cache locally for 4 seconds after the first read. A GlobalDataStore/GetAsync|GetAsync() call within these 4 seconds returns a value from the cache. Modifications to the key by GlobalDataStore/SetAsync|SetAsync() or GlobalDataStore/UpdateAsync|UpdateAsync() apply to the cache immediately and restart the 4 second timer.

DataStore/GetVersionAsync|GetVersionAsync(), DataStore/ListVersionsAsync|ListVersionsAsync(), DataStore/ListKeysAsync|ListKeysAsync(), and DataStoreService/ListDataStoresAsync|ListDataStoresAsync() don’t implement caching and will always fetch the latest data from the service.

Best Practices

The following guidelines will help you manage your data more efficiently and take advantage of future improvements.

Create Fewer Data Stores

Data stores behave similarly to tables in databases. Minimize the number of data stores in an experience and put related data in each data store. This approach allows you to configure each data store individually (versioning and indexing/querying) to improve the service’s efficiency to operate the data; as more features become available, this approach also allows you to more easily manage data stores.

Use a Single Object for Related Data

Since the increased maximum object size is 4 MB, there should be enough space to follow this rule. You can fetch all relevant data in one call and use the quota (limit) more efficiently. Additionally, GlobalDataStore/SetAsync|SetAsync() updates all data, so all data for the same player is always in sync. The versioning system versions individual objects rather than the whole data store. When restoring to older versions, self-contained objects are now consistent and useful.

Use Key Prefixes to Organize Your Data

You can filter keys with a certain prefix when calling DataStore/ListKeysAsync|ListKeysAsync(). Consider an experience that supports players having multiple character profiles; you can save keys with a prefix such as /User_1234/profiles/warrior and /User_1234/profiles/mage and use a prefix search with /User_1234/profiles to get a list of all profiles.