MemoryStoreSortedMap
Provides access to a sorted map within MemoryStoreService. A sorted map is a collection of items where string keys are associated with arbitrary values (up to the maximum allowed size -- see Memory Stores). Each item can also have an optional sort key, which can be a number or a string. In the ordering of items, the sort key, if provided, takes precedence over the key. Items with numeric sort keys are sorted before items with string sort keys, which are sorted before items with no sort key. Items with the same sort key and items with no sort key are arranged in alphabetical order by key.
Summary
Methods
Retrieves the value and sort key of a key in the sorted map.
- GetRangeAsync(direction : Enum.SortDirection,count : number,exclusiveLowerBound : Variant,exclusiveUpperBound : Variant):Array
Retrieves items within a sorted range of keys and sort keys.
Gets the size of the sorted map.
Removes the provided key from the sorted map.
Sets the value of a key.
Retrieves the value and sort key of a key from a sorted map and updates it with a new value and sort key.
Properties
Methods
GetAsync
Retrieves the value and sort key of a key in the sorted map.
Parameters
Key whose value and sort key to retrieve.
Returns
A tuple of two values:
- Key value, or nil if there's no item with the specified key.
- Sort key, or nil if there's no sort key associated with the specified key.
GetRangeAsync
Gets items within a sorted range of keys and sort keys.
Parameters
Sort direction, ascending or descending.
The number of items to retrieve; the maximum allowed value for this parameter is 200.
(Optional) Lower bound, exclusive, for the returned keys. This is provided as a table where one or both of key and sort key can be specified: { key: string, sortKey: Variant } .
(Optional) Upper bound, exclusive, for the returned keys. This is provided as a table where one or both of key and sort key can be specified: { key: string, sortKey: Variant } .
Returns
Item keys, values and sort keys in the requested range.
Code Samples
The code below prints all keys in a sorted map in alphabetical order with the help of the MemoryStoreSortedMap:GetRangeAsync() method.
local MemoryStoreService = game:GetService("MemoryStoreService")
local myMap = MemoryStoreService:GetSortedMap("MySortedMap")
function printAllKeys(map)
-- the initial lower bound is nil which means to start from the very first item
local exclusiveLowerBound = nil
-- this loop continues until the end of the map is reached
while true do
-- get up to a hundred items starting from the current lower bound
local items = map:GetRangeAsync(Enum.SortDirection.Ascending, 100, exclusiveLowerBound)
for _, item in ipairs(items) do
print(item.key)
print(item.sortKey)
end
-- if the call returned less than a hundred items it means we've reached the end of the map
if #items < 100 then
break
end
-- the last retrieved key is the exclusive lower bound for the next iteration
exclusiveLowerBound = {}
exclusiveLowerBound["key"] = items[#items].key
exclusiveLowerBound["sortKey"] = items[#items].sortKey
end
end
printAllKeys(myMap)RemoveAsync
Removes the provided key from the sorted map.
Parameters
Key to remove.
Returns
SetAsync
Sets the value and sort key of the key overwriting any existing key value and sort key.
Parameters
Key whose value to set.
Key value to set.
Item expiration, in seconds. The item is automatically removed from the sorted map once the expiration duration is reached. The maximum expiration time is 45 days (3,888,000 seconds).
(Optional) Sort key to set for this key. Accepted types are a number (integer or decimal) or a string.
Returns
UpdateAsync
Retrieves the value and sort key of a key from a sorted map and lets you update it to a new value and sort key via a callback function.
This method accepts a callback function that transforms the old value and old sort key into the updated value and updated sort key as required. The method retrieves the existing key value and sort key and passes it to the transform function which returns the new value and sort key for the item, with these exceptions:
- If the key does not exist, the old value and old sort key passed to the function will be nil.
- If the function returns nil, the update is canceled.
The new value and new sort key is saved only if the key was not updated (e.g. by a different game server) since the moment it was read. If the value or sort key did change, the transform function is invoked again with the most recent item value and sort key. This cycle repeats until the value and sort key are saved successfully or the transform function returns nil to abort the operation.
Parameters
Key whose value to update.
A function which you need to provide. The function takes the key's old value and old sort key as input and returns the new value and new sort key.
Item expiration time, in seconds, after which the item will be automatically removed from the sorted map. The maximum expiration time is 45 days (3,888,000 seconds).
Returns
The return value is a tuple of the last value and sort key returned by the transform function.
Code Samples
The code below updates the score in a leaderboard for a player in a game. The score is calculated as kills / deaths. The use of MemoryStoreSortedMap:UpdateAsync() ensures that the kills and deaths are updated for the most recent values even if multiple game servers update the same item simultaneously. A player's kills and deaths are monotonically increasing values and can hence only increase in value in a session.
local MemoryStoreService = game:GetService("MemoryStoreService")
local map = MemoryStoreService:GetSortedMap("Leaderboard")
local Players = game:GetService("Players")
function updateLeaderboard(itemKey, killsToAdd, deathsToAdd)
local success, newStats, newScore = pcall(function()
return map:UpdateAsync(itemKey, function(playerStats, playerScore)
playerStats = playerStats or { kills = 0, deaths = 0 }
playerStats.kills += killsToAdd
playerStats.deaths += deathsToAdd
if playerStats then
-- `playerScore` is the sortKey being used to sort items in the map
playerScore = playerStats.kills / math.max(playerStats.deaths, 1)
return playerStats, playerScore
end
return nil
end, 30)
end)
end
-- Add one kill to all players
for i, player in pairs(Players:GetPlayers()) do
updateLeaderboard(player.UserId, 1, 0)
end
-- Add 5 kills and 1 death to player with userId 12345
updateLeaderboard(12345, 5, 1)