Data & Memory Stores

This reference documents APIs relating to Data Stores and Memory Stores in experiences (universes). These classes are returned by methods in Experience or by other classes within.

`rblxopencloud.DataStore`

Represents a regular data store in an experience.

Attributes:

Name	Type	Description
`name`	`str`	The datastore's name.
`scope`	`Optional[str]`	The datastore's scope. `scope/key` syntax is required for keys when scope is `None`.
`experience`	`Experience`	The experience this DataStore is a part of.
`state`	`DataStoreState`	Whether the datastore is active or scheduled for deletion. Will always be `Unknown` if not returned by `Experience.list_datastores`.
`created_at`	`Optional[datetime]`	When the datastore was created.
`expires_at`	`Optional[datetime]`	When the datastore is scheduled to be permanently deleted.

`delete()`

Schedules a datastore for deletion. To prevent accidental loss of data, Roblox delays deletion by 30 days. After this period, the datastore and all its contents are permanently deleted. All requests to access or edit the DataStore will fail while it is scheduled for deletion.

The datastore can be restored within the 30-day period by calling DataStore.undelete.

`undelete()`

Cancels the scheduled deletion of the datastore.

`list_keys(prefix='', limit=None, show_deleted=False)`

Iterates all keys in the database and scope, optionally matching a prefix.

Parameters:

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

`get_entry(key)`

Gets the value of a key in the scope and datastore.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to fetch. If `DataStore.scope` is `None`, this must include the scope in the `scope/key` syntax.	required

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

Sets the value of a key in the datastore and scope.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to update. If `DataStore.scope` is `None`, this must include the scope in the `scope/key` syntax.	required
`value`	`Union[str, dict, list, int, float]`	The new value to set.	required
`users`	`Optional[list[int]]`	A list of Roblox user IDs to attach to the entry.	`None`
`metadata`	`dict`	A key-value pair of metadata to attach to the entry.	`{}`
`exclusive_create`	`bool`	Whether to update the entry if it already has a value. If `True` and it already has a value, `PreconditionFailed` is raised.	`False`
`previous_version`	`Optional[str]`	The expected previous version ID. If provided, and the previous version doesn't match, `PreconditionFailed` is raised.	`None`

`increment_entry(key, delta, users=None, metadata={})`

Increments the value of a key in the datastore and scope.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to increment. If `DataStore.scope` is `None`, this must include the scope in the `scope/key` syntax.	required
`delta`	`Union[int, float]`	The number to increment the value by. Use negative numbers to decrement the value.	required
`users`	`Optional[list[int]]`	a list of Roblox user IDs to attach to the entry.	`None`
`metadata`	`dict`	a dict of metadata to attach to the entry.	`{}`

`remove_entry(key)`

Removes the value of a key from the datastore and scope.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to remove. If `DataStore.scope` is `None`, this must include the scope in the `scope/key` syntax.	required

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

Iterates all available versions of a key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to find versions. If `DataStore.scope` is `None`, this must include the scope in the `scope/key` syntax.	required
`after`	`datetime`	Filters versions to only those created after this time.	`None`
`before`	`datetime`	Filters versions to only those created before this time.	`None`
`limit`	`int`	Maximum number of versions to iterate.	`None`
`descending`	`bool`	When `True` versions are iterated oldest first.	`True`

`get_version(key, version)`

Gets the value of a key at a specific version ID.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to get. If `DataStore.scope` is `None`, this must include the scope in the `scope/key` syntax.	required
`version`	`Union[str, datetime]`	The version ID string to fetch or datetime object to get latest version at specific time.	required

`rblxopencloud.EntryInfo`

Contains data about an entry such as version ID, timestamps, users and metadata.

Attributes:

Name	Type	Description
`version`	`str`	The string ID of the entry's version
`created`	`datetime`	When this key was created
`updated`	`datetime`	When this key was last modified, or when this version was created.
`users`	`list[int]`	a list of user ids attached to this entry.
`metadata`	`dict`	the key-value pairs of metadata attached to this entry.

`rblxopencloud.EntryVersion`

Contains data about a version such as it's ID, timestamps, content length and whether this version is deleted.

Attributes:

Name	Type	Description
`version`	`str`	The string ID of this version.
`deleted`	`bool`	whether this version has been deleted.
`content_length`	`int`	The length of the value.
`created`	`datetime`	When this version was created.
`key_created`	`datetime`	When the key was first created.

Supported Operations:

Operator	Description
`==`	Whether two `EntryVersion` have the same `version` and are of the same key and scope.

`get_value()`

Gets the value of this version. Shortcut for DataStore.get_version

`rblxopencloud.ListedEntry`

Object which contains an entry's key and scope.

Attributes:

Name	Type	Description
`key`	`str`	The entry's key.
`scope`	`str`	The entry's scope, usually is `global`.

Supported Operations:

Operator	Description
`==`	Whether two `ListedEntry` have the same `key` and `scope`.

`rblxopencloud.MemoryStoreQueue`

Represents a memory store queue in an experience.

Attributes:

Name	Type	Description
`name`	`str`	The queue's name.
`experience`	`Experience`	The experience the queue belongs to.

`add_item(value, expiration_seconds=30, priority=0)`

Adds a value to the queue.

Parameters:

Name	Type	Description	Default
`value`	`Union[str, dict, list, int, float]`	The value to be added to the queue.	required
`expiration_seconds`	`int`	The number of seconds for the value to stay in the queue.	`30`
`priority`	`float`	The value's priority. Keys with higher priorities leave the queue first.	`0`

`read_items(count=1, all_or_nothing=False, invisibility_seconds=30)`

Reads values from the queue.

Parameters:

Name	Type	Description	Default
`count`	`int`	The number of values to return	`1`
`all_or_nothing`	`bool`	Wether to return nothing if there isn't enough items in the queue to fullfill the requested `count`.	`False`
`invisibility_seconds`	`int`	The number of seconds the items in the queue should be invisible from further read requests.	`30`

Returns:

Type	Description
`tuple[list[Union[str, dict, list, int, float]], Optional[str]]`	A list of values as the first parameter and a readid string as the second parameter. The read ID string can be passed to `MemoryStoreQueue.remove_items` .

`remove_items(read_id)`

Permanently removes previously read values from the queue.

Parameters:

Name	Type	Description	Default
`read_id`	`str`	The read ID returned by `MemoryStoreQueue.read_items` .	required

`rblxopencloud.OrderedDataStore`

Represents an ordered data store in an experience.

Attributes:

Name	Type	Description
`name`	`str`	The ordered data store's name.
`scope`	`str`	The ordered data store's scope. If `None`, `scope/key` syntax must be used for keys.
`experience`	`Experience`	The experience this ordered data store is a part of.

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

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

Parameters:

Name	Type	Description	Default
`descending`	`bool`	whether the largest or the smallest number should be first.	`True`
`limit`	`Optional[int]`	Max number of entries to loop through.	`None`
`min`	`int`	Minimum entry value to retrieve	`None`
`max`	`int`	Maximum entry value to retrieve.	`None`

Note

OrderedDataStore.scope must not be None to sort keys. It is not possible to sort keys from all scopes.

`get_entry(key)`

Gets the value of a key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to find. If `OrderedDataStore.scope` is `None`, this must include the scope in the `scope/key` syntax.	required

`set_entry(key, value, exclusive_create=False, exclusive_update=False)`

Sets the value of a key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to create or update. If `OrderedDataStore.scope` is `None`, this must include the scope in the `scope/key` syntax.	required
`value`	`int`	The new integer value. Must be positive.	required
`exclusive_create`	`bool`	whether to fail if the key already has a value.	`False`
`exclusive_update`	`bool`	whether to fail if the key does not have a value.	`False`

`increment_entry(key, delta)`

Increments the value of a key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to increment.	required
`delta`	`int`	The amount to increment the key by. Negative numbers will decrease the value.	required

`remove_entry(key)`

Removes a key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to remove.	required

`rblxopencloud.SortedEntry`

Object which contains a sorted entry's key, scope, and value.

Attributes:

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

Supported Operations:

Operator	Description
`==`	Whether two `SortedEntry` have the same `key`, `scope` and `value`.

`rblxopencloud.SortedMap`

Represents a sorted map memory store in an experience.

Attributes:

Name	Type	Description
`name`	`str`	The sorted map's name.
`experience`	`Experience`	The experience the sorted map is a part of.

`list_keys(descending=False, limit=None, lower_bound_key=None, upper_bound_key=None, lower_bound_sort_key=None, upper_bound_sort_key=None)`

Returns an Iterable of keys in the sorted map.

Parameters:

Name	Type	Description	Default
`descending`	`bool`	Wether to return keys in descending order.	`False`
`limit`	`int`	Will not return more keys than this number. Set to `None` for no limit.	`None`
`lower_bound_key`	`Union[str, int]`	Only return values with key names greater than this value.	`None`
`upper_bound_key`	`Union[str, int]`	Only return values with key names less than this value.	`None`
`lower_bound_sort_key`	`Union[str, int]`	Only return values with sort keys greater than this value.	`None`
`upper_bound_sort_key`	`Union[str, int]`	Only return values with sort keys less than this value.	`None`

Yields:

Type	Description
`Iterable[SortedMapEntry]`	A sorted map entry representing for each entry in the sorted map.

`get_key(key)`

Fetches the value of a key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to find.	required

Returns:

Type	Description
`SortedMapEntry`	The entry information.

`set_key(key, value, expiration_seconds, sort_key=None, exclusive_create=False, exclusive_update=False)`

Creates or updates the provided key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to be created or updated.	required
`value`	`Union[str, dict, list, int, float]`	The new value of the key.	required
`expiration_seconds`	`int`	The number of seconds for the entry to live. Can not be greater than 3,888,000 seconds.	required
`sort_key`	`Union[int, float, str]`	The sort key used for sorting.	`None`
`exclusive_create`	`bool`	Wether to fail if the key already has a value.	`False`
`exclusive_update`	`bool`	Wether to fail if the key doesn't have a value.	`False`

Returns:

Type	Description
`SortedMapEntry`	The new entry information.

`remove_key(key, etag=None)`

Deletes a key from the sorted map.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to remove.	required
`etag`	`str`	Only delete if the current etag is the same as the provided value. Etag can be retrieved from `SortedMapEntry.etag`.	`None`

`rblxopencloud.SortedMapEntry`

Represents an entry in a sorted map.

Attributes:

Name	Type	Description
`key`	`str`	The entry's key.
`sort_key`	`Optional[Union[int, float, str]]`	The numeric or string key used to sort the entry.
`scope`	`Optional[Union[int, float, str]]`	The entry's scope.
`value`	`int`	The value of the entry.
`etag`	`str`	A server generated value for preconditional updating.
`expires_at`	`datetime`	The timestamp the entry will expire at.