NoSQL Explorer

Introduction

The NoSQL Explorer allows you to interact with the data stored for your game in the Mongo DB collections on the platform:

Important! If you're working on a new game that was created after the 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. For details on how to work with the new Game Data Service, see Data Type Explorer.

When you open the NoSQL Explorer, there are two main things to note:

• Do you want to work with your game's PREVIEW stage or LIVE stage Mongo database?
• What operation do you want to perform against the database collections?

PREVIEW Stage or LIVE Stage Database?

Each game has its own PREVIEW stage Mongo database. If you've taken a game Snapshot and published the game to LIVE stage, the game will also have a LIVE stage Mongo database:

• The PREVIEW stage and the LIVE stage Mongo databases are entirely distinct and separate databases.
• You can select the database you wish to look at using the Preview/Live switch at the top of the page and the Collections panel adjusts accordingly:

Note The Preview/Live switch will be enabled only if you have already published a game configuration Snapshot of your game to Live. The default selection is Preview stage.

What Database Collection Operation?

When you select a Database Collection, the Actions available for use with that Collection represent the different operations you can perform against the data in the selected Mongo database. See below for a detailed account of how to work with these operations.

FAQs? You can review Frequently Asked Questions about working with the NoSQL Explorer.

Checking Database Statistics

If you want to check the database statistics for the current game's Mongo database, click the Database Stats information button on the Collections panel:

A Database Stats panel opens:

Click OK to close the Database Stats panel at any time:

Selecting a Mongo DB Collection

You can use the Collections panel to select the Mongo DB Collection that you want to work with - click to expand any of the headings in the listing:

Here, we've selected the System>player Collection.

Selecting Actions

When you select a Collection, the Actions available for use with that Collection are shown as a series of option buttons. When you select an Action, the panel adjusts for the entering the specific operation parameters:

For details of the parameters used for each operation, see the following section

Selecting Multiple Collections

If you want to work with more than one Collection, each selection you make adds a tab for a Collection:

Working with the Output Panel

The results for the operations you perform against a database Collection are returned into the Output panel - you can click Find or Explain to get results. For example, here is the result for Explain for the Find tab:

When the panel loads, the results hierarchy is collapsed. You can drill-down to expand the levels and read-off details:

You can edit or delete individual Documents in a Collection from the Output panel.

NOT SYSTEM COLLECTIONS! Do not attempt to edit or delete any System Collection Documents manually. Caching operations which are managed by the platform will end up with invalid data if you do this!

RUNTIME or META COLLECTIONS? You can manually edit or delete Documents from these Collections, but only update META Collections in PREVIEW. You can update RUNTIME Collections in both PREVIEW and LIVE.

Editing a Document

1. Select a Collection and submit a Find to return results into the Output panel.

2. Expand the individual Document returned for your query and that you want to edit:

• In this example, we've submitted a Find against the System>player Collection.

Query Timeout! If you submit a query against a very large Collection, the query might timeout at 10 seconds. You will see a message but no data will be returned.

3. Click to edit the Document you've expanded. An Edit Document dialog appears.

4. Use the editor in the dialog to make your editing changes to the Document and click Save:

Deleting a Document

1. Select a Collection and submit a Find to return results into the Output panel:

2. Expand the individual Document returned for your query and that you want to delete.

3. Click to delete the Document you've expanded. A confirmation dialog appears with details of the Document you're about to delete from the Collection:

4. Click Delete again, if you want to continue and delete the Document.

Actions for Selected Collection

When you've selected the database Collection you want to work with, you can select one of the Actions available for that Collection: Find, Count, Insert, Update, Remove, Index, Aggregate, Drop, and Stats.

Creating Collections? For how to create a new Collection, see the following section.

Find

MongoDB Find Manual

Using the Find option, you can execute queries against Collections:

• If you have existing Mongo experience, the Find form builds a db..find(, ).sort().limit().skip() command based on the data populated in the form fields:

• Query: The query you want to execute in JSON form:
  • To find players with displayName "testUser" the following valid JSON must be used {"displayName" : "testUser"}
  • If you submit a query against a very large Collection, then the query might timeout at 10 seconds. You will see a message but no data will be returned.
• Sort: The JSON representation of the sort for the query:
  • To sort by userName in ascending order the following valid JSON must be used {"userName" : 1}
  • To sort by id, the following valid JSON must be used {"_id": -1} or {"_id": 1}
• Fields: Allows you to limit the fields that are returned in the results:
  • This is useful for Collections with large document.
  • To limit the results to only contain the userName and displayName, the following JSON should be used : {"userName" : 1, "displayName" : 1}. 1 indicates inclusion and 0 indicates exclusion for a field. You cannot mix inclusion and exclusion in a single query.
• Skip/Limit: The number of documents to skip, useful for paging in combination with limit:
  • To get the 3rd page of 10 documents per page, use skip=20 and limit=10.
  • The maximum that the limit value can be set to for Finds is 1000.
• Explain button: Enter your query and click this button to get information about the query returned into the Output panel. You can review and analyze this information to optimize your query.
• Export button: The Find option allows you to export the results to a local file. Set up your query as normal and press the Export button. The maximum that the limit value can be set to for exports is 1000.

You Must Use Valid JSON! If you want to use Query, Sort, or Fields, you must use valid JSON syntax and only valid JSON syntax, as shown in the examples given above. Importantly, JavaScript syntax is NOT VALID.

Count

MongoDB Count Manual

Using the Count option, you can get a count of the number of documents in a Collection that match a Find query.

• Query: The query you want to execute in JSON form:
  • To find players with displayName “testUser” the following JSON should be used {“displayName” : “testUser”}.
• Explain button: Enter your query and click this button to get information about the query returned into the Output panel. You can review and analyze this information to optimize your query.

Insert

MongoDB Insert Manual

Using the Insert option, you can insert documents directly into a Collection.

• Document : Add the document you want to insert into the Document field.
  • If the document you supply does not have an _id field, Mongo will create one for you.
  • If the document you supply does have an _id field and it is already in use within the Collection the insert will fail.

Update

MongoDB Update Manual

Using the Update option, you can modify an existing document(s) in a Collection.

• Query : The selection criteria for the update. Use the same query selectors as used in the Find method.
• Update : The modifications to apply.
• Multi : Set to true if all documents meeting the criteria should be modified.
• Upsert : Set to true to create a new document when no document matches the query.

Remove

MongoDB Remove Manual

Using the Remove option, you can remove all documents matching the supplied query from a Collection.

• Query : The selection criteria for the Remove operation. All documents matching this criteria will be removed.

Index

MongoDB Index Manual

Using the Index option, you can view the indexes that have been created for a Collection.

Aggregate

MongoDB Aggregate Manual

Using the Aggregate option, you can calculate aggregate values for data in the Collection.

• Pipeline : A JSON array of pipeline commands.
  • If you are supplying more than one pipeline stage you must wrap them within a JSON array.
• Explain button : Enter your query and click this button to get information about the query returned into the Output panel. You can review and analyze this information to optimize your query.

You Must Use Valid JSON! You must use valid JSON syntax and only valid JSON syntax for the Aggregate field. Importantly, JavaScript syntax is NOT VALID.

Drop

MongoDB Drop Manual

Using the Drop option, you can permanently remove a Collection from the database.

Stats

MongoDB Stats Manual

Using the Stats option, you can obtain statistics about the selected collection.

• Stats button : Shows the Collection statistics.

Creating a Collection

From the Collections panel, you can create a new Collection in the database:

1. Click the add icon. The Create Collection dialog appears:

• Collections can be created as Runtime (non-versioned) or Metadata (versioned).

2. Select the type of Collection you want to create and enter a name for the new Collection:

• Name : The name to give the Collection. Within the database:
  • Metadata Collections are prefixed with "meta."
  • Runtime Collections are prefixed with "script."

3. Click to Create the new Collection.