Documentation

Support

Cloud Save

Unity SDK tutorial

Cloud Save for Cloud Code

Open Unity Dashboard

Cloud Save

Cloud Save Queries

Understand indexes and query types for both numerical and text data stored in player and game data.
Read time 2 minutesLast updated 2 days ago
You can use Cloud Save to query both numerical and text data stored in Player Data and Game Data. You can use queries for many purposes, such as to create a guild or clan system, add matchmaking, implement an economy system or auction house, or return data for NPCs or items in a multiplayer environment.

Index creation

You need to index data in Cloud Save before you can query it. You can create and manage indexes in the Unity Dashboard, the Unity CLI or the Admin REST API. You can form indexes of individual Cloud Save keys, or combine multiple keys in a specific order to form a compound index. Cloud Save marks each key with a boolean to specify if the index is sorted in ascending or descending order. There is no additional charge for you to use indexes.

Query types

The following types of queries are supported in Cloud Save: 
  • EQ
    - Equal to
  • NE
    - Not equal to
  • LT
    - Less than
  • LE
    - Less than or equal to
  • GT
    - Greater than
  • GE
    - Greater than or equal to
Cloud save compares values to the indexed value, lexicographically for string data, numerically for numerical data.

Random sampling

Cloud Save allows you to return a random sample of results for a query, if you don't want to return the full sorted result set which you can paginate over (the default behavior). To use this feature, pass the 
sampleSize
option when you perform a query and specify the maximum number of results you want Cloud Save to return. You can use sampling for use cases such as to display a selection of possible guilds for a player to join, or to randomly match two players with similar statistics.

Limits

Limits on queries

The data that you can query from a client or server is defined by the Access Class of the key that is indexed:

Limits on indexes

  • The maximum size of a value that you can index is 128 bytes: Values greater than 128 bytes don't index; if you attempt to write values greater than 128 bytes to an indexed key,the index fails (the data still saves to Cloud Save but the data isn't indexed).
  • You can define up to 20 keys that you can index across all indexes and across all access classes and across Player State and Game State. This means that you can have up to 20 indexes with a single indexed key, or a single index with 20 keys, or any combination in between so long as the total number of indexed keys does not exceed the limit.

Additional resources