MemoryStoreSortedMap

Show Deprecated
Not Creatable
Not Replicated

Provides access to a sorted map within MemoryStore. 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. The keys are arranged in alphabetical order.

Summary

Properties

Events

Methods

GetAsync(key: string): Variant  YIELDS

Retrieves the value of a key in the sorted map.

GetRangeAsync(direction: SortDirection, count: number, exclusiveLowerBound: string, exclusiveUpperBound: string): Array  YIELDS

Retrieves items within a sorted range of keys.

RemoveAsync(key: string): void  YIELDS

Removes the provided key from the sorted map.

SetAsync(key: string, value: Variant, expiration: number): boolean  YIELDS

Sets the value of a key.

UpdateAsync(key: string, transformFunction: function, expiration: number): Variant  YIELDS

Retrieves the value of a key from a sorted map and updates it with a new value.

Properties

Events

Methods

GetAsync

Variant
Yields

Retrieves the value of a key in the sorted map.

Parameters

key: string

Key whose value to retrieve.


Returns

Variant

Key value, or nil -- if there's no item with the specified key.

GetRangeAsync

Array
Yields

Gets items within a sorted range of keys.

Parameters

direction: SortDirection

Sort direction, ascending or descending.

count: number

The number of items to retrieve; the maximum allowed value for this parameter is 200.

exclusiveLowerBound: string

(Optional) Lower bound, exclusive, for the returned keys.

Default Value: ""
exclusiveUpperBound: string

(Optional) Upper bound, exclusive, for the returned keys.

Default Value: ""

Returns

Array

Item keys and values in the requested range.

Code Samples

Retrieving MemoryStore Keys
1local MemoryStoreService = game:GetService("MemoryStoreService")

2

3local myMap = MemoryStoreService:GetSortedMap("MySortedMap")

4

5function printAllKeys(map)

6	-- the initial lower bound is nil which means to start from the very first item

7	local exclusiveLowerBound = nil

8

9	-- this loop continues until the end of the map is reached

10	while true do

11		-- get up to a hundred items starting from the current lower bound

12		local items = map:GetRangeAsync(Enum.SortDirection.Ascending, 100, exclusiveLowerBound)

13

14		for _, item in ipairs(items) do

15			print(item.key)

16		end

17

18		-- if the call returned less than a hundred items it means we've reached the end of the map

19		if #items < 100 then

20			break

21		end

22

23		-- the last retrieved key is the exclusive lower bound for the next iteration

24		exclusiveLowerBound = items[#items].key

25	end

26end

27

28printAllKeys(myMap)

RemoveAsync

void
Yields

Removes the provided key from the sorted map.

Parameters

key: string

Key to remove.


Returns

void

No return.

SetAsync

boolean
Yields

Sets the value of the key overwriting any existing key value.

Parameters

key: string

Key whose value to set.

value: Variant

Key value to set.

expiration: number

Item expiration, in seconds. The item is automatically removed from the sorted map once the expiration duration is reached. The maximum expiration time is 30 days (2,592,000 seconds).


Returns

boolean

True if a new item was added, false -- if an existing item was updated.

UpdateAsync

Variant
Yields

Retrieves the value of a key from a sorted map and lets you update it to a new value via a callback function.

This method accepts a callback function that transforms the old value into the updated value as required. The method retrieves the existing key value and passes it to the transform function which returns the new value for the item, with these exceptions:

  • If the key does not exist, the old value passed to the function will be nil.
  • If the function returns nil, the update is canceled.

The new value 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 did change, the transform function is invoked again with the most recent item value. This cycle repeats until the value is saved successfully or the transform function returns nil to abort the operation.

Parameters

key: string

Key whose value to update.

transformFunction: function

A function which you need to provide. The function takes the key's old value as input and returns the new value.

expiration: number

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

Variant

The return value is the last value returned by the transform function.

Code Samples

Updating a MemoryStore
1local MemoryStoreService = game:GetService("MemoryStoreService")

2local map = MemoryStoreService:GetSortedMap("AuctionItems")

3

4function placeBid(itemKey, bidAmount)

5	map:UpdateAsync(itemKey, function(item)

6		item = item or { highestBid = 0 }

7		if item.highestBid < bidAmount then

8			item.highestBid = bidAmount

9			return item

10		end

11		return nil

12	end)

13end

14

15placeBid("MyItem", 50)