> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Crie facilmente endpoints de API REST a partir de suas consultas salvas
# Configurando endpoints da Query API
export const Image = ({img, alt, size}) => {
return
;
};
O recurso **endpoint da Query API** permite criar um endpoint de API diretamente de qualquer consulta SQL salva no console do ClickHouse Cloud. Você poderá acessar esses endpoints via HTTP para executar suas consultas salvas sem precisar se conectar ao seu serviço do ClickHouse Cloud por meio de um driver nativo.
## Pré-requisitos
Antes de prosseguir, verifique se você tem:
* Uma chave de API com as permissões adequadas
* Uma Role de Admin no Console
Você pode seguir este guia para [criar uma chave de API](/pt-BR/products/cloud/features/admin-features/api/openapi) caso ainda não tenha uma.
**Permissões mínimas**
Para consultar um endpoint de API, a chave de API precisa ter a role de organização `Member` com acesso ao serviço `Query Endpoints`. A role do banco de dados é configurada quando você cria o endpoint.
### Criar uma consulta salva
Se você já tiver uma consulta salva, pode pular esta etapa.
Abra uma nova aba de consulta. Para fins de demonstração, usaremos o [conjunto de dados do YouTube](/pt-BR/get-started/sample-datasets/youtube-dislikes), que contém aproximadamente 4,5 bilhões de registros.
Siga as etapas da seção ["Create table"](/pt-BR/get-started/sample-datasets/youtube-dislikes#create-the-table) para criar a tabela no seu serviço Cloud e inserir dados nela.
**Use `LIMIT` para limitar o número de linhas**
O tutorial do conjunto de dados de exemplo insere muitos dados — 4,65 bilhões de linhas — e isso pode levar algum tempo.
Para este guia, recomendamos usar a cláusula `LIMIT` para inserir uma quantidade menor de dados,
por exemplo, 10 milhões de linhas.
Como exemplo de consulta, vamos retornar os 10 uploaders com a maior média de visualizações por vídeo com base em um parâmetro `year` informado pelo usuário.
```sql highlight={11} theme={null}
WITH sum(view_count) AS view_sum,
round(view_sum / num_uploads, 2) AS per_upload
SELECT
uploader,
count() AS num_uploads,
formatReadableQuantity(view_sum) AS total_views,
formatReadableQuantity(per_upload) AS views_per_video
FROM
youtube
WHERE
toYear(upload_date) = {year: UInt16}
GROUP BY uploader
ORDER BY per_upload desc
LIMIT 10
```
Observe que esta consulta contém um parâmetro (`year`), destacado no trecho acima.
Você pode especificar parâmetros de consulta usando `{ }` junto com o tipo do parâmetro.
O editor de consultas do console SQL detecta automaticamente expressões de parâmetros de consulta do ClickHouse e exibe um campo para cada parâmetro.
Vamos executar essa consulta rapidamente para garantir que ela funcione, informando o ano `2010` no campo de variáveis da consulta, no lado direito do editor SQL:
Em seguida, salve a consulta:
Mais informações sobre consultas salvas podem ser encontradas na seção ["Saving a query"](/pt-BR/products/cloud/features/sql-console-features/sql-console#saving-a-query).
### Configurar o endpoint da Query API
Os endpoints da Query API podem ser configurados diretamente na tela da consulta clicando no botão **Share** e selecionando `API Endpoint`.
Será solicitado que você especifique quais chaves de API poderão acessar o endpoint:
Após selecionar uma chave de API, será solicitado que você:
* Selecione a role do banco de dados que será usada para executar a consulta (`Full access`, `Read only` ou `Create a custom role`)
* Especifique os domínios permitidos para compartilhamento de recursos entre origens (CORS)
Depois de selecionar essas opções, o endpoint da Query API será provisionado automaticamente.
Um comando `curl` de exemplo será exibido para que você possa enviar uma solicitação de teste:
O comando `curl` exibido na interface é fornecido abaixo para sua conveniência:
```bash theme={null}
curl -H "Content-Type: application/json" -s --user ':' '?format=JSONEachRow¶m_year='
```
### Parâmetros da API de consulta
Os parâmetros de consulta podem ser especificados com a sintaxe `{parameter_name: type}`. Esses parâmetros serão detectados automaticamente, e o payload da solicitação de exemplo conterá um objeto `queryVariables` por meio do qual você poderá passá-los.
### Testes e monitoramento
Depois que um endpoint da Query API for criado, você poderá testá-lo usando `curl` ou qualquer outro cliente HTTP:
Depois de enviar sua primeira solicitação, um novo botão deverá aparecer imediatamente à direita do botão **Share**. Ao clicar nele, será aberto um flyout contendo dados de monitoramento sobre a consulta:
## Detalhes de implementação
Este endpoint executa consultas em seus endpoints salvos da Query API.
Ele oferece suporte a várias versões, formatos de resposta flexíveis, consultas parametrizadas e respostas opcionais em streaming (apenas na versão 2).
**Endpoint:**
```text theme={null}
GET /query-endpoints/{queryEndpointId}/run
POST /query-endpoints/{queryEndpointId}/run
```
### Métodos HTTP
| Método | Caso de uso | Parâmetros |
| -------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **GET** | Consultas simples com parâmetros | Passe variáveis de consulta por parâmetros na URL (`?param_name=value`) |
| **POST** | Consultas complexas ou quando se usa o corpo da requisição | Passe variáveis de consulta no corpo da requisição (objeto `queryVariables`) |
**Quando usar GET:**
* Consultas simples sem dados aninhados complexos
* Os parâmetros podem ser codificados facilmente na URL
* A semântica do HTTP GET favorece o cache
**Quando usar POST:**
* Variáveis de consulta complexas (arrays, objetos, strings longas)
* Quando o corpo da requisição for preferível por motivos de segurança/privacidade
* Upload de arquivos em streaming ou grandes volumes de dados
### Autenticação
**Obrigatório:** Sim
**Método:** Basic Auth com OpenAPI Key/Secret
**Permissões:** Permissões adequadas para o endpoint de consulta
### Configuração da requisição
#### Parâmetros da URL
| Parâmetro | Obrigatório | Descrição |
| ----------------- | ----------- | ---------------------------------------------------------------- |
| `queryEndpointId` | **Sim** | O identificador único do endpoint de consulta que será executado |
#### Parâmetros da consulta
| Parâmetro | Obrigatório | Descrição | Exemplo |
| --------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- | ------------------------ |
| `format` | Não | Formato da resposta (compatível com todos os formatos do ClickHouse) | `?format=JSONEachRow` |
| `param_:name` | Não | Variáveis da consulta quando o corpo da requisição é um fluxo. Substitua `:name` pelo nome da sua variável | `?param_year=2024` |
| `request_timeout` | Não | Tempo limite da consulta em milissegundos (padrão: 30000) | `?request_timeout=60000` |
| `:clickhouse_setting` | Não | Qualquer [configuração do ClickHouse](/pt-BR/reference/settings/session-settings) compatível | `?max_threads=8` |
| Cabeçalho | Obrigatório | Descrição | Valores |
| ------------------------------- | ----------- | --------------------------------------------------------------------------- | --------------------------------------------- |
| `x-clickhouse-endpoint-version` | Não | Especifica a versão do endpoint | `1` ou `2` (o padrão é a última versão salva) |
| `x-clickhouse-endpoint-upgrade` | Não | Dispara a atualização da versão do endpoint (use com o cabeçalho de versão) | `1` para atualizar |
***
### Corpo da requisição
#### Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
| ---------------- | ------ | ----------- | ------------------------------------ |
| `queryVariables` | object | Não | Variáveis a serem usadas na consulta |
| `format` | string | Não | Formato da resposta |
#### Formatos compatíveis
| Versão | Formatos compatíveis |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Versão 2** | Todos os formatos compatíveis com o ClickHouse |
| **Versão 1 (limitada)** | TabSeparated
TabSeparatedWithNames
TabSeparatedWithNamesAndTypes
JSON
JSONEachRow
CSV
CSVWithNames
CSVWithNamesAndTypes |
***
### Respostas
#### Sucesso
**Status:** `200 OK`
A consulta foi executada com êxito.
#### Códigos de erro
| Código de status | Descrição |
| ------------------ | ------------------------------------------------------ |
| `400 Bad Request` | A solicitação estava malformada |
| `401 Unauthorized` | Falta de autenticação ou permissões insuficientes |
| `404 Not Found` | O endpoint de consulta especificado não foi encontrado |
#### Boas práticas para tratamento de erros
* Certifique-se de incluir credenciais de autenticação válidas na solicitação
* Valide o `queryEndpointId` e as `queryVariables` antes de enviar
* Implemente um tratamento de erros adequado, com mensagens de erro apropriadas
***
### Atualizando versões de endpoint
Para atualizar da versão 1 para a versão 2:
1. Inclua o header `x-clickhouse-endpoint-upgrade` com o valor `1`
2. Inclua o header `x-clickhouse-endpoint-version` com o valor `2`
Isso habilita o acesso aos recursos da versão 2, incluindo:
* Suporte a todos os formatos do ClickHouse
* Capacidade de transmitir respostas em streaming
* Desempenho e funcionalidade aprimorados
## Exemplos
### Requisição básica
**SQL do Query API Endpoint:**
```sql theme={null}
SELECT database, name AS num_tables FROM system.tables LIMIT 3;
```
#### Versão 1
```bash theme={null}
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints//run' \
--user '' \
-H 'Content-Type: application/json' \
-d '{ "format": "JSONEachRow" }'
```
```javascript theme={null}
fetch(
"https://console-api.clickhouse.cloud/.api/query-endpoints//run",
{
method: "POST",
headers: {
Authorization: "Basic ",
"Content-Type": "application/json",
},
body: JSON.stringify({
format: "JSONEachRow",
}),
}
)
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
```
```json title="Resposta" theme={null}
{
"data": {
"columns": [
{
"name": "database",
"type": "String"
},
{
"name": "num_tables",
"type": "String"
}
],
"rows": [
["INFORMATION_SCHEMA", "COLUMNS"],
["INFORMATION_SCHEMA", "KEY_COLUMN_USAGE"],
["INFORMATION_SCHEMA", "REFERENTIAL_CONSTRAINTS"]
]
}
}
```
#### Versão 2
```bash theme={null}
curl 'https://console-api.clickhouse.cloud/.api/query-endpoints//run?format=JSONEachRow' \
--user '' \
-H 'x-clickhouse-endpoint-version: 2'
```
```application/x-ndjson title="Resposta" theme={null}
{"database":"INFORMATION_SCHEMA","num_tables":"COLUMNS"}
{"database":"INFORMATION_SCHEMA","num_tables":"KEY_COLUMN_USAGE"}
{"database":"INFORMATION_SCHEMA","num_tables":"REFERENTIAL_CONSTRAINTS"}
```
```bash theme={null}
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints//run?format=JSONEachRow' \
--user '' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2'
```
```javascript theme={null}
fetch(
"https://console-api.clickhouse.cloud/.api/query-endpoints//run?format=JSONEachRow",
{
method: "POST",
headers: {
Authorization: "Basic ",
"Content-Type": "application/json",
"x-clickhouse-endpoint-version": "2",
},
}
)
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
```
```application/x-ndjson title="Resposta" theme={null}
{"database":"INFORMATION_SCHEMA","num_tables":"COLUMNS"}
{"database":"INFORMATION_SCHEMA","num_tables":"KEY_COLUMN_USAGE"}
{"database":"INFORMATION_SCHEMA","num_tables":"REFERENTIAL_CONSTRAINTS"}
```
### Requisição com variáveis de consulta, versão 2 e formato JSONCompactEachRow
**SQL do Query API Endpoint:**
```sql theme={null}
SELECT name, database FROM system.tables WHERE match(name, {tableNameRegex: String}) AND database = {database: String};
```
```bash theme={null}
curl 'https://console-api.clickhouse.cloud/.api/query-endpoints//run?format=JSONCompactEachRow¶m_tableNameRegex=query.*¶m_database=system' \
--user '' \
-H 'x-clickhouse-endpoint-version: 2'
```
```application/x-ndjson title="Resposta" theme={null}
["query_cache", "system"]
["query_log", "system"]
["query_views_log", "system"]
```
```bash theme={null}
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints//run?format=JSONCompactEachRow' \
--user '' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2' \
-d '{ "queryVariables": { "tableNameRegex": "query.*", "database": "system" } }'
```
```javascript theme={null}
fetch(
"https://console-api.clickhouse.cloud/.api/query-endpoints//run?format=JSONCompactEachRow",
{
method: "POST",
headers: {
Authorization: "Basic ",
"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));
```
```application/x-ndjson title="Resposta" theme={null}
["query_cache", "system"]
["query_log", "system"]
["query_views_log", "system"]
```
### Requisição com array nas variáveis da consulta que insere dados em uma tabela
**SQL da tabela:**
```SQL theme={null}
CREATE TABLE default.t_arr
(
`arr` Array(Array(Array(UInt32)))
)
ENGINE = MergeTree
ORDER BY tuple()
```
**SQL do Query API Endpoint:**
```sql theme={null}
INSERT INTO default.t_arr VALUES ({arr: Array(Array(Array(UInt32)))});
```
```bash theme={null}
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints//run' \
--user '' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2' \
-d '{
"queryVariables": {
"arr": [[[12, 13, 0, 1], [12]]]
}
}'
```
```javascript theme={null}
fetch(
"https://console-api.clickhouse.cloud/.api/query-endpoints//run",
{
method: "POST",
headers: {
Authorization: "Basic ",
"Content-Type": "application/json",
"x-clickhouse-endpoint-version": "2",
},
body: JSON.stringify({
queryVariables: {
arr: [[[12, 13, 0, 1], [12]]],
},
}),
}
)
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
```
```text title="Resposta" theme={null}
OK
```
### Requisição com a configuração `max_threads` do ClickHouse definida como 8
**SQL do Query API Endpoint:**
```sql theme={null}
SELECT * FROM system.tables;
```
```bash theme={null}
curl 'https://console-api.clickhouse.cloud/.api/query-endpoints//run?max_threads=8' \
--user '' \
-H 'x-clickhouse-endpoint-version: 2'
```
```bash theme={null}
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints//run?max_threads=8,' \
--user '' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2' \
```
```javascript theme={null}
fetch(
"https://console-api.clickhouse.cloud/.api/query-endpoints//run?max_threads=8",
{
method: "POST",
headers: {
Authorization: "Basic ",
"Content-Type": "application/json",
"x-clickhouse-endpoint-version": "2",
},
}
)
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
```
### Solicite a resposta e faça o parse como stream\`
**SQL do Query API Endpoint:**
```sql theme={null}
SELECT name, database FROM system.tables;
```
```typescript theme={null}
async function fetchAndLogChunks(
url: string,
openApiKeyId: string,
openApiKeySecret: string
) {
const auth = Buffer.from(`${openApiKeyId}:${openApiKeySecret}`).toString(
"base64"
);
const headers = {
Authorization: `Basic ${auth}`,
"x-clickhouse-endpoint-version": "2",
};
const response = await fetch(url, {
headers,
method: "POST",
body: JSON.stringify({ format: "JSONEachRow" }),
});
if (!response.ok) {
console.error(`Erro HTTP! Status: ${response.status}`);
return;
}
const reader = response.body as unknown as Readable;
reader.on("data", (chunk) => {
console.log(chunk.toString());
});
reader.on("end", () => {
console.log("Stream encerrado.");
});
reader.on("error", (err) => {
console.error("Erro no stream:", err);
});
}
const endpointUrl =
"https://console-api.clickhouse.cloud/.api/query-endpoints//run?format=JSONEachRow";
const openApiKeyId = "";
const openApiKeySecret = "";
// Exemplo de uso
fetchAndLogChunks(endpointUrl, openApiKeyId, openApiKeySecret).catch((err) =>
console.error(err)
);
```
```shell title="Saída" theme={null}
> npx tsx index.ts
> {"name":"COLUMNS","database":"INFORMATION_SCHEMA"}
> {"name":"KEY_COLUMN_USAGE","database":"INFORMATION_SCHEMA"}
...
> Stream encerrado.
```
### Inserir um fluxo de dados de um arquivo em uma tabela
Crie um arquivo `./samples/my_first_table_2024-07-11.csv` com o seguinte conteúdo:
```csv theme={null}
"user_id","json","name"
"1","{""name"":""John"",""age"":30}","John"
"2","{""name"":""Jane"",""age"":25}","Jane"
```
**SQL para CREATE TABLE:**
```sql theme={null}
create table default.my_first_table
(
user_id String,
json String,
name String,
) ENGINE = MergeTree()
ORDER BY user_id;
```
**SQL do Query API Endpoint:**
```sql theme={null}
INSERT INTO default.my_first_table
```
```bash theme={null}
cat ./samples/my_first_table_2024-07-11.csv | curl --user '' \
-X POST \
-H 'Content-Type: application/octet-stream' \
-H 'x-clickhouse-endpoint-version: 2' \
"https://console-api.clickhouse.cloud/.api/query-endpoints//run?format=CSV" \
--data-binary @-
```