Data Browser and Editor
The Ditto DQL Editor is a powerful interface for working directly with your app’s data stored in the Ditto Portal. It allows you to write and run DQL queries to read, insert, update, and delete documents across your collections. The editor also includes helpful features like query history/favorites that persist across sessions and data import/export tools to streamline your workflow.
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:
Item | Description |
---|---|
1 | Navigation Breadcrumb bar - can use to navigate back to the Collections page or to your app’s home page |
2 | Navigation Tabs to switch between the DQL Editor and the Collections Data Browser |
3 | Links 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 |
4 | Collections - list of collections in the app |
5 | DQL Editor - write DQL queries to read, insert, update, and delete documents. |
6 | Run query - execute the query in the DQL Editor. |
7 | View favorite queries and query history. |
8 | Switch between table and tree view. |
9 | Export query results that are displayed in the query results pane. |
10 | Query 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:
Once a file is selected, the query editor will be populated with the following DQL query and the query will automatically execute:
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:
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:
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:
UPDATE statements
An example of a valid DQL UPDATE statement is shown below:
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:
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:
Item | Description |
---|---|
1 | Navigation Breadcrumb bar - can use to navigate back to the Collections page or to your app’s home page |
2 | Navigation Tabs to switch between the DQL Editor and the Collections Data Browser |
3 | Links 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 |
4 | Collections - list of collections in the app |
5 | Data Browser - table view of the documents in a collection |
6 | JSON 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.