> 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/ordereddatastore.md).

# OrderedDataStore

OrderedDataStore : `GlobalDataStore`

## Overview

OrderedDataStore is a permanent data store that can only hold integer values, and it provides retrieval sorted by the stored values. Use it for data that requires score ordering, such as leaderboards and rankings.

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

This object can only be used in a server environment, and accessing it from the client raises an error.

GetAsync, SetAsync, IncrementAsync, UpdateAsync, and RemoveAsync inherited from GlobalDataStore are available, with the following differences compared to DataStore.

**Differences from DataStore**

* Only **integers** can be stored. Saving a decimal, string, bool, table, NaN, or Inf raises an error and leaves the existing value unchanged.
* Only integers within -(2^53 - 1) to 2^53 - 1 are saved and retrieved exactly. If a saved value cannot be represented exactly in a script, the retrieval fails.
* Version history and metadata are not supported. Once a value is overwritten or deleted, the previous value cannot be recovered.
* The second return value of GetAsync (DataStoreKeyInfo) is always nil. If the key does not exist, it returns nil, nil.
* Passing UserIds or an options argument to SetAsync or IncrementAsync raises an error. SetAsync returns nil.
* Passing a nil value to SetAsync raises an error. Use RemoveAsync to delete a key.
* The UpdateAsync callback receives only the current value as its argument and returns the new integer value directly. It returns the updated value and nil when the value is saved, and nil, nil when the callback returns nil and the write is canceled.
* Passing DataStoreGetOptions to GetAsync does not enable caching. Every retrieval sends a new request.
* It uses storage separate from a DataStore with the same name.

**Important Notes**

* The UpdateAsync callback runs again with the latest value when multiple servers update the same key at the same time, and the number of executions is not guaranteed. Do not perform external actions inside the callback.
* Calling a waiting function inside the UpdateAsync callback interrupts the callback and the value is not saved. The call returns nil, nil without an error and only leaves an error log in the Output window, so pcall cannot confirm the failure.
* A failed save call does not guarantee that the value was not saved. Retrying a failed IncrementAsync as is can add the value twice.
* A value saved on another server may briefly return the previous value.
* While the server is shutting down, new requests fail immediately, and only the last waiting request per key is processed.

## Properties

## Methods

### GetSortedAsync

Returns a DataStorePages object that lets you iterate through the stored entries, sorted by value and divided into pages.

The sort order is determined by ascending, the maximum number of entries per page by pagesize, and minValue and maxValue limit the range of values to retrieve.

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

**Important Notes**

* The order of entries with the same value is not guaranteed.
* The returned result is not a fixed snapshot taken at retrieval time. If entries are added or deleted before you load the next page, those changes are reflected, so the same entry can appear twice or be missed.
* Caching is not used, so every call sends a new request.
* This method and AdvanceToNextPageAsync have the narrowest request limit. They fail immediately instead of waiting when the limit is exceeded, so storing and sharing the retrieved result is recommended.

#### Parameters

| `boolean` ascending | <p>The sort order.</p><ul><li>Sorts from the lowest value in ascending order when true.</li><li>Sorts from the highest value in descending order when false.</li><li>Omitting it or passing nil raises an error.</li></ul>                                  |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number` pagesize   | <p>The maximum number of entries per page.</p><ul><li>Must be between 1 and 100, and a value outside this range raises an error.</li><li>There is no default value, so omitting it or passing nil raises an error.</li></ul>                                |
| `number` minValue   | <p>(Optional) The minimum value to retrieve.</p><ul><li>Entries lower than this value are excluded, and the boundary value is included.</li><li>Only integers can be specified, and passing a non-integer value such as a string raises an error.</li></ul> |
| `number` maxValue   | <p>(Optional) The maximum value to retrieve.</p><ul><li>Entries higher than this value are excluded, and the boundary value is included.</li><li>Only integers can be specified, and a value smaller than minValue raises an error.</li></ul>               |

#### Return

| `DataStorePages` | <p>A DataStorePages object holding the sorted entries divided into pages.</p><ul><li>GetCurrentPage() returns an array of tables with key (string) and value (number) fields.</li><li>If no entries match, GetCurrentPage() returns an empty table and IsFinished is true.</li></ul> |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

#### Code Samples

```lua
local DataStoreService = game:GetService("DataStoreService")
local LeaderboardStore = DataStoreService:GetOrderedDataStore("KillLeaderboard")

local success, errorMessageOrPages = pcall(function()
    return LeaderboardStore:GetSortedAsync(false, 10)
end)

if not success then
    print("errorMessage : ", errorMessageOrPages)
else
    local pages = errorMessageOrPages

    while true do
        for _, entry in ipairs(pages:GetCurrentPage()) do
            print("UserId : ", entry.key, " / Score : ", entry.value)
        end

        if pages.IsFinished then
            break
        end

        local advanceSuccess, errorMessage = pcall(function()
            pages:AdvanceToNextPageAsync()
        end)

        if not advanceSuccess then
            print("errorMessage : ", errorMessage)
            break
        end
    end
end
```

```lua
local DataStoreService = game:GetService("DataStoreService")
local LeaderboardStore = DataStoreService:GetOrderedDataStore("KillLeaderboard")

local success, errorMessageOrPages = pcall(function()
    return LeaderboardStore:GetSortedAsync(true, 50, 1000, 5000)
end)
```

## Events

## See also

{% content-ref url="/pages/faztiZVM1KMYewnGlEy3" %}
[Custom Leaderboard](/manual/script-manual/advanced-gameplay-systems/ordereddatastore.md)
{% endcontent-ref %}