---
title: HTTP API - DQL Queries
slug: cloud/http-api/dql-queries
docTags: 
createdAt: 2023-12-11T01:23:10.521Z
---

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`&#x20;

# DQL Support

The DQL HTTP API supports the following DQL commands:

- `SELECT`
- `INSERT`&#x20;
- `UPDATE`

:::hint{type="warning"}
`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)](docId\:JMhbyt6ShuVF5rk8QgUMv) .
:::

# SELECT

To retrieve documents from a collection, use a `SELECT` statement and, if desired, include optional clauses pinpointing criteria to further filter results.&#x20;

For more information, see *Ditto Query Language* > [SELECT](docId:1bFCHjoxcgV01keflfvvU).

## Optional Clauses for Filtering

The following table provides an overview of the various clauses you can use to set granular controls for filter operations:

| **Clause**                              | **Description**                                                                                                                 |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| <font color="#db2777">`FROM`</font>     | The required clause specifying the collection containing the documents for retrieval. (See [FROM](docId:1bFCHjoxcgV01keflfvvU)) |
| <font color="#db2777">`WHERE`</font>    | Applies filtering conditions to restrict the documents included in the result set. (See [WHERE](docId:1bFCHjoxcgV01keflfvvU))   |
| <font color="#db2777">`ORDER BY`</font> | Specifies the sorting order of the result set based on one or more expressions. (See [ORDER BY](docId:1bFCHjoxcgV01keflfvvU))   |
| <font color="#db2777">`LIMIT`</font>    | Restricts the number of documents included in the result set. (See [LIMIT](docId:1bFCHjoxcgV01keflfvvU))                        |
| <font color="#db2777">`OFFSET`</font>   | Skips a specific number of documents before returning the result set. (See [OFFSET](docId:1bFCHjoxcgV01keflfvvU))               |

## Basic SELECT Operation

The following syntax outlines the basic structure of a `SELECT` statement:

:::CodeblockTabs
DQL

```sql
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"
  }'
```

### 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
}
```

# INSERT with Arguments

To create new documents, use an `INSERT` statement and, if desired, optional arguments defining the fields to include.

:::CodeblockTabs
DQL

```sql
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"
        }
      }
  }'
```

**Sample Response**

```json
{
  "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 <font color="#db2777">`UPDATE`</font> operation.

:::CodeblockTabs
DQL

```sql
UPDATE your_collection_name
SET field1 = value1, field2 -> [mutator], ...
WHERE [condition]
```
:::

For more information, see *Ditto Query Language* > [UPDATE](docId:_vxfd7_jJFfTzByIVqoxh).

# 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
}
```