Data Type Explorer
Introduction
The Data Type Explorer allows you to view and manage the Data Types you’ve created to persist data on the platform for your game using the Game Data Service.
Important! If you're working on a new game that was created after the new Game Data Service was launched in January 2018, you won't be able to create new Mongo Runtime collections in the Collections panel and you'll get an error if you try to do this or if you try to create a Runtime collection using Cloud Code. If you're working on a game that you started to develop before the Game Data Service was launched or if you've copied a Snapshot of a game you started to develop before the Game Data Service was launched into a new game, you'll be able to create Mongo Runtime collections. For details on how to work with Mongo collections, see NoSQL Explorer.
From the Data Types panel, you can quickly access your custom Data Types. When you open a Data Type, several actions are available to interact with its data - see the following section for details of how to work with these actions.
This topic introduces the Game Data Service and explains how to work with the Data Types you create to manage the custom data you want to persist against the platform for your game:
FAQs? You can review Frequently Asked Questions about working with the Data Type Explorer.
Why Game Data Service?
The Game Data Service allows you to manage the custom data that your game persists on the GameSparks platform in a controlled and streamlined way. You can:
- Create and configure Data Types for the custom data you want for your game.
- Add indexed data fields in the Configurator to use when querying against your game's Data Types. See the Game Data page.
When you follow these steps to use the Game Data Service, you'll be adopting a carefully considered and well-designed approach to data persistence for your game. In return for this data persistence set up work, you'll get the benefits of a data service that's been designed with your game’s performance under high player loads very much in mind, a service that ensures any frequent data retrieval operations, such as rich-querying against your game’s custom data, is done optimally and efficiently.
Using Game Data Service - Guidelines and Best Practices? For advice on how best to use the Game Data Service for persisting and managing the custom data structures in your game, we strongly recommend that you review the section on Custom Data>Using the Game Data Service in the Managing Data Persistence in the GameSparks Platform tutorial.
Opening Data Types
1. On the main navigation menu, select Data Explorer. The Data Types panel lists the custom Data Types you've created for persisting data on the platform.
2. If you want to set up indexed fields for your Data Types, click Configure Data Indexes to go directly to the Configurator>Game Data page:
- For details of how to set up indexes for your Data Types, see the Game Data page.
3. Select a Data Type to open it:
- When you open a Data Type, the available actions are shown as a series of option buttons.
- You can open multiple Data Types — a tab will appear for each one.
- If you haven't added any indexed fields to the Data Type, then Query will not be available as an action.
- For details on how to use the available actions, see the following section.
Using Data Type Actions
When you open a Data Type, you can use several actions to interact with the data:
- Insert – insert data documents.
- Find – retrieve and inspect data documents by ID.
- Query – query data:
- You can use only those fields you’ve added as indexed fields to build your queries.
- You can Export the results returned by a query.
- If you haven’t added any indexed fields to a Data Type, then the Query action will not be available when you open the Data Type.
- Drop – remove all data in a Data Type.
Warning! There is a limit of 500 Data Types per user. Any attempt to exceed this limit will fail.
Inserting Data
You can use the Insert option to insert a document into a Data Type:
1. In the Data Explorer, open the Data Type into which you want to insert data.
2. Select Insert. The tab adjusts.
3. Enter the details for the insert action:
- ID – Enter an ID for the document:
- You must enter at least one alphanumeric character for the ID.
- You cannot use the underscore or pipe (│) characters for the ID.
- Data – Use the JSON editor to enter the document. You can use both indexed and non-indexed fields.
- TTL – Set a Time To Live for the document by clicking in this text field and then using the pop-up calendar:
- The inserted document will expire and be deleted from the Data Type at the specified point in the future.
- If you don’t enter a TTL, then the document will have an unlimited lifespan.
- In this example, we’ll insert a document for PlayerOne into the Player Data Type.
- The document Data uses two indexed field paths—location and ranking—that we've previously added for the Player Data Type and two non-indexed fields—displayname and firstname.
Important! If you insert a document using the same ID as an existing document, then the Insert action overwrites the existing.
4. Click the Insert button. The tab adjusts and when the document has been inserted, the details are shown at the bottom of the tab:
5. We can repeat the Insert action to add two further Player documents. In each case, we’ll give these players the same CITY location as PlayerOne:
- For PlayerTwo:
- For PlayerThree:
In the next section, we use the Find action against our custom Player Data Type.
Warning! Any document you insert must be less than 400Kb in size.
Finding Data
You can find and view individual documents by ID.
Note: You cannot retrieve all documents in a Data Type at once, but you can retrieve multiple documents by querying using indexed fields. See the following section.
To find a document by ID:
1. In the Data Explorer, open the Data Type whose documents you want to find and manage:
- The Find action is selected by default.
- The ID field is empty and you must enter an ID to execute the find.
2. Enter the ID of the document you want to retrieve.
3. Click the Find button. The tab adjusts and the document is loaded:
4. Click to Delete the document if you want to remove it from your Data Type.
5. If you want to change the content of the document, click Edit. The Edit Document dialog appears.
6. Make the editing changes you want to the document:
- In this example, we’ve edited the ranking value for PlayerOne.
- You can edit the TTL for the document.
7. If you want to perform a version check when you save your changes, select Use version check. If you select this, when you attempt to save your changes to the document, the save will fail if the document has been modified elsewhere since you loaded it using Find.
8. Click to Save your editing changes. The Edit Document dialog closes and the document has been updated on the Data Type tab:
Querying Data
If you have set up indexed fields for a Data Type, you can retrieve data from it by building a query using those indexed fields and submitting that query in the Data Explorer:
- Using Query Builder
- Using Query JSON
- Query Rules Using "in"
- Querying Arrays
- Building Complex Queries
- Export Query Results
At the outset, it's important to note:
- The maximum number of results returned for a query is 100.
- If you build complex queries, you can only use two rules for each condition you build into your query. See following section.
- If you query against an array of data, the satisfaction of the query criteria will be performed against the last value in the array. See the following section for an example.
- Although the Game Data Service is immediately consistent for GetItems requests, it's eventually consistent for queries. This means that if you insert data into a Data Type and then immediately query it, you might not get the results you were expecting.
Using Query Builder
First, we’ll use the Query Builder to build a query using the indexed fields we've added to the Player Data Type:
1. In the Data Explorer, open the Data Type you want to query.
2. Select the Query action.
3. You can use the Builder to create the query you want to perform:
- Use the Add Rule and Add Group buttons to build more complex queries.
4. You can define a sorting for the results returned by the query using any of the indexed fields you’ve added to the Data Type:
- Use the Sort and Order drop-downs to define the results sorting you want:
- Note that you use the Short Codes of the indexed fields you’ve added to your Data Type when building your query and defining a results sorting.
5. Click the Query button:
- This simple query uses the CITY indexed field and returns each of the documents we inserted for the Player Data Type in the previous section.
Note: A Query returns up to a maximum of 100 results that satisfy the query.
6. Click to expand and view the details any of the documents returned by your query:
You can use two options here to manage your custom data:
- Edit the document.
- Delete the document.
7. You can refine your Query to get just the results you want:
- Here, we’ve added a second rule by conjunction using the RANK indexed field, so that only the documents for those players who live in York and have a ranking greater than 20 are returned.
Using Query JSON
As well as using the Builder to create a query, you can view and edit your query JSON directly:
- Click JSON to show this view – you can then edit the query JSON or copy and paste if you want to use the JSON elsewhere:
- Here, we’ve opened the query JSON and changed the value for the query rule using the RANK indexed field and re-issued the query to return the single player in our Data Type that is ranked greater than 30.
Query Rules Using "in"
You can build query rules using the "in" operator by entering a comma-separated list of values for a field you are querying against. The query results will contain only those documents where the queried field value matches one of the values in the comma-separated list.
However, care is required when you use an "in" rule to build a query. Suppose we had inserted data into our PlayerOne and PlayerThree documents for the CLASS indexed fields of the Player Data Type - say Knight and Warrior respectively. We could then query the Data Type using this rule to return both documents:
But you must ensure that the comma-separated list of values you use for this type of query rule does not contain any white space characters. In this example, if we insert a white space before the second value: " Knight", the query will fail to return the PlayerOne document that satisfies "Knight":
Querying Arrays
When you build a query that will operate on a data array in a Data Type, then the query is performed against the last value in the array. Here's an example:
1. Open a Data Type and insert a data document that contains an array. We'll open TEAMS and insert TeamOne data:
- Note that we've inserted an array for team scores.
2. For the purpose of the example, we'll add two more documents:
- TeamTwo:
- TeamThree:
3. Now, before we try to query this Data Type, you can copy the JSON you've used to insert data for one of the TEAMS documents and go to the Game Data page and open the TEAMS Game Data Indexes.
4. Under Indexed Fields, click Index Advisor and paste in the JSON copied from the Insert. The JSON is scanned and candidate indexed fields for the Data Type are listed.
5. For this example, click to add the teamname and scores paths and give each indexed field a Short Code:
6. Click to Save and Close the Data Type indexing.
7. Go back to Data Explorer and build a simple query with a rule that uses the TEAMSCORE indexed field:
- Here we're querying only for those teams with a score greater that 34, which was the last value in TeamThree scores array, whereas TeamOne and TeamTwo had 63 and 56 respectively in their scores arrays. As expected, TeamThree isn't returned for the query.
Building Complex Queries
You can use the Query Builder to build complex queries by using the Add Rule and Add Group options. However, you can only add two rules for each condition.
For example, suppose we develop the example from the previous section and add scores for each of our players, which is an indexed field for the Player Data Type:
- PlayerOne - 120
- PlayerTwo - 140
- PlayerThree - 160
If we now try to build a 3-rule condition to return only PlayerTwo and PlayerThree and submit the query, we'll get an error:
Instead, we have to add a second group and build the query in this way:
Exporting Query Results
You can export the results returned by a query against a Data Type directly to a local file:
- Create your query and click Export. The results of the query are loaded, exported as JSON to a local file, and saved to your Downloads folder.
Dropping Data Type
You can Drop a Data Type to remove all of its data. This will remove all of the documents in the Data Type. The Drop action can be useful in Preview because you might be developing and testing your game and want to clear out test data occasionally.
Important! There is no undo available for the Drop action, so you must be especially careful using in the Live stage of your game.
1. In Data Explorer, open a Data Type containing data that you want to remove.
2. Select Drop.
3. Click the red Drop button:
A warning/confirmation dialog appears:
4. Click OK to confirm the data drop. The dialog closes and a message confirms that the Data Type has been dropped:
It's important to note that:
- Any indexes that you've configured for the Data Type are not affected when you drop it. If you recreate the same Data Type, the indexing will be re-applied.
- Whether or not a dropped Data Type continues to be listed in the Data Types panel depends on the existence of indexed field:
- If you drop a Data Type that you've created a Game Data Index for on the Game Data page, it will continue to show in the Data Types panel.
- If you drop a Data Type that you haven't created a Game Data Index for, it will be removed from the Data Types panel.
Opening Other Data Types
You can create and open a Data Type directly from the Data Explorer. You can then:
- Insert data into it in the normal way.
- In the Configurator, set up indexed fields for this new Data Type.
- Return to the Data Explorer and query against the Data Type using those indexed fields.
To create, open, and query data for other Data Types:
1. Open the Data Explorer and on the Data Types panel, enter the name of the new Data Type in the Other type field:
- Here, we open a new TOURNAMENTS Data Type.
2. Click Open. The new Data Type is created and opened in the Data Explorer.
3. Click Insert to load some data into the new Data Type:
- In this example, we've inserted a TournamentOne document into the TOURNAMENTS Data Type.
- We’ve used three String and one Number fields.
4. Insert any other data documents you want for your Data Type:
- For this example, we’ll add two further tournaments, each of which are located in London.
- Note that you can immediately perform a Find by ID:
- Here we’ve retrieved the TournamentTwo document.
5. If you refresh, the new TOURNAMENTS is added to the Data Types panel:
- Note that the Query button does not show for the new Data Type. This is because, although you’ve added data to it, you haven’t yet added any indexed fields for the Data Type.
6. Go to Configurator>Game Data.
7. Add indexed fields for the new TOURNAMENTS Data Type using the same Short Code:
- Note that we’ve added two indexed fields using the same Paths as used for the initial data Insert we performed in the Data Explorer.
8. Click to Save and Close the new Data Type Index.
9. Return to the Data Explorer and re-open the TOURNAMENTS Data Type. Because we've added Data Type Indexing, the Query action is now available and we can query the data using any of the indexing fields:
Filtering Data Types
As you add Data Types to your game, the Data Types panel will automatically paginate the list into manageable pages of 10:
You can use the Filter field to quickly reduce the list and find the specific Data Type you want to work with:
Data Types in Preview and Live
When you have set up your Data Type Indexes in Preview for your game’s data persistence requirements against the platform, you can take a game configuration Snapshot. By publishing the game Snapshot, you make the Data Type Indexing available for the game’s Live stage. It’s important to note when publishing a game Snapshot to Live:
- No data is published to Live from the custom Data Types into which you’ve inserted data in Preview.
- However, any updates for adding/removing Data Type Indexes are made to the game’s Live stage.
- This re-indexing operation against the game's Live data might cause a delay in the game’s publication process - see the following section for details.
Re-Indexing and Publishing a Game
The updating of Data Type Indexes has a knock-on effect for the game publication process:
- If there are any indexing changes in the new game Snapshot, the re-indexing operation might take some time because the new indexing schema has to be built against the game’s Live data.
- The re-indexing operation must complete before the game Snapshot is fully published.
In the following example, five new Data Type Indexes have been added since the game was last published to Live. When the new game Snapshot is published from the Game Overview page, a status progress will show for the re-indexing operation: