> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/development/api-reference/classes/memorystoresortedmap.md).

# MemoryStoreSortedMap

MemoryStoreSortedMap : `Instance`

## Overview

MemoryStoreSortedMap is a sorted key-value memory store shared by multiple servers in the same world. Use it for data whose items must be retrieved in a defined order, such as real-time leaderboards.

It can only be retrieved through the MemoryStoreService:GetSortedMap() method and cannot be created with Instance.new().

This object can only be used in server Scripts, and calling it from a LocalScript raises an error.

**Keys and Sort Keys**

Each item can have a sort key (sortKey) separate from its key (key). The key is an unchanging name that identifies the item, and the sort key is the value by which the item is sorted.

In ascending order, items are sorted in the following order.

1. Items whose sort key is a number (in value order)
2. Items whose sort key is a string (in lexicographic order)
3. Items without a sort key (in key order)

Items with the same sort key are sorted by key.

**Storage Rules**

* Keys must be strings of 1 to 128 characters.
* Values must be 1 to 32,768 bytes when serialized. Saving a table with circular references or a value of a type that cannot be stored raises an error.
* String sort keys can be up to 128 characters long.
* Every item has an expiration time (in seconds), specified in the range of 0 to 3,888,000 seconds (45 days). Expired items are treated the same as items that do not exist.

**Important Notes**

* Because the storage is volatile, data may be lost when the storage restarts.
* Caching is not used, so every read and write sends a new request on each call.
* The Async methods of this object yield the calling script until the result is received. A failed request raises an error, so wrapping calls in pcall is recommended.

## Properties

## Methods

### GetAsync

Returns the value and sort key stored at the specified key.

If there is no item for the key or the item has expired, it returns nil without an error. If the request fails due to a server error or similar, it raises an error instead of returning nil.

This method yields the calling script until the result is received.

#### Parameters

| `string` InKey | The key of the item whose value to retrieve. Must be 1 to 128 characters long. |
| -------------- | ------------------------------------------------------------------------------ |

#### Return

| `Tuple` | <p>Returns the value together with the sort key.</p><ul><li>The first value is the value stored at the key.</li><li>The second value is the sort key of the item (number or string), and it is nil if there is no sort key.</li><li>If the item does not exist or has expired, both values are nil.</li></ul> |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

### GetRangeAsync

Returns the items in the specified range as an array, according to the sort order.

The result is not a Pages object but an array received in a single request, and it holds up to InCount items.

This method yields the calling script until the result is received.

**Range Rules**

* InLowerBound is the boundary at the front of the sort order and InUpperBound is the boundary at the back, and they have the same meaning regardless of the sort direction.
* If only sortKey is specified for a boundary, all items with that sort key are excluded from the result.
* If both sortKey and key are specified for a boundary, only the single item with that key is excluded from the result.
* For example, to retrieve only items whose sort key is 20, specify the immediately preceding and following sort keys as the boundaries, such as { sortKey = 10 } for InLowerBound and { sortKey = 30 } for InUpperBound.

#### Parameters

| `Value` InDirection  | <p>The sort direction.</p><ul><li>Specify Enum.SortDirection.Ascending or Enum.SortDirection.Descending.</li><li>The strings "Ascending" or "Descending" can also be used, and they are case-insensitive.</li></ul> |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number` InCount     | <p>The maximum number of items to return.</p><ul><li>Must be between 1 and 200, and a value outside this range raises an error.</li><li>If a decimal is specified, the value rounded up is applied.</li></ul>       |
| `Value` InLowerBound | <p>(Optional) The front boundary of the retrieval range.</p><ul><li>Specified as a table in the form { key = ..., sortKey = ... }.</li><li>Omitting it or passing nil retrieves without a front boundary.</li></ul> |
| `Value` InUpperBound | <p>(Optional) The back boundary of the retrieval range.</p><ul><li>Specified as a table in the form { key = ..., sortKey = ... }.</li><li>Omitting it or passing nil retrieves without a back boundary.</li></ul>   |

#### Return

| `Value` | <p>An array of the retrieved items.</p><ul><li>Each item is a table with key, value, and sortKey fields.</li><li>Items are sorted in the direction specified by InDirection.</li><li>If no items match, it returns an empty table, not nil.</li></ul> |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

### GetSizeAsync

Returns the number of stored items.

Expired items are excluded from the count. Items added or deleted while the count is being taken may or may not be included.

This method yields the calling script until the result is received.

#### Parameters

#### Return

| `Value` | The number of stored items (number). It is 0 for a store where nothing has been saved yet. |
| ------- | ------------------------------------------------------------------------------------------ |

#### Code Samples

### RemoveAsync

Deletes the item with the specified key. It is also removed from the sort order.

Deleting a key that does not exist succeeds without an error.

This method yields the calling script until the deletion is complete.

#### Parameters

| `string` InKey | The key of the item to delete. Must be 1 to 128 characters long. |
| -------------- | ---------------------------------------------------------------- |

#### Return

| `Value` | There is no return value (nil). |
| ------- | ------------------------------- |

#### Code Samples

### SetAsync

Saves a value and a sort key at the specified key. If the key already has a value, it is overwritten unconditionally.

The value and sort key are updated together. The expiration time is applied anew on every save.

This method yields the calling script until the save is complete. A failed save raises an error.

**Important Notes**

* If InSortKey is omitted, the existing sort key is not kept but deleted. To change only the value, pass the existing sort key again.

#### Parameters

| `string` InKey       | The key of the item to save the value to. Must be 1 to 128 characters long.                                                                                                                                                                                                                                                                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Value` InValue      | <p>The value to save.</p><ul><li>Must be 1 to 32,768 bytes when serialized.</li><li>Omitting it or passing nil raises an error.</li></ul>                                                                                                                                                                                                                                                                       |
| `Value` InExpiration | <p>The expiration time of the item (in seconds).</p><ul><li>Must be between 0 and 3,888,000 seconds (45 days), and decimals can also be specified.</li><li>Specifying 0 makes the item expire immediately and be deleted.</li><li>There is no default value, so omitting it or passing nil raises an error.</li></ul>                                                                                           |
| `Value` InSortKey    | <p>(Optional) The sort key of the item.</p><ul><li>Specify a number or a string (up to 128 characters).</li><li>A boolean is converted to 1 for true and 0 for false, and NaN or infinity is converted to 0.</li><li>Specifying an empty string or omitting it results in an item without a sort key.</li><li>Passing any other type, such as table, function, Vector3, or EnumItem, raises an error.</li></ul> |

#### Return

| `Value` | true if an item already existed at the key before saving, false otherwise. |
| ------- | -------------------------------------------------------------------------- |

#### Code Samples

### UpdateAsync

Reads the current value and sort key of the specified key, transforms them with a callback function, and saves the result.

If another server or script changes the same key after the value is read but before it is saved, the latest value is read again and the callback runs again. This retry is performed up to 5 times or for up to 10 seconds, and an error is raised if the value cannot be saved within that limit.

This method yields the calling script until the save is complete.

**Important Notes**

* If the callback does not return a sort key (returns only one value), the sort key is deleted. To keep the sort key, return the second argument received by the callback as is.
* The callback runs again on every retry, so the number of executions is not guaranteed. Do not perform external actions inside the callback.
* If an error occurs inside the callback, the value is not changed and UpdateAsync raises an error.
* Calling UpdateAsync again on the same key inside the callback raises an error.
* The expiration time does not keep the expiration time of the existing item; it is applied anew with the InExpiration value on every update.

#### Parameters

| `string` InKey              | The key of the item whose value to update. Must be 1 to 128 characters long.                                                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Value` InTransformFunction | <p>A function that receives the current value and sort key and returns a new value and a new sort key.</p><ul><li>Receives nil for both arguments if the item does not exist or has expired.</li><li>Returning nil as the first return value cancels the update, in which case UpdateAsync returns nil without an error.</li><li>Omitting the second return value or returning nil for it deletes the sort key.</li><li>Passing a value that is not a function raises an error.</li></ul> |
| `Value` InExpiration        | <p>The expiration time of the updated item (in seconds).</p><ul><li>Must be between 0 and 3,888,000 seconds (45 days).</li><li>Even if the item already exists, this value is applied as the new expiration time.</li><li>Specifying 0 makes the item expire immediately and be deleted.</li><li>There is no default value, so omitting it or passing nil raises an error.</li></ul>                                                                                                      |

#### Return

| `Tuple` | <p>Returns the new value that was saved together with the new sort key.</p><ul><li>If the callback returned nil and canceled the update, both values are nil.</li></ul> |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

## Events
