Datastore¶

Datastore is a powerful storage system designed to persistently store user and game data, such as items and leaderboards. It ensures data consistency across sessions and games, allowing different servers to access and modify the same set of data. This Datastore struct contains a set of functions for manipulating data.

Functions¶

void GetAsync(string key, function callback<boolean, string, string, DatastoreKeyInfo?>)¶

SERVER ONLY

Get the latest value and its associated datastoreKeyInfo with the provided key, and call the callback function when the Get operation is completed Returns 'nil' if the key does not exist or if the latest value has been deleted

key The key for which the value is requested
callback The callback function to be executed when the Get operation is completed
1. isSuccess This parameter indicates if the request has been successful
2. message If the request has not been successful, you will get an error message
3. value The value in the datastore with the given key
4. info DatastoreKeyInfo includes the version number, date and time the version was created, and metadata if it exists

 -- example GetAsync
 local datastore = YaDatastoreAPI.GetDatastore("backpack")

 local key = "testKey"
 local function callback(isSuccess,message,value,info)
     print("whether request is success:",isSuccess)
     if isSuccess then
         print("value:",value)
         print("createAt:",info.CreateAt)
         print("updateAt:",info.UpdateAt)
         print("version:",info.Version)
         print("metadata:",info.Metadata)
     else
         print("error message:",message)
     end
 end

 datastore:GetAsync(key, callback)

void SetAsync(string key, string value, function callback<boolean, string, string, DatastoreKeyInfo?>, [string metadata])¶

SERVER ONLY

Set the latest value for the provided key, and call the callback function when the Set operation is completed

key The key for which the value should be set
value The value that will be set to. Note that you can send values of any type, including bool, string, number, and lua table.
callback The callback function to be executed when the Set operation is completed
1. isSuccess This parameter indicates if the setting has been successful
2. message If the setting has not been successful, you will get an error message
3. value The latest value in the datastore with the given key
4. info DatastoreKeyInfo includes the version number, date and time the version was created, and metadata if it exists
metadata Optional parameter. If set, it will upload the set metadata. The metadata must be a Lua table and its keys must be string

 -- example SetAsync
 local datastore = YaDatastoreAPI.GetDatastore("backpack")

 local key = "testKey"
 local value = "testValue"
 local metadata = {}
 metadata["userId"] = "123"

 local function callback(isSuccess,message,value,info)
     print("whether request is success:",isSuccess)
     if isSuccess then
         print("value:",value)
         print("createAt:",info.CreateAt)
         print("updateAt:",info.UpdateAt)
         print("version:",info.Version)
         print("metadata:",info.Metadata)
     else
         print("error message:",message)
     end
 end

 datastore:SetAsync(key, value, callback, metadata)

void IncAsync(string key, number delta, function callback<boolean, string, string, DatastoreKeyInfo?>, [string metadata])¶

SERVER ONLY

Increment the value of a key by the provided amount (both must be integers), and call the callback function when the Increment operation is completed

key The key for which the value should be updated
delta The amount to be added to the current value
callback The callback function to be executed when the Increment operation is completed
1. isSuccess This parameter indicates if the addition has been successful
2. message If the addition has not been successful, you will get an error message
3. value The latest value in the datastore with the given key
4. info DatastoreKeyInfo includes the version number, date and time the version was created, and metadata if it exists
metadata Optional parameter. If set, it will upload the set metadata. The metadata must be a Lua table and its keys must be string

 -- example IncAsync
 local datastore = YaDatastoreAPI.GetDatastore("points")

 local key = "testKey"
 local delta = 10
 local metadata = {}
 metadata["userId"] = "123"

 local function callback(isSuccess,message,value,info)
     print("whether request is success:",isSuccess)
     if isSuccess then
         print("value:",value)
         print("createAt:",info.CreateAt)
         print("updateAt:",info.UpdateAt)
         print("version:",info.Version)
         print("metadata:",info.Metadata)
     else
         print("error message:",message)
     end
 end

 datastore:IncAsync(key, value, callback, metadata)

void RemoveAsync(string key, function callback<boolean, string, string, DatastoreKeyInfo?>)¶

SERVER ONLY

Remove the value for the provided key, and call the callback function when the Remove operation is completed. Note that this function does not delete the data. If needed, removed values can be retrieved using Datastore:GetVersionAsync(). Removed objects will be permanently deleted after 30 days.

key The key for which the value should be removed
callback The callback function to be executed when the Remove operation is completed
1. isSuccess This parameter indicates if the Remove operation has been successful
2. message If the operation has not been successful, you will get an error message
3. value The value in the datastore prior to the deletion
4. info DatastoreKeyInfo includes the version number, date and time the version was created, and metadata if it exists.

 -- example RemoveAsync
 local datastore = YaDatastoreAPI.GetDatastore("backpack")

 local key = "testKey"
 local function callback(isSuccess,message,value,info)
     print("whether request is success:",isSuccess)
     if isSuccess then
         print("value:",value)
         print("createAt:",info.CreateAt)
         print("updateAt:",info.UpdateAt)
         print("version:",info.Version)
         print("metadata:",info.Metadata)
     else
         print("error message:",message)
     end
 end

 datastore:RemoveAsync(key, callback)

void GetVersionAsync(string key, string version, function callback<boolean, string, string, DatastoreKeyInfo?>)¶

SERVER ONLY

Get the specified value and its datastoreKeyInfo with the provided key and version, and call the callback function when the Get operation is completed

key The key for which the value is requested
version The version for which the value is requested
callback The callback function to be executed when the Get operation is completed
1. isSuccess This parameter indicates if the request has been successful
2. message If the request has not been successful, you will get an error message
3. value The specified value for the given key and version
4. info DatastoreKeyInfo includes the version number, date and time the version was created, and metadata if it exists

 -- example GetVersionAsync
 local datastore = YaDatastoreAPI.GetDatastore("backpack")

 local key = "testKey"

 -- The 'version' variable must already contain the version number
 local version = "testVersion"
 local function callback(isSuccess,message,value,info)
     print("whether request is success:",isSuccess)
     if isSuccess then
         print("value:",value)
         print("createAt:",info.CreateAt)
         print("updateAt:",info.UpdateAt)
         print("version:",info.Version)
         print("metadata:",info.Metadata)
     else
         print("error message:",message)
     end
 end

 datastore:GetVersionAsync(key, version, callback)

void ListKeysAsync(function callback<boolean, string, DatastoreKeyPages?>, [string prefix], [number pageSize], [number offset], [boolean excludeDeleted])¶

SERVER ONLY

Enumerate through all keys of a datastore and call the callback function when the enumeration is completed prefix is used to restrict the keyName results. excludeDeleted is used to filter out deleted keys. PageSize and Offset are used for pagination, where the former refers length of each page and the latter indicates the page offset

callback The callback function to be executed when the List operation is completed
1. isSuccess This parameter indicates if the enumeration has been successful
2. message If the enumeration has not been successful, you will get an error message
3. DatastoreKeyPages DatastoreKeyPages displays all the keys stored in the datastore, presented in a paginated format
prefix Optional parameter. Restricts the keyName results to those that match the given prefix. Default Value: ""
pageSize Optional parameter. Specifies the length of each page. Default value: 10
offset Optional parameter. Specifies the page offset. Default value: 0
excludeDeleted Optional parameter. Filters out deleted keys. Default value: false

 -- example ListKeysAsync
 local datastore = YaDatastoreAPI.GetDatastore("backpack")

 local function callback(isSuccess,message,result)
    print("whether request is success:",isSuccess)
    if isSuccess then
        for i,t in ipairs(result.Pages) do
            local keyName = t.KeyName
            print(" KeyName " .. i .. " is " .. keyName )
        end
        print(result.PageInfo.Offset)
        print(result.PageInfo.Limit)
        print(result.PageInfo.Total)
    else
        print("error message:",message)
    end
 end

 datastore:ListKeysAsync(callback)

void ListVersionsAsync(string key, function callback<boolean, string, DatastoreVersionPages?>, [boolean ascending], [number pageSize], [number offset], [number minDate], [number maxDate])¶

SERVER ONLY

Enumerate all histories of a specific key and call the callback function when the enumeration is completed

key The key for which all histories are requested
callback The callback to be executed when the enumeration is completed
1. isSuccess This parameter indicates if the request was success.
2. message If the request was not success, you will get error message.
3. DatastoreVersionPages DatastoreVersionPages displays the history of a specific key, presented in a paginated format.
ascending (Optional) Determines whether the pages are sorted in ascending order. Default value: false, meaning the descending sort order
pageSize (Optional) Specifies the length of each page. Default value: 10
offset (Optional) Specifies the page offset. Default value: 0
minDate (Optional) If set, the creation time earlier than the minDate will be excluded. Default value: 0
maxDate (Optional) If set, the creation time later than the maxDate will be excluded. Default value: INT_MAX

 -- example ListVersionsAsync
 local datastore = YaDatastoreAPI.GetDatastore("backpack")

 local key = "testKey"

 local function callback(isSuccess,message,result)
    print("whether request is success:",isSuccess)
    if isSuccess then
        for i,t in ipairs(result.Pages) do
            local version = t.Version
            local isDeleted = t.IsDeleted
            local createdTime = t.CreatedTime
            print("Key:" .. key .. "; Version:" .. version, "; Created:" .. createdTime .. "; Deleted:" .. tostring(isDeleted))
        end
        print(result.PageInfo.Offset)
        print(result.PageInfo.Limit)
        print(result.PageInfo.Total)
    else
        print("error message:",message)
    end
 end

 datastore:ListVersionsAsync(key,callback)

void RemoveVersionAsync(string key, string version, function callback<boolean, string>)¶

SERVER ONLY

Remove the specified value permanently, and call the callback function after the Remove operation is completed

key The key name for which a version is to be removed
version The version number of the key to remove
callback The callback function to be executed when the Remove operation is completed
1. isSuccess This parameter indicates if the Remove operation has been successful
2. message If the Remove operation has not been successful, you will get an error message

 -- example RemoveVersionAsync
 local datastore = YaDatastoreAPI.GetDatastore("backpack")

 local key = "testKey"

 -- The 'version' variable must already contain the version number
 local version = "testVersion"
 local function callback(isSuccess,message)
     print("whether request is success:",isSuccess)
     if not isSuccess then
         print("message:",message)
     end
 end

 datastore:RemoveVersionAsync(key, version, callback)