DataStoreService
DataStoreService exposes methods for getting GlobalDataStore and OrderedDataStore objects. Data stores can only be accessed by game servers, so you can only use DataStoreService within a Script or a ModuleScript that is used by a Script.
See Data Stores for an in-depth guide on data structure, management, error handling, etc.
Code Samples
1local DataStoreService = game:GetService("DataStoreService")
2
3for _, enumItem in pairs(Enum.DataStoreRequestType:GetEnumItems()) do
4 print(enumItem.Name, DataStoreService:GetRequestBudgetForRequestType(enumItem))
5endSummary
Properties
Sets whether data store functions should automatically retry or not. DataStoreService does not respect this property because automatic retry has been disabled due to technical reasons. Therefore, you must implement systems for retrying operations yourself.
Events
Methods
Creates a GlobalDataStore instance with the provided name and scope.
Get an OrderedDataStore given a name and optional scope.
Returns the number of requests that can be made by the given request type.
Returns a DataStoreListingPages object for enumerating through all of the experience's data stores.
Properties
AutomaticRetry
Sets whether data store functions should automatically retry or not.
DataStoreService does not respect this property because automatic retry has been disabled due to technical reasons. Therefore, you must implement systems for retrying operations yourself. It is possible that automatic retry will be enabled again in the future.
Events
Methods
GetDataStore
This function creates a DataStore instance with the provided name and scope. Subsequent calls to this method with the same name/scope will return the same object.
Using the scope parameter will restrict operations to that scope by automatically prepending the scope to keys in all operations done on the data store. This function also accepts an optional DataStoreOptions instance which includes options for enabling AllScopes. See Data Stores for details on scope.
Parameters
Name of the data store.
(Optional) A string specifying the scope.
(Optional) A DataStoreOptions instance to enable experimental features and v2 API features.
Returns
A GlobalDataStore instance with provided name and optional scope.
GetGlobalDataStore
This function returns the default GlobalDataStore. If you want to access a specific named data store instead, you should use the DataStoreService:GetDataStore() function.
Returns
Code Samples
1local DataStoreService = game:GetService("DataStoreService")
2
3local GlobalDataStore = DataStoreService:GetGlobalDataStore()
4
5print(GlobalDataStore.Name)GetOrderedDataStore
This method returns an OrderedDataStore, similar to the way DataStoreService:GetDataStore() does with GlobalDataStores. Subsequent calls to this method with the same name/scope will return the same object.
Returns
Code Samples
1local DataStoreService = game:GetService("DataStoreService")
2local pointsStore = DataStoreService:GetOrderedDataStore("Points")
3
4local function printTopTenPlayers()
5 local isAscending = false
6 local pageSize = 10
7 local pages = pointsStore:GetSortedAsync(isAscending, pageSize)
8 local topTen = pages:GetCurrentPage()
9
10 -- The data in 'topTen' is stored with the index being the index on the page
11 -- For each item, 'data.key' is the key in the OrderedDataStore and 'data.value' is the value
12 for rank, data in ipairs(topTen) do
13 local name = data.key
14 local points = data.value
15 print(name .. " is ranked #" .. rank .. " with " .. points .. "points")
16 end
17
18 -- Potentially load the next page...
19 --pages:AdvanceToNextPageAsync()
20end
21
22-- Create some data
23pointsStore:SetAsync("Alex", 55)
24pointsStore:SetAsync("Charley", 32)
25pointsStore:SetAsync("Sydney", 68)
26
27-- Display the top ten players
28printTopTenPlayers()GetRequestBudgetForRequestType
This function returns the number of data store requests that the current place can make based on the given DataStoreRequestType. Any requests made that exceed this budget are subject to throttling. Monitoring and adjusting the frequency of data store requests using this function is recommended.
Returns
Code Samples
1local DataStoreService = game:GetService("DataStoreService")
2
3local globalStore = DataStoreService:GetGlobalDataStore()
4
5local function printBudget()
6 local budget = DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.SetIncrementAsync)
7 print("Current set/increment budget:", budget)
8end
9
10for i = 1, 5 do
11 local key = "key" .. i
12 local success, err = pcall(function()
13 globalStore:SetAsync(key, true)
14 end)
15 if success then
16 printBudget()
17 else
18 print(err)
19 end
20endListDataStoresAsync
Returns a DataStoreListingPages object for enumerating through all of the experience's data stores. It accepts an optional prefix parameter to only locate data stores whose names start with the provided prefix.
Only data stores containing at least one object will be listed via this function.
Returns
DataStoreListingPages instance containing DataStoreInfo instances that provide details such as name, creation time, and time last updated.