Cloud Save Queries

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

Read time 4 minutes

Last updated a month 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 responses don't include any data you save before you create the index.

Index behavior

How you structure a compound index affects both the speed of a query and the range of queries you can run. The following sections explain how Cloud Save evaluates key order within a compound index, and the scope of queries a compound index supports.

Compound index key order

An index that uses multiple keys evaluates them in order. Cloud Save only searches records matching the first key's criteria for the second key, and so on.

The more your first constraint narrows results, the faster the query is overall.

Compound index scope

A compound index of three keys (

) lets you run queries on the first key

, without requiring you to also query keys

at the same time.

This means you don't need a separate index for

. However, you can't use this index to query keys

without also querying the earlier keys in the compound index.

If you use individual indexes instead of a compound index to search for specific records, then you run a full query per key, and then the service finds matching records by comparing the separate result sets.
Individual indexes are much slower than using a single compound index, and with larger player counts, queries take significantly longer.

Documentation

Development

User Acquisition

Monetization

Industry