Cloud Save Queries
Cloud Save Queries allows you to define indexes on Player Data and Game Data (Custom Items) stored in Cloud Save so you can search / query data using Cloud Code.
Refer to the documentation for the Cloud Save SDK for Cloud Code for a list of methods for querying data in Cloud Save from Cloud Code.
Query types
The following types of queries are supported:
- EQ - Equal
- NE - Not Equal
- LT - Less Than
- LE - Less Than or Equal
- GT - Greater Than
- GE - Greater Than or Equal
Values are compared to the indexed value, lexicographically for string data, numerically for numerical data.
Sampling
Cloud Save supports returning a random sample of the total query results. To retrieve a sample, pass in sampleSize when making a query request.
Creating indexes
By default, data in Cloud Save cannot be queried. To enable querying, an index with the desired keys must be created against an access class and entity type. An index is a list of keys that are stored in a specific order.
An index can be used to query for players or custom entities that match a specific key or range of keys, both from the admin API as well as from the client API. Indexes can be listed, created, updated, and deleted using the admin API.
Indexes can be formed of individual Cloud Save keys, or multiple keys can be combined in a specific order to form a compound index. Each key is marked with a boolean to specify if the index is sorted in ascending or descending order.
You can create and manage indexes in the Unity Cloud Dashboard.
Limits
The maximum size of a value that can be indexed is 128 bytes.
Values greater than 128 bytes will not be indexed, attempting to write values greater than 128 bytes to a key that is indexed will fail (the data will still be saved to Cloud Save but the data will not be indexed).
You can define up to 20 keys which can be indexed across all indexes and across all access classes and across Player State and Game State.
This means that there can be 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.
Only data that is saved after an index has been created can be queried, data saved before an index has been created will not be included in query responses.