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

# GlobalDataStore

GlobalDataStore : `Instance`

## Overview

Provides features used to save and load data.

When you use these methods on an OrderedDataStore, the storable values, return values, and callback format differ, so refer to the OrderedDataStore page as well.

## Properties

## Methods

### GetAsync

Returns DataStoreKeyInfo, which contains the value stored to a specified key and information of the item.

These two values return nil if the key doesn’t exist.

#### Parameters

| `string` InKey                  | The key storing data.                                                                                                                                                                                                      |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DataStoreGetOptions` InOptions | (Optional) An options object used to control retrieval behavior. If the UseCache property is set to true and a valid cached value remains, the cached value is returned as-is without sending a new request to the server. |

#### Return

| `Tuple` | Returns the DataStoreKeyInfo object, which contains information such as version timestamp, along with the value of the specified key. |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

```lua
local DataStoreService = game:GetService("DataStoreService")
local GoldStore = DataStoreService:GetDataStore("PlayerGold")

local success, errorMessageOrLoadValue = pcall(function()
    return GoldStore:GetAsync(player.UserId)
end)
```

### IncrementAsync

Provides a feature used to increase or decrease the value stored in a key by a specified integer value. Both exiting value and value used to adjust must be integer for this feature to be processed properly. Because IncrementAsync performs atomic calculation internally, unlike SetAsync, a value is safely accrued even when multiple users are updating the value at the same time. Due to this nature, IncrementAsync is the simplest and most effective option when processing accrued number data such as coin, EXP, or score.

#### Parameters

| `string` InKey                        | The key of which value will be updated.                                                                              |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `number` InDelta                      | Represents the integer value to be added to existing value; currently stored value will be increased by this number. |
| `Array` InUserIds                     | (Optional) Metadata used to track who updated data or ID of the users affected by the change.                        |
| `DataStoreIncrementOptions` InOptions | (Optional) An object used to store additional information or metadata.                                               |

#### Return

| `Value` | The stored final key value. |
| ------- | --------------------------- |

#### Code Samples

```lua
local DataStoreService = game:GetService("DataStoreService")
local GoldStore = DataStoreService:GetDataStore("PlayerGold")

local success, errorMessageOrLoadValue = pcall(function()
    return GoldStore:IncrementAsync(player.UserId, 1)
end)
```

### RemoveAsync

Converts a certain key into the deleted status.

Once deletion is complete, GetAsync retrieving the key returns nil.

#### Parameters

| `string` InKey | The key to be deleted. |
| -------------- | ---------------------- |

#### Return

| `Tuple` | Returns the value and DataStoreKeyInfo of the removed key prior to deletion. |
| ------- | ---------------------------------------------------------------------------- |

#### Code Samples

```lua
local DataStoreService = game:GetService("DataStoreService")
local GoldStore = DataStoreService:GetDataStore("PlayerGold")

local success, errorMessage = pcall(function()
    GoldStore:RemoveAsync(player.UserId)
end)
```

### SetAsync

Overwrites the value stored in a specific key with a specified value.

SetAsync is useful when quickly updating individual keys, but when multiple servers are trying to change the same key, the values overwrite each other, resulting in an unexpected value may be stored.

For this reason, when race condition needs to be prevented while multiple users are reading and writing data simultaneously, it is safer to use methods such as IncrementAsync or UpdateAsync that support atomic process.

#### Parameters

| `string` InKey                  | The key of which value will be updated.                                                       |
| ------------------------------- | --------------------------------------------------------------------------------------------- |
| `Value` InValue                 | The value to be changed.                                                                      |
| `Value` InUserIds               | (Optional) Metadata used to track who updated data or ID of the users affected by the change. |
| `DataStoreSetOptions` InOptions | (Optional) An object used to store additional information or metadata.                        |

#### Return

| `Value` | The stored final key value. |
| ------- | --------------------------- |

#### Code Samples

```lua
local DataStoreService = game:GetService("DataStoreService")
local GoldStore = DataStoreService:GetDataStore("PlayerGold")

local success, errorMessageOrLoadValue = pcall(function()
    GoldStore:SetAsync(player.UserId, 100)
end)
```

### UpdateAsync

It reads a specific key and updates data with a new value decided by the callback function. If nil is returned during callback, task is canceled and existing data will be maintained.

If multiple requests come in simultaneously and a data conflict occurs, UpdateAsync automatically fetches the latest value and reruns the callback to resolve the conflict. This process repeats until the data is safely updated.

The callback function **returns multiple values in order**: the new value, UserIds, and metadata (`return newValue, userIds, metadata`). UserIds and metadata can be omitted.

{% hint style="warning" %}
The callback return format changed in release-40. Up to release-39, the callback returned a single table in the form `{ newValue, userIds, metadata }`, but from release-40 onward it returns multiple values. If you still return a table the old way, the entire table is stored as the value, and subsequent GetAsync calls will return `{ original data, userIds, metadata }` instead of the original data.
{% endhint %}

#### Parameters

| `string` InKey              | The key of which value will be updated.                                                                                                                                                                                                                                                                                                                                          |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Value` InTransformFunction | A callback function that receives the currently stored value and a DataStoreKeyInfo containing its version information, and returns the value to update, along with any UserIds and metadata to store with it, as multiple values in order. UpdateAsync updates the data based on the values returned by this callback, and cancels the update if the first return value is nil. |

#### Return

| `Tuple` | Returns the DataStoreKeyInfo object, which contains information such as version timestamp, along with the value of the specified key. |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

```lua
local DataStoreService = game:GetService("DataStoreService")
local GoldStore = DataStoreService:GetDataStore("PlayerGold")

local success, errorMessageOrLoadValue, keyInfo = pcall(function()
    return GoldStore:UpdateAsync(player.UserId, function(currentGold, keyInfo)
        local newGold = (currentGold or 0) + 10
        return newGold, keyInfo:GetUserIds(), keyInfo:GetMetadata()
    end)
end)
```

## Events

## See also