Data stores are a storage feature for Roblox games. They can be used to save data which should persist between game sessions, including items in a player’s inventory, experience points, or almost anything else.

Data stores are shared per game, so any place in a game, including places in different servers, can access and change the same data.

Structure

A data store is essentially a dictionary, like a Lua table. Each value in the data store can be indexed by a unique key which includes the player’s Player/UserId|UserId, for instance:

Key Value
Player_1234 50
Player_2345 20
Player_7462 78000
Player_8934 1200
Player_10345 0

Data Store Access

Data stores are managed by DataStoreService, so your scripts must get the service before doing much else:

local DataStoreService = game:GetService("DataStoreService")

Data stores can only be accessed by the server through Script|Scripts. Attempting client-side access in a LocalScript will cause an error.

Managing a Data Store

Setting Data

GlobalDataStore/SetAsync|SetAsync() sets the value of a new data store entry. This function requires the key name of the entry and the value to set.

local DataStoreService = game:GetService("DataStoreService")
local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
 
local success, err = pcall(function()
	experienceStore:SetAsync("Player_1234", 50)
end)
 
if success then
	print("Success!")
end

Functions like GlobalDataStore/SetAsync|SetAsync() that access a data store's contents are network calls that may occasionally fail. It's recommended that these calls be wrapped in pcall() to catch and handle errors.

GlobalDataStore/SetAsync|SetAsync() can be hazardous since it overwrites any value currently in the entry. If you're updating an existing entry, GlobalDataStore/UpdateAsync|UpdateAsync() is recommended because it considers the old value before making changes.

Reading Data

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

local DataStoreService = game:GetService("DataStoreService")
local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
 
local success, currentExperience = pcall(function()
	return experienceStore:GetAsync("Player_1234")
end)
 
if success then
	print("Current Experience:", currentExperience)
end

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.

local DataStoreService = game:GetService("DataStoreService")
local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
 
local success, newExperience = pcall(function()
	return experienceStore:IncrementAsync("Player_1234", 1)
end)
 
if success then
	print("New Experience:", newExperience)
end

Updating Data

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

local DataStoreService = game:GetService("DataStoreService")
local nicknameStore = DataStoreService:GetDataStore("Nicknames")
 
local function makeNameUpper(currentName)
	local newName = string.upper(currentName)
	return newName
end
 
local success, newName = pcall(function()
	return nicknameStore:UpdateAsync("Player_1234", makeNameUpper)
end)
 
if success then
	print("Uppercase Name:", newName)
end

The function passed into GlobalDataStore/UpdateAsync|UpdateAsync() is not permitted to yield, so it cannot contain any yielding function like wait().

Removing Data

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

local DataStoreService = game:GetService("DataStoreService")
local nicknameStore = DataStoreService:GetDataStore("Nicknames")
 
local success, nickname = pcall(function()
	return nicknameStore:RemoveAsync("Player_1234")
end)
 
if success then
	print("Removed Nickname:", nickname)
end

Data Store Events

Each key in a data store can fire an event when its value changes. This can be connected to a custom function by GlobalDataStore/OnUpdate|OnUpdate() which requires the key name of the entry plus the function to call when the event occurs.

local DataStoreService = game:GetService("DataStoreService")
local levelStore = DataStoreService:GetDataStore("PlayerLevel")
 
local connection
 
local function onLevelUpdate(newLevel)
	if newLevel == 50 then
		print("Player has reached max level!")
		-- Disconnect connection when player reaches max level
		connection:Disconnect()
	end
end
 
connection = experienceStore:OnUpdate("Player_1234", onLevelUpdate)
 
local success, err = pcall(function()
	levelStore:IncrementAsync("Player_1234", 1)
end)

As shown in this example, it's recommended that you disconnect connections when they're no longer needed, as there's a Articles/Datastore Errors|request limit associated with GlobalDataStore/OnUpdate|OnUpdate() events.

Ordered Data Stores

Regular data stores do not sort their content. This isn’t a concern for many games, but sometimes it’s useful to get data in an ordered fashion, like leaderboard stats.

An OrderedDataStore is a special type of data store that can:

  • Easily return its content in a sorted order.
  • Return multiple records in one request (versus a regular data store where you can only request one entry at a time).

An ordered data store uses the same functions as a regular data store including GlobalDataStore/GetAsync|GetAsync(), GlobalDataStore/SetAsync|SetAsync(), GlobalDataStore/UpdateAsync|UpdateAsync(), etc. In addition, it provides the OrderedDataStore/GetSortedAsync|GetSortedAsync() function which accepts parameters for the “page size” of the returned DataStorePages object, the sort order, and minimum/maximum values.

Consider an ordered data store populated with five characters and their ages. This example sorts the data into pages with 3 entries each, in descending order, then loops through the pages and outputs each character’s name/age.

local DataStoreService = game:GetService("DataStoreService")
local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")
 
-- Populate ordered data store
characterAgeStore:SetAsync("Mars", 19)
characterAgeStore:SetAsync("Janus", 20)
characterAgeStore:SetAsync("Diana", 18)
characterAgeStore:SetAsync("Venus", 25)
characterAgeStore:SetAsync("Neptune", 62)
 
-- Sort data into pages of three entries (descending order)
local pages = characterAgeStore:GetSortedAsync(false, 3)
 
while true do
	-- Get the current (first) page
	local data = pages:GetCurrentPage()
	-- Iterate through all key-value pairs on page
	for _, entry in pairs(data) do
		print(entry.key .. ":" .. tostring(entry.value))
	end
	-- Check if last page has been reached
	if pages.IsFinished then
		break
	else
		print("----------------")
		-- Advance to next page
		pages:AdvanceToNextPageAsync()
	end
end

Error Handling / Limits

Requests to data stores, like all network calls, may occasionally fail due to poor connectivity or other issues. As you’ve seen throughout this article, it’s important to wrap data store commands in pcall() and handle any resulting errors. Every error message contains an error code that you can cross-reference in the Articles/Datastore Errors|Data Store Errors and Limits tables.

In addition, there are Articles/Datastore Errors|limits applied to the data store model. If a game exceeds these limits, the Roblox engine will automatically throttle the game’s data store usage, causing data requests to take longer.

Using Data Stores in Studio

By default, places simulated in Studio do not have access to data stores, so any request function like GlobalDataStore/SetAsync|SetAsync() or GlobalDataStore/GetAsync|GetAsync() will cause an error if called from Studio.

If desired, data stores can be enabled in Studio as follows:

  1. Go to the Create menu on the Roblox site.

  2. Select Configure Game for the desired game.

  3. In the Basic Settings tab, check Enable Studio Access to API Services.

  4. Click Save to register your changes.

Accessing data stores in Studio can be dangerous for live games because Studio accesses the same data stores as the client application. To avoid overwriting production data, you should not to enable this setting for live games — instead, enable it for a separate test version of the game.

Now that you understand data stores, the primary request commands, and the basic limits, learn how to implement a functional data store in Articles/Saving Player Data|Saving Player Data.

https://www.robloxdev.com/articles/Data-store