# GlobalDataStore GlobalDataStore : `Instance` ## Overview Provides features used to save and load data. ## 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 value of a callback function must be **single Table form** instead of Tuple. A new value, UserIds, and metadata must be included in this table in the order and returned. #### Parameters | `string` InKey | The key of which value will be updated. | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Value` InTransformFunction | A callback function that takes DataStoreKeyInfo containing currently stored value and its version information as a factor and converts values to be updated, and if necessary, UserIds and metadata to be stored together into a single table. UpdateAsync updates data based on the content of the table returned by this callback. | #### 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.overdare.com/development/api-reference/classes/globaldatastore.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.