Game Data - Setting up Indexes

In the Configurator, you can set up Game Data Indexes for the custom data you'll persist for your game in the platform using the Game Data Service. When you set up indexed fields for your custom data in this way, you can then query them:

• Managing Game Data Indexes
• Adding a Game Data Index
• Using the Index Advisor
• Working with Game Data in Cloud Code
• Tutorials

When you’ve done this work in the Configurator to set up indexes for your data, you can insert data, either using the Data Explorer or through Cloud Code, and then query that data using those indexed fields:

• See Data Explorer.

Accessing Data by id only? If you are only going to access a game data document by id, you don't need to add and configure any indexed fields. You'll be able to find these documents by id without defining any indexed fields.

Add Indexes Later? If you add game data in the Data Explorer or through Cloud Code without first setting up indexing fields, you can add indexed fields at a later date in the Configurator. You’ll then be able to query the data documents using those indexed fields.

Managing Data Persistence? For general guidelines and best practices to help you in deciding how to organize and manage data persistence on the GameSparks platform for your game, please review the Managing Data Persistence tutorial.

FAQs? You can review Frequently Asked Questions about creating and managing your Game Data.

Managing Game Data Indexes

The Configurator>Game Data page lists the Data Types for which you've added indexed fields:

You can use the following options (highlighted above):

• Add - Add new Game Data Indexes.
• - Edit Game Data Indexes.
• - Delete Game Data Indexes.

Adding a Game Data Index

To add a new Game Data Index:

1. Click Configurator>Game Data. The Game Data page opens.

2. Click to Add a new Game Data Index. The Add Data Type Index page opens.

3. Enter the details of the custom Data Type for which you want to add indexed fields. In this example, we're going to add indexed fields for a Player Data Type:

• Short Code – Unique identifier, which is used by the API to allow you to identify the Data Type.
• Name – Name of the Data Type, which you can use to identify the Data Type in the portal.
• Description – Description of the Data Type.

Warning! The Short Code for a Data Type cannot contain an underscore character.

4. In the Indexed Fields panel, click to Add a new field for indexing the Data Type.

5. Enter the details of the indexed field:

• Short Code – Unique identifier, which you can use through the API to identify the indexed field.
• Path – The unique path of the indexed field.
• Type – Select an appropriate Type for the indexed field—two are available:
  • String
  • Number

Warning! The Short Code for an indexed field cannot contain an underscore or a period character.

6. Add any other indexed fields you want to use for querying the Data Type:

For the current example, we’ve added a total of three indexed fields:

• CITY – Type is String.
• RANK – Type is Number.
• SCORE – Type is Number.

Important! You can add a maximum of five indexed fields, at which point the Add button will be disabled.

Note: Alternatively, you can use a sample JSON document in the Index Advisor to set up your Data Type Indexes. See the following section for how to do this.

7. Click to Save and Close. You are returned to the Game Data page where the new Data Type with indexed fields is listed:

At this stage, it's important to note:

• If you don't add any indexed fields for the Data Type, you'll still be able to insert data into the Data Type but you won't be able to submit queries against the collection. The Data Type will be shown in the Data Explorer and if you open it in the Explorer, no Query button will be available.
• No data will yet have been created in the database for a brand new Data Type for which you've just added indexed fields. This will only occur when you insert data into the Data Type, either in the Data Explorer or using Cloud Code calls through the Game Data Service.
• If you've already inserted game data and created a custom Data Type, you can add indexed fields for that Data Type afterwards from this page without any conflict, and you'll then be able to query the data using those indexed fields.
• If you drop the data from a Data Type and empty it of data, this has no effect on the indexes you've set up on this page.

Using the Index Advisor

You can use the Index Advisor to add data indexes using a sample JSON document. This means you can quickly set up indexed fields for querying your custom data in those cases where you’ve already designed the data structures you want to persist against the platform.

1. Go to Configurator>Game Data and on the Game Data page, click to Edit the Data Type for which you want to set up indexing fields.

2. Under Indexed Fields, click to open the Index Advisor, which contains a JSON editor:

3. Enter the JSON document which you want to use to set up indexing fields for the Data Type. The JSON is scanned and candidate fields are listed with Path and Type entered automatically:

• If any of the fields in the JSON have already been added as indexed fields for the Data Type, then they will not be listed for addition.
• You can copy and paste your sample document into the JSON editor.

4. Click to add the field paths you want to use for indexing the Data Type. These should be the fields you want to query against, up to a maximum of five:

• For each field path you add, you must enter a Short Code.
• In this example, we’ve added two more indexing fields for the Player Data Type.

Note: The Short Code for an indexed field cannot contain an underscore character.

5. If the Type that is assigned to the field automatically is not what you want to use for querying, use the drop-down to change to the other Type. For example, in this case you might want to change the ARMOUR field to a String:

6. Click to Save and Close the Data Type Indexes you’ve set up using your sample JSON document.

Working with Game Data in Cloud Code

You can make use of the Game Data Service Cloud Code methods to store and access game data. As you enter your script, the usual script autocomplete functions in the Cloud Code editor invokes method selection and Help text:

API Documentation

For the Game Data Service API documentation pages, go to Cloud Code under API Documentation and then go to:

• Spark>getGameDataService
• SparkGameDataService

Building Script Queries in Cloud Code - Examples

Once you've reviewed the API documentation and started to use the Game Data Service Cloud Code methods, you can start to build queries to return data stored in your Data Types. You can use the following operators when building queries:

• .in - includes
• .eq - equals
• .ne - does not equal
• .gt - greater than (for string query conditions use this for alphabetical comparisons)
• .lt - less than (for string query conditions use this for alphabetical comparisons)
• startsWith - starts with (only available for string query conditions)
• between - between

For example, to query for email strings:

• var query = API.S("email").eq(email);
• var query = API.S("email").ne(email);
• var query = API.S("email").in("@hotmail.co.uk");

Review Tutorials! See the following section for Game Data Service tutorials containing examples of how to build queries in Cloud Code.

Tutorials

Here are some tutorials that show how to persist and query data on the platform through Cloud Code using the Game Data Service:

• Automating Password Change
• Scheduling Cloud Code
• Facebook Webhooks and GameSparks Integration
• Generating Codes for Joining Challenges
• Sharing Data between Players
• Searching for Players and Teams
• Submitting JSON Document Queries
• Creating Custom Friends Lists