Accessing the DQL Editor

To access the DQL Editor, log in to the portal > select your app > click Collections > and then click DQL editor button located on the right. Note that clicking the View link on any collection will automatically open the DQL Editor with that collection selected.

DQL Editor Interface Overview

The following illustration and corresponding table provide a basic overview of the DQL Editor:

ItemDescription
1Navigation Breadcrumb bar - can use to navigate back to the Collections page or to your app’s home page
2Navigation Tabs to switch between the DQL Editor and the Collections Data Browser
3Links to the documentation, import one or more documents as JSON or CSV files, and settings for the DQL Editor. The settings are used to enable or disable Strict Mode
4Collections - list of collections in the app
5DQL Editor - write DQL queries to read, insert, update, and delete documents.
6Run query - execute the query in the DQL Editor.
7View favorite queries and query history.
8Switch between table and tree view.
9Export query results that are displayed in the query results pane.
10Query results pane that shows the results of the query in JSON or table format.

Import

You can use the Import button to import one or more documents as either a file (JSON or CSV) or to import JSON data directly.

Import data by file

To import data by file, click the Import button and then select the file you want to import.

  • You can either select an existing collection to import the data into, or create a new collection to import the data into.
  • Use the Click to upload or drag and drop link to select a file to import.
  • The file should be in either JSON or CSV format.
  • JSON text should follow the RFC 8259 specification.

An example of a JSON file is shown below:

[
 {
  "_id": "b393c327-6e01-4c52-9408-95a27ae9e83b",
  "address1": "123 Medlock Bridge Rd",
  "address2": "Suite 123",
  "city": "Johns Creek",
  "state": "GA",
  "zipcode": "30097",
  "lat": 34.0644,
  "long": -84.1746,
  "storeNumber": 206,
  "openHour": "10:30",
  "closeHour": "21:30"
 },
 {
  "_id": "d71f4e8b-912f-46e9-a3a5-3d1a3b07129f",
  "address1": "123 N Main St",
  "city": "Alpharetta",
  "state": "GA",
  "zipcode": "30009",
  "lat": 34.0900,
  "long": -84.2811,
  "storeNumber": 204,
  "openHour": "10:00",
  "closeHour": "21:00"
 },
 {
  "_id": "ef5a6d22-6f19-431c-83dc-cd68297d2c13",
  "address1": "1125 Woodstock Rd",
  "city": "Roswell",
  "state": "GA",
  "zipcode": "30075",
  "lat": 34.0583,
  "long": -84.3891,
  "storeNumber": 205,
  "openHour": "11:00",
  "closeHour": "22:00"
 }
]

Once a file is selected, the query editor will be populated with the following DQL query and the query will automatically execute:

INSERT INTO `locations` DOCUMENTS 
(deserialize_json('{"_id":"b393c327-6e01-4c52-9408-95a27ae9e83b","address1":"123 Medlock Bridge Rd","address2":"Suite 123","city":"Johns Creek","state":"GA","zipcode":"30097","lat":34.0644,"long":-84.1746,"storeNumber":206,"openHour":"10:30","closeHour":"21:30"}')), 
(deserialize_json('{"_id":"d71f4e8b-912f-46e9-a3a5-3d1a3b07129f","address1":"123 N Main St","city":"Alpharetta","state":"GA","zipcode":"30009","lat":34.09,"long":-84.2811,"storeNumber":204,"openHour":"10:00","closeHour":"21:00"}')), 
(deserialize_json('{"_id":"ef5a6d22-6f19-431c-83dc-cd68297d2c13","address1":"1125 Woodstock Rd","city":"Roswell","state":"GA","zipcode":"30075","lat":34.0583,"long":-84.3891,"storeNumber":205,"openHour":"11:00","closeHour":"22:00"}'))

Once imported, the new document’s _id will be displayed in the query results pane as Mutated document ID.

Import data by JSON

To import data by JSON, click the Import button and then select Import by JSON.

  • You can either select an existing collection to import the data into, or create a new collection to import the data into.
  • You will be provided with a text editor where you can enter or paste the JSON data.

An example of the JSON data is shown below:

{
  "_id": "a1c92e1b-dc3d-4a0b-8ae7-ec94a237263e",
  "address1": "123 Howell Mill Rd",
  "address2": "Suite 100",
  "city": "Atlanta",
  "state": "GA",
  "zipcode": "30318",
  "lat": 33.7866,
  "long": -84.4111,
  "storeNumber": 104,
  "openHour": "11:00",
  "closeHour": "23:00"
}

Once imported, the new document’s _id will be displayed in the query results pane as Mutated document ID.

Settings - Strict Mode

The settings for the DQL Editor are located in the top right corner of the DQL Editor. The settings are used to enable or disable Strict Mode. With strict mode enabled, all fields are treated as a register by default. When enabled, every field in a document must match the collection definition exactly — including its CRDT type (e.g., map, register, counter).

Disabling strict mode enables new functionality: when turned off, collection definitions are no longer required. SELECT queries will return and display all fields by default. This matches the behavior of the legacy query language. - objects in INSERT and UPDATE statements are treated as maps. When a field has multiple possible types, the most recently updated type is chosen.

For new projects, we recommend disabling strict mode. You can learn more about this feature here.

Collections

A list of collections in your app is displayed in the left side pane of the DQL Editor. Selecting a collection will automatically generate a SELECT statement that will be populated in the DQL query editor. You can hide this pane by clicking the drawer icon in the top right corner of the pane.

DQL Query Editor

The DQL query editor is the main area of the DQL Editor where you can write DQL queries. The editor requires a valid DQL query to be entered. DQL queries need to use single quotes to include field names and values.

INSERT statements

An example of a valid DQL INSERT statement in the editor pane to insert a new document into the locations collection is shown below:

INSERT INTO `locations` 
VALUES (
 {
	'_id': '4f8c73e2-671e-4a4f-bc28-1821d972e433', 
	'address1': '123 Hwy 12 W', 
	'city': 'Fayetteville', 
	'state': 'GA', 
	'zipcode': '30214', 
	'lat': 33.4632, 
	'long': -84.4897, 
	'storeNumber': 207, 
	'openHour': '10:00', 
	'closeHour': '21:00'
 }
)

The DQL query editor requires the use of single quotes for field names and string values. Use double quotes in DQL query editor will result in an error: Invalid query: DQL parser error: Unexpected token { at line 2 column 8 near "VALUES {"; expected (

If you want to use double quotes for field names and string values, you can use the deserialize_json function to convert the JSON string to a DQL string. An example of this is shown below:

INSERT INTO `locations` DOCUMENTS 
(deserialize_json('{"_id":"4f8c73e2-671e-4a4f-bc28-1821d972e431","address1":"123 Hwy 12 W","city":"Fayetteville","state":"GA","zipcode":"30214","lat":33.4632,"long":-84.4897,"storeNumber":207,"openHour":"10:00","closeHour":"21:00"}')) 

UPDATE statements

An example of a valid DQL UPDATE statement is shown below:

UPDATE `locations`
SET address1 = '123 Hwy 54 W' 
WHERE _id = '4f8c73e2-671e-4a4f-bc28-1821d972e431'

Mutations to documents via the INSERT, UPDATE, and DELETE statements are displayed in the query results pane as Mutated document ID.

SELECT statements

An example of a valid DQL SELECT statement is shown below:

SELECT * FROM `locations` LIMIT 10

When queries are executed using the SELECT statement, the results are displayed in the query results pane. The results are displayed in JSON format by default. You can switch to table view by clicking the Table button in the top right corner of the query results pane.

For comprehensive DQL syntax and usage information, refer to the DQL documentation.

Queries Favorites and History

The Queries pane is located to the right of the DQL Editor. It is used to view the history of queries that have been executed. You can also add queries to your favorites or delete a query from the history by clicking the ... button. You can close the Queries pane by clicking the ‘x’ button in the top right corner of the pane.

Query Results

The query results pane displays the results of the query in either JSON or table format. The number of documents returned by the query is displayed in the top right corner of the query results pane.

Exporting query results

Once you execute a query, you can export the results by clicking the Export query result button in the top right corner of the query results pane. You can export the results as a JSON file or a CSV file.

JSON Results

The JSON results display the results of the query in JSON format. A chevron icon appears after each line number allowing you to hide or show elements in the document.

Table Results

The table results display all the documents in a table view. Selecting a document in the table will display the document in the Document Viewer.

Document Viewer

The Document Viewer displays the document in JSON format. You can use the up and down buttons to navigate documents based on how they are displayed in the table view. Clicking the square icon in the Document title bar will copy the document to the clipboard.

Collections Data Browser Interface Overview

The following illustration and corresponding table provide a basic overview of the Collections Data Browser:

ItemDescription
1Navigation Breadcrumb bar - can use to navigate back to the Collections page or to your app’s home page
2Navigation Tabs to switch between the DQL Editor and the Collections Data Browser
3Links to the documentation, import one or more documents as JSON or CSV files, and settings for the DQL Editor. The settings are used to enable or disable Strice Mode
4Collections - list of collections in the app
5Data Browser - table view of the documents in a collection
6JSON Document viewer - JSON view of a document

Data Browser

The data browser works with the same functionality as the DQL Editor when using the Table tab in the Query results pane. You can use the dropdown list in the upper right to set a time period for the table to auto-refresh, which will allow it to check for changes in any documents in a given collection.

Like the DQL Editor’s Query results panel, selecting a document in the table will display the document in the Document Viewer.