HTTP Data API
HTTP API - DQL Queries

This article provides an overview of how to perform Ditto Query Language (DQL) queries in Ditto using the HTTP data API.
RPC Endpoint
Use the following endpoint to execute your queries: https://<CLOUD_ENDPOINT>/api/v4/store/execute 
DQL Support
The DQL HTTP API supports the following DQL commands:
SELECT
INSERT 
UPDATE
EVICT is not currently available for the Big Peer, although it's in development. To learn more about removing data from your Big Peer instance, see Writing: HTTP (Legacy)﻿ .
SELECT
To retrieve documents from a collection, use a SELECT statement and, if desired, include optional clauses pinpointing criteria to further filter results. 
For more information, see Ditto Query Language > SELECT﻿.
Optional Clauses for Filtering
The following table provides an overview of the various clauses you can use to set granular controls for filter operations:
﻿
Basic SELECT Operation
The following syntax outlines the basic structure of a SELECT statement:
DQL
SELECT * FROM collection
SELECT * FROM collection
﻿
cURL Request
For instance, performing the following cURL request to SELECT documents from the cars collection:
Curl
curl -X POST "https://<CLOUD_ENDPOINT>/api/v4/store/execute" \
  --header 'Authorization: <AUTHORIZATION-TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "statement": "SELECT * FROM cars"
  }'
curl -X POST "https://<CLOUD_ENDPOINT>/api/v4/store/execute" \
  --header 'Authorization: <AUTHORIZATION-TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "statement": "SELECT * FROM cars"
  }'
﻿
Response Object
After invoking a request to INSERT documents, Ditto returns a response object similar to the following example:
JSON
{
  "transactionId": 100,
  "queryType": "select",
  "items": [{
    "_id": "123",
    "color": "blue"
  },{
    "_id": "456",
    "color": "red"
  }],
  "mutatedDocumentIds": [],
  "error": {},
  "warnings": [],
  "totalWarningsCount": 0
}
{
  "transactionId": 100,
  "queryType": "select",
  "items": [{
    "_id": "123",
    "color": "blue"
  },{
    "_id": "456",
    "color": "red"
  }],
  "mutatedDocumentIds": [],
  "error": {},
  "warnings": [],
  "totalWarningsCount": 0
}
﻿
INSERT with Arguments
To create new documents, use an INSERT statement and, if desired, optional arguments defining the fields to include.
DQL
INSERT INTO cars DOCUMENTS (:doc1), (:doc2)
INSERT INTO cars DOCUMENTS (:doc1), (:doc2)
﻿
cURL Request
For example, initiating creating doc1 and doc2 as follows:
Curl
curl -X POST "https://<CLOUD_ENDPOINT>/api/v4/store/execute" \
  --header 'Authorization: <AUTHORIZATION-TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "statement": "INSERT INTO cars DOCUMENTS (:doc1), (:doc2)",
      "args": {
        "doc1": {
          "_id": "123",
          "color": "blue"
        },
        "doc2": {
          "_id": "456",
          "color": "red"
        }
      }
  }'
curl -X POST "https://<CLOUD_ENDPOINT>/api/v4/store/execute" \
  --header 'Authorization: <AUTHORIZATION-TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "statement": "INSERT INTO cars DOCUMENTS (:doc1), (:doc2)",
      "args": {
        "doc1": {
          "_id": "123",
          "color": "blue"
        },
        "doc2": {
          "_id": "456",
          "color": "red"
        }
      }
  }'
﻿
Sample Response
JSON
{
  "transactionId": 100,
  "queryType": "mutation",
  "items": [],
  "mutatedDocumentIds": ["123", "456"],
  "error": {},
  "warnings": [],
  "totalWarningsCount": 0
}
{
  "transactionId": 100,
  "queryType": "mutation",
  "items": [],
  "mutatedDocumentIds": ["123", "456"],
  "error": {},
  "warnings": [],
  "totalWarningsCount": 0
}
﻿
UPDATE
To modify the content of existing documents in a collection, use the UPDATE operation.
DQL
UPDATE your_collection_name
SET field1 = value1, field2 -> [mutator], ...
WHERE [condition]
UPDATE your_collection_name
SET field1 = value1, field2 -> [mutator], ...
WHERE [condition]
﻿
For more information, see Ditto Query Language > UPDATE﻿.
Response Object Definition
The following snippet outlines the structure of a typical response for insert or update document operations:
JSON
{
  // Transaction Identifier
	"transactionId": number,
  // Possible values:
  // - "select"
  // - "mutation" (for insert or update operations)
  // - "unknown" (when returning an error before the query is known)
  "queryType": string,
  // Array of documents. Only populated for SELECT queries.
  "items": [...],
  // Document ids of documents modified by insert or update operations
  "mutatedDocumentIds": [...],
  // A single error. It prevents the query from executing / completing.
  // Will always be present, even if there are no errors.
  "error": {
    // Description of error. Not present if no errors.
    "description": string
  },
  // Array of warnings. Max 10 will be shown.
  // Will always be present, even if there are no warnings.
  "warnings": [
     {
        // Document identifier. May not be present
        "_id": string,
        // Description of warning
        "description": string
     }
  ],
  // Total number of warnings during query execution, including those in the
  // `warnings` property above.
  "totalWarningsCount": number
}
{
  // Transaction Identifier
	"transactionId": number,
  // Possible values:
  // - "select"
  // - "mutation" (for insert or update operations)
  // - "unknown" (when returning an error before the query is known)
  "queryType": string,
  // Array of documents. Only populated for SELECT queries.
  "items": [...],
  // Document ids of documents modified by insert or update operations
  "mutatedDocumentIds": [...],
  // A single error. It prevents the query from executing / completing.
  // Will always be present, even if there are no errors.
  "error": {
    // Description of error. Not present if no errors.
    "description": string
  },
  // Array of warnings. Max 10 will be shown.
  // Will always be present, even if there are no warnings.
  "warnings": [
     {
        // Document identifier. May not be present
        "_id": string,
        // Description of warning
        "description": string
     }
  ],
  // Total number of warnings during query execution, including those in the
  // `warnings` property above.
  "totalWarningsCount": number
}
﻿
﻿
Updated 09 Oct 2024
Did this page help you?
HTTP API - Getting Started
HTTP API - Attachments