Setting up query API endpoints

#### Headers[​](#headers "Direct link to Headers")

|  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Header Required Description Values|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `x-clickhouse-endpoint-version` No Specifies the endpoint version `1` or `2` (defaults to last saved version)| `x-clickhouse-endpoint-upgrade` No Triggers endpoint version upgrade (use with version header) `1` to upgrade | | | | | | | | | | | |

---

### Request body[​](#request-body "Direct link to Request body")

#### Parameters[​](#params "Direct link to Parameters")

|  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Required Description|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `queryVariables` object No Variables to be used in the query|  |  |  |  | | --- | --- | --- | --- | | `format` string No Response format | | | | | | | | | | | |

#### Supported formats[​](#supported-formats "Direct link to Supported formats")

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| Version Supported Formats|  |  |  |  | | --- | --- | --- | --- | | **Version 2** All ClickHouse-supported formats|  |  | | --- | --- | | **Version 1 (limited)** TabSeparated   TabSeparatedWithNames   TabSeparatedWithNamesAndTypes   JSON   JSONEachRow   CSV   CSVWithNames   CSVWithNamesAndTypes | | | | | |

---

### Responses[​](#responses "Direct link to Responses")

#### Success[​](#success "Direct link to Success")

**Status:** `200 OK`  
The query was successfully executed.

#### Error codes[​](#error-codes "Direct link to Error codes")

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Status Code Description|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `400 Bad Request` The request was malformed|  |  |  |  | | --- | --- | --- | --- | | `401 Unauthorized` Missing authentication or insufficient permissions|  |  | | --- | --- | | `404 Not Found` The specified query endpoint wasn't found | | | | | | | |

#### Error handling best practices[​](#error-handling-best-practices "Direct link to Error handling best practices")

- Ensure valid authentication credentials are included in the request
- Validate the `queryEndpointId` and `queryVariables` before sending
- Implement graceful error handling with appropriate error messages

---

### Upgrading endpoint versions[​](#upgrading-endpoint-versions "Direct link to Upgrading endpoint versions")

To upgrade from version 1 to version 2:

1. Include the `x-clickhouse-endpoint-upgrade` header set to `1`
2. Include the `x-clickhouse-endpoint-version` header set to `2`

This enables access to version 2 features including:

- Support for all ClickHouse formats
- Response streaming capabilities
- Enhanced performance and functionality

## Examples[​](#examples "Direct link to Examples")

### Basic request[​](#basic-request "Direct link to Basic request")

**Query API Endpoint SQL:**

```
SELECT database, name AS num_tables FROM system.tables LIMIT 3;
```

#### Version 1[​](#version-1 "Direct link to Version 1")

- cURL- JavaScript

```
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'Content-Type: application/json' \
-d '{ "format": "JSONEachRow" }'
```

```
fetch(
  "https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run",
  {
    method: "POST",
    headers: {
      Authorization: "Basic <base64_encoded_credentials>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      format: "JSONEachRow",
    }),
  }
)
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));
```

```
{
  "data": {
    "columns": [
      {
        "name": "database",
        "type": "String"
      },
      {
        "name": "num_tables",
        "type": "String"
      }
    ],
    "rows": [
      ["INFORMATION_SCHEMA", "COLUMNS"],
      ["INFORMATION_SCHEMA", "KEY_COLUMN_USAGE"],
      ["INFORMATION_SCHEMA", "REFERENTIAL_CONSTRAINTS"]
    ]
  }
}
```

#### Version 2[​](#version-2 "Direct link to Version 2")

- GET (cURL)- POST (cURL)- JavaScript

```
curl 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONEachRow' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'x-clickhouse-endpoint-version: 2'
```

```
{"database":"INFORMATION_SCHEMA","num_tables":"COLUMNS"}
{"database":"INFORMATION_SCHEMA","num_tables":"KEY_COLUMN_USAGE"}
{"database":"INFORMATION_SCHEMA","num_tables":"REFERENTIAL_CONSTRAINTS"}
```

```
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONEachRow' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2'
```

```
fetch(
  "https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONEachRow",
  {
    method: "POST",
    headers: {
      Authorization: "Basic <base64_encoded_credentials>",
      "Content-Type": "application/json",
      "x-clickhouse-endpoint-version": "2",
    },
  }
)
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));
```

```
{"database":"INFORMATION_SCHEMA","num_tables":"COLUMNS"}
{"database":"INFORMATION_SCHEMA","num_tables":"KEY_COLUMN_USAGE"}
{"database":"INFORMATION_SCHEMA","num_tables":"REFERENTIAL_CONSTRAINTS"}
```

### Request with query variables and version 2 on JSONCompactEachRow format[​](#request-with-query-variables-and-version-2-on-jsoncompacteachrow-format "Direct link to Request with query variables and version 2 on JSONCompactEachRow format")

**Query API Endpoint SQL:**

```
SELECT name, database FROM system.tables WHERE match(name, {tableNameRegex: String}) AND database = {database: String};
```

- GET (cURL)- POST (cURL)- JavaScript

```
curl 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONCompactEachRow&param_tableNameRegex=query.*&param_database=system' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'x-clickhouse-endpoint-version: 2'
```

```
["query_cache", "system"]
["query_log", "system"]
["query_views_log", "system"]
```

```
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONCompactEachRow' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2' \
-d '{ "queryVariables": { "tableNameRegex": "query.*", "database": "system" } }'
```

```
fetch(
  "https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONCompactEachRow",
  {
    method: "POST",
    headers: {
      Authorization: "Basic <base64_encoded_credentials>",
      "Content-Type": "application/json",
      "x-clickhouse-endpoint-version": "2",
    },
    body: JSON.stringify({
      queryVariables: {
        tableNameRegex: "query.*",
        database: "system",
      },
    }),
  }
)
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));
```

```
["query_cache", "system"]
["query_log", "system"]
["query_views_log", "system"]
```

### Request with array in the query variables that inserts data into a table[​](#request-with-array-in-the-query-variables-that-inserts-data-into-a-table "Direct link to Request with array in the query variables that inserts data into a table")

**Table SQL:**

```
CREATE TABLE default.t_arr
(
    `arr` Array(Array(Array(UInt32)))
)
ENGINE = MergeTree
ORDER BY tuple()
```

**Query API Endpoint SQL:**

```
INSERT INTO default.t_arr VALUES ({arr: Array(Array(Array(UInt32)))});
```

- cURL- JavaScript