Data Store

rblxopencloud.DataStore

Represents a regular data store in an experience.

Warning

This class isn't designed to be created by users. It is returned by Experience.get_data_store() and Experience.list_data_stores().

Attributes:

Name	Type	Description
name	str	The data store's name.
scope	Optional[str]	The data store's scope. If it is None, then it uses the scope/key syntax.
experience	Experience	The experience the data store belongs to.
created	Optional[datetime]	The time the datetime was created. Only present if returned by Experience.list_data_stores().

list_keys(prefix='', limit=None)

Returns an Iterable of keys in the database and scope, optionally matching a prefix. Will return keys from all scopes if the scope attribute is None.

Example

This will print every key in the data store.

for key in datastore.list_keys():
    print(key.key, key.scope)

If you'd like the keys in a list, you can use the list method:

list(datastore.list_keys())

Parameters:

Name	Type	Description	Default
prefix	str	Only return keys that start with this prefix.	''
limit	Optional[int]	Will not return more keys than this number. Set to None for no limit.	None

Returns:

Type	Description
Iterable[ListedEntry]	An Iterable of all keys in the data store.

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to list data store keys, or is from an invalid IP address.
NotFound	The experience or data store does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.

get(key)

Fetches the value of a key.

Parameters:

Name	Type	Description	Default
key	str	The key to find. If scope is None, then the key should use the scope/key syntax.	required

Returns:

Type	Description
tuple[Union[str, dict, list, int, float], EntryInfo]	A tuple with the key's value in the first index, and the key's metadata as an rblxopencloud.EntryInfo() in the second index.

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to get data store keys, or is from an invalid IP address.
NotFound	The experience, data store, or entry does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.

set(key, value, users=None, metadata={}, exclusive_create=False, previous_version=None)

Sets the value of a key with the new data.

Parameters:

Name	Type	Description	Default
key	str	The key to set. If scope is None, then the key should use the scope/key syntax.	required
value	Union[str, dict, list, int, float]	The key's new value.	required
users	Optional[list[int]]	a list of Roblox user IDs to attach to the entry to assist with GDPR tracking/removal.	None
metadata	dict	A dictionary of custom metadata for the entry.	{}
exclusive_create	bool	whether to update the entry if it already has a value. Raises rblx-open-cloud.PreconditionFailed if it has a value.	False
previous_version	Optional[str]	don't update if the current version is not this value. Raises rblx-open-cloud.PreconditionFailed if it has a value.	None

Returns:

Type	Description
EntryVersion	An rblxopencloud.EntryInfo() object with information about the datastore entry.

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to create/update data store keys, or is from an invalid IP address.
NotFound	The experience, data store, or entry does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.
ValueError	previous_version and exclusive_create are both set, or the scope/key syntax wasn't used and scope is None.
PreconditionFailed	A precondition such as previous_version or exclusive_create failed.

Warning

If users and metadata parameters are not included, they will be removed from the entry.

increment(key, increment, users=None, metadata={})

Increments the value of a key with the provided number. Numbers may be negative to decrement the value.

Parameters:

Name	Type	Description	Default
key	str	The key to increment. If scope is None, then the key should use the scope/key syntax.	required
increment	Union[int, float]	The amount to increment the value. This number can be negative to decrement the value.	required
users	Optional[list[int]]	a list of Roblox user IDs to attach to the entry to assist with GDPR tracking/removal.	None
metadata	dict	A dictionary of custom metadata for the entry.	{}

Returns:

Type	Description
tuple[Union[str, dict, list, int, float], EntryInfo]	A tuple with the key's value in the first index, and the key's metadata as an rblxopencloud.EntryInfo() in the second index. The same as DataStore.get().

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to increment data store keys, or is from an invalid IP address.
NotFound	The experience, data store, or entry does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.
ValueError	The scope/key syntax wasn't used and scope is None.

Warning

If users and metadata parameters are not included, they will be removed from the entry.

remove(key)

Removes the key. The key isn't permanently deleted for 30 days after it is removed.

Parameters:

Name	Type	Description	Default
key	str	The key to remove. If scope is None, then the key should use the scope/key syntax.	required

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to remove data store keys, or is from an invalid IP address.
NotFound	The experience, data store, or entry does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.
ValueError	The scope/key syntax wasn't used and scope is None.

list_versions(key, after=None, before=None, limit=None, descending=True)

Returns an Iterable of versions avaliable for the key. Optionally within a ceartin time period.

Example

This will print every version avaliable for the key, and fetch their values.

for version in datastore.list_versions("key-name"):
    print(version, version.get_value())

If you'd like the versions in a list, you can use the list method:

list(datastore.list_versions("key-name"))

Parameters:

Name	Type	Description	Default
key	str	The key to find versions for. If scope is None, then the key should use the scope/key syntax.	required
after	Optional[datetime]	Only find versions after this datetime	None
before	Optional[datetime]	Only find versions before this datetime	None
limit	Optional[int]	Will not return more versions than this number. Set to None for no limit.	None
descending	bool	Wether the versions should be sorted by date ascending or descending.	True

Returns:

Type	Description
Iterable[EntryVersion]	An Iterable of all versions of the key.

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to list data store keys, or is from an invalid IP address.
NotFound	The experience, data store, or key does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.
ValueError	The scope/key syntax wasn't used and scope is None.

get_version(key, version)

Gets the value of a key at a specific version.

Parameters:

Name	Type	Description	Default
key	str	The key to find. If scope is None, then the key should use the scope/key syntax.	required
version	str	The ID of the version to find.	required

Returns:

Type	Description
tuple[Union[str, dict, list, int, float], EntryInfo]	A tuple with the key's value in the first index, and the key's metadata as an rblxopencloud.EntryInfo in the second index. The same as DataStore.get().

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to get data store keys, or is from an invalid IP address.
NotFound	The experience, data store, entry, or version does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.

Tip

Since DataStore.list_versions(), and DataStore.set() return rblxopencloud.EntryVersion(), you can use the EntryVersion.get_value() method as a shortcut when using those methods.

rblxopencloud.OrderedDataStore

Represents an ordered data store in an experience.

Warning

This class isn't designed to be created by users. It is returned by Experience.get_ordered_data_store().

Attributes:

Name	Type	Description
name	str	The data store's name.
scope	Optional[str]	The data store's scope. If it is None, then it uses the scope/key syntax.
experience	Experience	The experience the data store belongs to.

sort_keys(descending=True, limit=None, min=None, max=None)

Returns an Iterable of keys in order based on their value.

Example

This will print every key in the datastore.

for key in datastore.sort_keys():
    print(key.name, key.value)

If you'd like the keys in a list, you can use the list method:

list(datastore.sort_keys())

Parameters:

Name	Type	Description	Default
descending	bool	Wether the largest number should be first, or the smallest.	True
limit	Optional[int]	Will not return more keys than this number. Set to None for no limit.	None
min	int	Minimum entry value to retrieve	None
max	int	Maximum entry value to retrieve.	None

Returns:

Type	Description
Iterable[SortedEntry]	An Iterable of all keys in the data store.

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to list ordered data store keys, or is from an invalid IP address.
NotFound	The experience, data store, or key does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.
ValueError	The scope/key syntax wasn't used and scope is None.

get(key)

Gets the value of the key.

Parameters:

Name	Type	Description	Default
key	str	The key to get. If scope is None, then the key should use the scope/key syntax.	required

Returns:

Type	Description
int	The integer value of the key.

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to get ordered data store keys, or is from an invalid IP address.
NotFound	The experience, data store, or entry does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.
ValueError	The scope/key syntax wasn't used and scope is None.

set(key, value, exclusive_create=False, exclusive_update=False)

Sets the value of the key, and then returns the new value.

Parameters:

Name	Type	Description	Default
key	str	The key to get. If scope is None, then the key should use the scope/key syntax.	required
value	int	The new integer value. Must be positive.	required
exclusive_create	bool	Wether to fail if the key already has a value.	False
exclusive_update	bool	Wether to fail if the key does not have a value.	False

Returns:

Type	Description
int	The integer value of the key.

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to create/update ordered data store keys, or is from an invalid IP address.
NotFound	The experience, data store, or entry does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.
PreconditionFailed	A precondition such as exclusive_create or exclusive_update failed.
ValueError	The scope/key syntax wasn't used and scope is None, or both exclusive_create and exclusive_update are True.

increment(key, increment)

Increments the value of the key, and then returns the new value.

Parameters:

Name	Type	Description	Default
key	str	The key to get. If scope is None, then the key should use the scope/key syntax.	required
increment	int	The amount to increment the value. You can use negative numbers to decrease the value.	required

Returns:

Type	Description
int	The integer value of the key.

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to increment ordered data store keys, or is from an invalid IP address.
NotFound	The experience, data store, or entry does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.
ValueError	The scope/key syntax wasn't used and scope is None, or both exclusive_create and exclusive_update are True.

remove(key)

Removes a key.

Parameters:

Name	Type	Description	Default
key	str	The key to remove. If scope is None, then the key should use the scope/key syntax.	required

Raises:

Type	Description
InvalidKey	The API key isn't valid, doesn't have access to remove ordered data store keys, or is from an invalid IP address.
NotFound	The experience, data store, or entry does not exist.
RateLimited	You've exceeded the rate limits.
ServiceUnavailable	The Roblox servers ran into an error, or are unavailable right now.
rblx_opencloudException	Roblox returned an unexpected error.
ValueError	The scope/key syntax wasn't used and scope is None, or both exclusive_create and exclusive_update are True.

rblxopencloud.EntryInfo

Represents a Data Store entry, and contains metadata about the entry.

Warning

This class isn't designed to be created by users. It is returned by DataStore.get(), DataStore.increment(), and DataStore.get_version().

Attributes:

Name	Type	Description
version	str	The version ID of this entry.
created	datetime	The timestamp the entry was created.
updated	datetime	The timestamp the entry was last modified.
users	list[int]	A list of user IDs associated with the entry.
metadata	dict	The dictionary of custom metadata.

rblxopencloud.EntryVersion

Represents a Data Store entry version, and contains data about the version.

Warning

This class isn't designed to be created by users. It is returned by DataStore.set(), and DataStore.list_versions().

Attributes:

Name	Type	Description
version	str	The version ID of this entry.
deleted	bool	Wether this version has been marked as deleted.
content_length	int	The number of characters the value is.
created	datetime	The timestamp the version was created.
key_created	datetime	The timestamp the entry was first created.

get_value()

Gets the value of the current version. This is a shortcut for DataStore.get_version()

Returns:

Type	Description
tuple[Union[str, dict, list, int, float], EntryInfo]	A tuple with the key's value in the first index, and the key's metadata as an EntryInfo in the second index.

rblxopencloud.ListedEntry

Represents a Data Store entry iterated by DataStore.list_keys().

Warning

This class isn't designed to be created by users. It is returned by DataStore.list_keys().

Attributes:

Name	Type	Description
key	str	The entry's key.
scope	str	The entry's scope.

rblxopencloud.SortedEntry

Represents an Ordered Data Store entry when listed with OrderedDataStore.sort_keys().

Warning

This class isn't designed to be created by users. It is returned by OrderedDataStore.sort_keys().

Attributes:

Name	Type	Description
key	str	The entry's key.
scope	str	The entry's scope.
value	int	The value of the entry.