15 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

GlobalDataStore

Inherits from: Instance → Object

A GlobalDataStore exposes functions for saving and loading data for the DataStoreService.

See Data stores for an in-depth guide on data structure, management, error handling, limits, and more.

Ordered data stores do not support versioning and metadata, so DataStoreKeyInfo is always nil for keys in an OrderedDataStore. If you need versioning and metadata support, use a DataStore.

Inherits from: Instance

Descendants: DataStore, OrderedDataStore

Memory category: Instances

Tags: NotCreatable, NotReplicated

Methods

Name	Type / Returns	Description
GlobalDataStore:BatchGetAsync	Dictionary	Returns the values of multiple keys from the data store in a single request.
GlobalDataStore:GetAsync	Tuple	Returns the value of a key in a specified data store and a `DataStoreKeyInfo` instance.
GlobalDataStore:IncrementAsync	Variant	Increments the value of a key by the provided amount (both must be integers).
GlobalDataStore:OnUpdate	RBXScriptConnection	Sets a callback function to be executed any time the value associated with a key is changed.
GlobalDataStore:RemoveAsync	Tuple	Removes the specified key while also retaining an accessible version.
GlobalDataStore:SetAsync	Variant	Sets the value of the data store for the given key.
GlobalDataStore:UpdateAsync	Tuple	Updates a key's value with a new value from the specified callback function.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

GlobalDataStore:BatchGetAsync

This function retrieves the values of multiple keys in a single request.

This method is currently only supported on OrderedDataStore. Calling it on a standard GlobalDataStore or DataStore will throw an error.

Unlike GlobalDataStore:GetAsync(), this method does not return DataStoreKeyInfo since ordered data stores do not support versioning or metadata.

The returned dictionary maps each key to a table with a value field. For example, if you request keys {"coins", "gems"}, the result might look like:

{
    coins = { value = 100 },
    gems = { value = 50 }
}

Keys that do not exist in the data store or have empty values are omitted from the result rather than returning nil values.

Limits

The keys array must contain at least one key and no more than the server-configured maximum (default 100). Exceeding the limit will throw an error. Each call counts against the ordered data store read budget based on the number of keys requested.

Parameters

Name	Type	Default	Description
keys	Array		An array of key name strings to retrieve. The maximum number of keys per request is determined by a server-side limit (default 100).
options	Dictionary	nil	(Optional) Unused; has no effect.

Returns

Type	Description
Dictionary	A dictionary mapping each requested key (string) to a table containing a `value` field with the key's current value. Keys that don't exist or have no value are omitted from the result.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["DataStore"]

Code samples: View on Creator Hub (GlobalDataStore-BatchGetAsync1).

GlobalDataStore:GetAsync

This function returns the latest value of the provided key and a DataStoreKeyInfo instance. If the key does not exist or if the latest version has been marked as deleted, both return values will be nil.

Keys are cached locally for 4 seconds after the first read. A GlobalDataStore:GetAsync() call within these 4 seconds returns a value from the cache. Modifications to the key by GlobalDataStore:SetAsync() or GlobalDataStore:UpdateAsync() apply to the cache immediately and restart the 4 second timer.

To get a specific version, such as a version before the latest, use DataStore:GetVersionAsync().

Parameters

Name	Type	Default	Description
key	string		The key name for which the value is requested. If `DataStoreOptions.AllScopes` was set to true when accessing the data store through `DataStoreService:GetDataStore()`, this key name must be prepended with the original scope as in "scope/key".
options	DataStoreGetOptions	nil	(Optional) A `DataStoreGetOptions` instance that controls aspects of the read, such as whether to bypass the locally cached value via its `DataStoreGetOptions.UseCache` property.

Returns

Type	Description
Tuple	The value of the entry in the data store with the given key and a `DataStoreKeyInfo` instance that includes the version number, date and time the version was created, and functions to retrieve `UserIds` and metadata.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["DataStore"]

GlobalDataStore:IncrementAsync

This function increments the value of a key by the provided amount (both must be integers).

Values in GlobalDataStores are versioned as outlined in versioning. OrderedDataStores do not support versioning, so calling this method on an ordered data store key will overwrite the current value with the incremented value and make previous versions inaccessible.

Parameters

Name	Type	Default	Description
key	string		Key name for which the value should be updated. If `DataStoreOptions.AllScopes` was set to true when accessing the data store through `DataStoreService:GetDataStore()`, this key name must be prepended with the original scope as in "scope/key".
delta	int	1	Amount to increment the current value by.
userIds	Array	{}	(Optional) A table of `UserIds` to associate with the key.
options	DataStoreIncrementOptions	nil	(Optional) `DataStoreIncrementOptions` instance that combines multiple additional parameters as custom metadata and allows for future extensibility.

Returns

Type	Description
Variant	The updated value of the entry in the data store with the given key.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["DataStore"]

GlobalDataStore:OnUpdate

Deprecated. This function has been deprecated and should not be used in new work. You can use the Cross Server Messaging Service to publish and subscribe to topics to receive near real-time updates, completely replacing the need for this function.

This function sets callback as the function to be run any time the value associated with the key changes. Once every minute, OnUpdate polls for changes by other servers. Changes made on the same server will run the function immediately. In other words, functions like IncrementAsync(), SetAsync(), and UpdateAsync() change the key's value in the data store and will cause the function to run.

It's recommended that you disconnect the connection when the subscription to the key is no longer needed.

Parameters

Name	Type	Default	Description
key	string		The key identifying the entry being retrieved from the data store.
callback	Function		The function to be executed any time the value associated with key is changed.

Returns

Type	Description
RBXScriptConnection	The connection to the key being tracked for updates.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe
capabilities	["DataStore"]

Code samples: View on Creator Hub (GlobalDataStore-OnUpdate1).

GlobalDataStore:RemoveAsync

This function marks the specified key as deleted by creating a new "tombstone" version of the key. Prior to this, it returns the latest version prior to the remove call.

After a key is removed via this function, GlobalDataStore:GetAsync() calls for the key will return nil. Older versions of the key remain accessible through DataStore:ListVersionsAsync() and DataStore:GetVersionAsync(), assuming they have not expired.

OrderedDataStore does not support versioning, so calling RemoveAsync() on an OrderedDataStore key will permanently delete it.

Removed objects will be deleted permanently after 30 days.

If the previous values were already deleted via GlobalDataStore:RemoveAsync() or DataStore:RemoveVersionAsync(), the function will return nil, nil for value and DataStoreKeyInfo respectively.

Parameters

Name	Type	Default	Description
key	string		Key name to be removed. If `DataStoreOptions.AllScopes` was set to true when accessing the data store through `DataStoreService:GetDataStore()`, this key name must be prepended with the original scope as in "scope/key".

Returns

Type	Description
Tuple	The value of the data store prior to deletion and a `DataStoreKeyInfo` instance that includes the version number, date and time the version was created, and functions to retrieve `UserIds` and metadata.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["DataStore"]

GlobalDataStore:SetAsync

This function sets the latest value, UserIds, and metadata for the given key.

Metadata definitions must always be updated with a value, even if there are no changes to the current value; otherwise the current value will be lost.

Any string being stored in a data store must be valid UTF-8. In UTF-8, values greater than 127 are used exclusively for encoding multi-byte codepoints, so a single byte greater than 127 will not be valid UTF-8 and the GlobalDataStore:SetAsync() attempt will fail.

Set vs. Update

GlobalDataStore:SetAsync() is best for a quick update of a specific key, and it only counts against the write limit. However, it may cause data inconsistency if two servers attempt to set the same key at the same time. GlobalDataStore:UpdateAsync() is safer for handling multi-server attempts because it reads the current key value (from whatever server last updated it) before making any changes. However, it's somewhat slower because it reads before it writes, and it also counts against both the read and write limit.

Parameters

Name	Type	Default	Description
key	string		Key name for which the value should be set. If `DataStoreOptions.AllScopes` was set to true when accessing the data store through `DataStoreService:GetDataStore()`, this key name must be prepended with the original scope as in "scope/key".
value	Variant		The value that the data store key will be set to.
userIds	Array	{}	Table of `UserIds`, highly recommended to assist with GDPR tracking/removal.
options	DataStoreSetOptions	nil	(Optional) `DataStoreSetOptions` instance that allows for metadata specification on the key.

Returns

Type	Description
Variant	The version identifier of the newly created version. It can be used to retrieve key info using `GetVersionAsync()` or to remove it using `RemoveVersionAsync()`.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["DataStore"]

GlobalDataStore:UpdateAsync

This function retrieves the value and metadata of a key from the data store and updates it with a new value determined by the callback function specified through the second parameter. If the callback returns nil, the write operation is cancelled and the value remains unchanged.

In cases where another game server updated the key in the short timespan between retrieving the key's current value and setting the key's value, GlobalDataStore:UpdateAsync() will call the function again, discarding the result of the previous call. The function will be called as many times as needed until the data is saved or until the callback function returns nil. This can be used to ensure that no data is overwritten.

Set vs. Update

Callback Function

The callback function accepts two arguments:

Current value of the key prior to the update.
DataStoreKeyInfo instance that contains the latest version information (this argument can be ignored if metadata is not being used).

In turn, the callback function returns up to three values:

The new value to set for the key.
An array of UserIds to associate with the key. DataStoreKeyInfo:GetUserIds() should be returned unless the existing IDs are being changed; otherwise all existing IDs will be cleared.
A Luau table containing metadata to associate with the key. DataStoreKeyInfo:GetMetadata() should be returned unless the existing metadata is being changed; otherwise all existing metadata will be cleared.

If the callback returns nil instead, the current server will stop attempting to update the key.

The callback function cannot yield, so do not include calls like task.wait().

Parameters

Name	Type	Default	Description
key	string		Key name for which the value should be updated. If `DataStoreOptions.AllScopes` was set to true when accessing the data store through `DataStoreService:GetDataStore()`, this key name must be prepended with the original scope as in "scope/key".
transformFunction	Function		Transform function that takes the current value and `DataStoreKeyInfo` as parameters and returns the new value along with optional `UserIds` and metadata.

Returns

Type	Description
Tuple	The updated value of the entry in the data store with the given key and a `DataStoreKeyInfo` instance that includes the version number, date and time the version was created, and functions to retrieve `UserIds` and metadata.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["DataStore"]

Properties

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

Events

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.