Cloud Save Queries

Understand indexes and query types for both numerical and text data stored in player and game data.

Read time 2 minutes

Last updated a day 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:

Using the Cloud Save SDK for Unity, a game client can query Player Data in the Public Access Class or query Game Data stored in the Default Access Class.
Using the Cloud Save SDK for Cloud Code, or by using the CLI or Admin REST API, you can query for an indexed key in any Access Class (for example, Default, Public, Private or Protected).

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.

Important

You can only query data that you save after you create the index. Query resposes don't include any data you save before you create the index.

Documentation

Development

User Acquisition

Monetization

Industry