DataService

Getting it

local DataService = Engine:GetService("DataService")

Overview

DataService is Engine's storage layer. Its core is the profile: a table of data for one key (usually one player) that is loaded once, owned by exactly one server at a time, kept in memory while the player plays, autosaved, and saved one last time when the session ends or the server shuts down. Because only one server can own a profile, item duplication through server hopping is not possible.

Changes you make through the profile's methods (Set, Increment, ArrayInsert...) are also replicated to the player who owns the profile, so the client always has a live, read-only copy of its own data without any remotes of your own.

Around profiles DataService wraps every other Roblox storage service with retries, request budgeting and error reporting:

Player data in 20 lines

local Players = game:GetService("Players")
local Engine = require(game:GetService("ServerScriptService"):WaitForChild("Engine"))
local DataService = Engine:GetService("DataService")

local PlayerData = DataService:CreateProfileStore("PlayerData", {
	Coins = 0,
	Level = 1,
	Inventory = {},
})

Players.PlayerAdded:Connect(function(player)
	PlayerData:StartSessionAsync(PlayerData:PlayerKey(player), {
		Player = player,
		Create = true, -- create the profile for new players
	}):andThen(function(profile)
		profile:Reconcile() -- add fields that were added to the template later
		print(player.Name, "has", profile:Get("Coins"), "coins")
	end):catch(function(err)
		player:Kick("Your data could not be loaded. Please rejoin.")
		warn(err)
	end)
end)

local function addCoins(player: Player, amount: number)
	local profile = PlayerData:GetSession(PlayerData:PlayerKey(player))
	if profile then
		profile:Increment("Coins", amount)
	end
end

local DataService = Engine:GetService("DataService")

DataService:GetProfileAsync("PlayerData"):andThen(function(profile)
	coinsLabel.Text = tostring(profile:Get("Coins"))
	profile:OnChange("Coins", function(coins)
		coinsLabel.Text = tostring(coins)
	end)
end)

The session ends by itself when the player leaves (EndSessionOnLeave), and every active profile is saved when the server shuts down.

Profile stores

CreateProfileStore

DataService:CreateProfileStore(name: string, template: { [string]: any }?, options: { Migrations: { Migration }? }?): ProfileStore

Creates the store (a DataStore with that name). New profiles start as a deep copy of template. Migrations is a list of functions that upgrade old data in place: when a profile with an older data version loads, each missing migration runs once, in order.

local PlayerData = DataService:CreateProfileStore("PlayerData", template, {
	Migrations = {
		function(data) -- version 1 -> 2: coins became a table of currencies
			data.Currencies = { Coins = data.Coins or 0 }
			data.Coins = nil
		end,
	},
})

:GetProfileStore(name) returns an existing store (errors if missing), :FindProfileStore(name) returns nil instead, :GetProfileStores() lists them.

ProfileStore

StartSessionParams

If another server still owns the profile, DataService asks it to save and release, and waits (FirstLoadRepeat, LoadRepeatPeriod). An unresponsive server's session is taken over after SessionStealSeconds, and a crashed server's session (no save for AssumeDeadSeconds) is taken immediately.

Profile

Reading and writing data

Use the profile's methods to change data. They validate the change, mark the profile dirty and replicate the change to the player. Paths are dot strings such as "Inventory.Weapons" or key arrays (see Patch).

Set and Update never create tables along the path, and never replace a value on the path that is not a table. They error with the part of the path that is the problem, and change nothing:

profile:Set("Stats.Kills", 0)  -- errors: Engine: DataService Profile:Set - Stats does not exist
profile:Set("Stats", {})       -- create the table first
profile:Set("Stats.Kills", 0)  -- works: the last key may be new
profile:Set("Coins.Gold", 5)   -- errors when Coins holds a number: Coins is not a table

Tables your data always needs belong in the template, so :Reconcile() adds them to older profiles.

You can also change profile.Data directly; call :Sync() afterwards to replicate the whole table to the player.

Saving and sessions

Before every save the data is checked with Patch.Validate (ValidateDataOnSave). Invalid data is reported and the save is skipped, so one bad value never corrupts the stored profile.

Messages

ProfileStore:MessageAsync(key, message) queues a message in the profile itself. The server that owns the profile receives it in profile.OnMessage; if nobody owns it, the next server to load it does.

profile.OnMessage = function(message, processed)
	if message.Type == "Gift" then
		profile:Increment("Coins", message.Amount)
	end
	processed() -- remove the message from the queue
end

Edits and transfers

Messages are fire-and-forget. Edits are named, validated changes that you can await, with a guaranteed single application even when retried:

PlayerData:DefineEdit("GrantItem", function(profile, payload, meta)
	if #profile:Get("Inventory") >= 100 then
		return false -- reject: inventory full
	end
	profile:ArrayInsert("Inventory", payload.ItemId)
end)

-- from any server, for an online or offline player
PlayerData:EditAsync(PlayerData:PlayerKey(userId), "GrantItem", { ItemId = "Sword" }, { WaitForApply = true })
	:andThen(function(result, reason)
		print(result) -- "applied", "queued", "rejected" or "missing"
	end)

A handler that errors or returns false rejects the edit. Payloads must be storable values.

Transfers move something between two profiles, for example a trade or a gift, so that it is never lost or duplicated: the Debit handler runs on the source profile, then Credit on the target. If the credit fails, Refund gives it back to the source.

PlayerData:DefineTransfer("GiftCoins", {
	Debit = function(profile, payload)
		if profile:Get("Coins") < payload.Amount then
			return false
		end
		profile:Increment("Coins", -payload.Amount)
	end,
	Credit = function(profile, payload)
		profile:Increment("Coins", payload.Amount)
	end,
	Refund = function(profile, payload)
		profile:Increment("Coins", payload.Amount)
	end,
})

PlayerData:TransferAsync(fromKey, toKey, "GiftCoins", { Amount = 100 })

TransferOptions: { Id?, ToStore?, WaitForApply? }. ToStore moves between two profile stores. Applied ids are remembered for AppliedIdRetentionDays.

Receipt processors

CreateReceiptProcessor

DataService:CreateReceiptProcessor(store: ProfileStore, handlers: { [productId]: (profile, receiptInfo) -> any }, options: { OnUnknownProduct? }?): (receiptInfo) -> Enum.ProductPurchaseDecision

Builds a ProcessReceipt callback that grants developer products exactly once: it finds the buyer's active profile, skips purchases it already applied, runs your handler, records the purchase id and saves before telling Roblox the purchase was granted. A handler that errors or returns false leaves the purchase pending, so Roblox tries again later.

MarketplaceService.ProcessReceipt = DataService:CreateReceiptProcessor(PlayerData, {
	[1234567] = function(profile)
		profile:Increment("Coins", 500)
	end,
})

MonetizationService offers a complete purchase system on top of this.

Stores

DataService:CreateStore(name: string, scope: string?): Store

A plain DataStore with retries and request budgeting. GetStore and FindStore look it up again.

All return Promises. Calls are retried RetryAttempts times with backoff, and wait for request budget when the server is close to its DataStore limits.

Extended stores

DataService:CreateExtendedStore(name: string, scope: string?): ExtendedStore

One DataStore key holds at most 4 MB. An ExtendedStore keeps entries that need more room, such as the build on a plot. Every entry has one master key with Data, the small essential data you choose (author, name, ...), and named sections for the big data. Each section is saved in keys of its own, and a section bigger than one key is split over several. GetExtendedStore and FindExtendedStore look a store up again.

local Plots = DataService:CreateExtendedStore("Plots")

-- When the plot is claimed
Plots:CreateAsync(plotKey, { Owner = player.UserId, Name = "My base" })

-- Every save
Plots:SetSectionAsync(plotKey, "Build", serializeBuild(plot))

-- Loading
Plots:GetAsync(plotKey):andThen(function(data, info)
	if data then
		print(data.Name, "was last saved at", info.UpdatedAt)
	end
end)

Plots:GetSectionAsync(plotKey, "Build"):andThen(function(build)
	if build then
		loadBuild(plot, build)
	end
end)

ExtendedStore

Every method returns a Promise.

CreateAsync is the only method that creates an entry. SetAsync, UpdateAsync, SetSectionAsync and SetSectionsAsync on an entry that does not exist reject with "the entry does not exist" and write nothing. Reading or removing something that does not exist changes nothing, and a read resolves nil.

info is read-only: { CreatedAt, UpdatedAt, Revision, Sections }, where Sections is { [name] = { Size, KeyCount, UpdatedAt } }. Times are Unix seconds and Size is in characters.

data must be a table that a DataStore can store (see Patch.Validate). A section can hold any storable value; remove one with RemoveSectionAsync, not by saving nil. Keys and section names are at most 50 characters. The master key holds Data and the list of sections, so it must stay under 4 MB itself: keep big values in sections.

Safe saving

• A section is written to new keys first, and the master key switches to them in one atomic update. A failed or interrupted save never leaves half-written data: the entry keeps its previous version, and a create that fails leaves nothing behind.
• Replaced keys are removed afterwards. Keys that a crashed server left behind are removed by a later write, once they are older than ExtendedStorePendingTimeout.
• Every section is checked (size and CRC32) when it is read. A read that overlaps a save tries again on the new version, and real damage is reported as an error instead of returned.
• Writes to one key on one server run in the order they were called. A save that Roblox reports as failed although it went through is not applied twice.
• A key that holds something other than an ExtendedStore entry is never overwritten.
• The server waits for running writes when it shuts down.
• Data and sections are copied when you call the method, so changing your table afterwards does not change what is saved.

Without DataStore access it works in memory, like a Store, and IsMock is true.

Requests per call

ExtendedStoreChunkSize sets how many characters one section key holds, and ExtendedStoreParallelRequests how many section keys one call reads, writes or removes at the same time.

Ordered stores

DataService:CreateOrderedStore(name: string, scope: string?): OrderedStore

Numbers sorted by value, for all-time leaderboards: GetAsync, SetAsync, IncrementAsync, RemoveAsync, and :GetTopAsync(count, ascending?, minValue?, maxValue?), which resolves with { { Key, Value } }. For complete leaderboards with periods and boards in the world, see LeaderboardSystem.

Memory stores

Fast, temporary storage shared by all servers of the experience. Every value needs an expiration in seconds.

Each has Get... and Find... lookups.

Topics

DataService:CreateTopic(name: string): Topic

Cross-server messages through MessagingService. topic:PublishAsync(data) sends (JSON up to MessageMaxBytes), and topic.Received: Signal<(data, sentAt)> fires on every server that created the topic. :Destroy() unsubscribes.

local announcements = DataService:CreateTopic("Announcements")
announcements.Received:Connect(function(data)
	showBanner(data.Text)
end)
announcements:PublishAsync({ Text = "Double coins weekend!" })

Documents

DataService:CreateDocument(name: string, template: { [string]: any }?): Document

One shared, versioned table for the whole game, such as live event settings or a ban list. Updates are applied safely even when several servers write at once.

Service events and state

Client

On the client, DataService gives read-only access to the player's own replicated profiles and to local stores.

A client profile has Data, Version, Active, StoreName, :Get(path), :OnChange(path, fn(new, old)), Changed: Signal<(keys, new, old)> and SessionEnded. It is a copy: changing it does not change the server's data.

Local stores (client)

Local stores let the client save small per-player values, such as UI preferences or keybinds, without any server code. They are backed by a profile store on the server, size-limited and rate-limited.

local settings = DataService:CreateLocalStore("Settings")
settings:WaitForLoadAsync():andThen(function()
	musicToggle.Value = settings:Get("Music") ~= false
end)

musicToggle.Changed:Connect(function(value)
	settings:Set("Music", value)
end)

Never put anything in a local store that matters for gameplay: the client decides what goes in. The server can read a player's local stores with DataService:GetLocalProfileAsync(player).

Configuration

Types

export type Path
export type Profile
export type ProfileStore
export type StartSessionParams
export type ProfileStoreOptions
export type Migration = (data: { [string]: any }) -> ()
export type LastSaveReason = "Manual" | "External" | "Shutdown"
export type EditHandler
export type EditResult = "applied" | "queued" | "rejected" | "missing"
export type EditOptions
export type TransferHandlers
export type TransferOptions
export type Store
export type ExtendedStore
export type ExtendedKeyInfo
export type SectionInfo
export type OrderedStore
export type SortedMap
export type HashMap
export type Queue
export type Topic
export type Document
export type ReceiptHandlers
export type ReceiptProcessor
export type DataStoreState = "NotReady" | "NoInternet" | "NoAccess" | "Access"