Configurando endpoints da Query API

Crie facilmente endpoints de API REST a partir de suas consultas salvas

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 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.

1. ​

   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, que contém aproximadamente 4,5 bilhões de registros. Siga as etapas da seção “Create 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.

   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”.

2. ​

   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:

   curl -H "Content-Type: application/json" -s --user '<key_id>:<key_secret>' '<API-endpoint>?format=JSONEachRow&param_year=<value>'
   
3. ​

   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.

4. ​

   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:

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 compatível	?max_threads=8

​

Cabeçalhos

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:

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

​

Versão 1

cURL

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

JavaScript

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));

Resposta

{
  "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

GET (cURL)

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

Resposta

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

POST (cURL)

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'

JavaScript

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));

Resposta

{"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:

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

GET (cURL)

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'

Resposta

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

POST (cURL)

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

JavaScript

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));

Resposta

["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:

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

SQL do Query API Endpoint:

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

cURL

curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2' \
-d '{
  "queryVariables": {
    "arr": [[[12, 13, 0, 1], [12]]]
  }
}'

JavaScript

fetch(
  "https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run",
  {
    method: "POST",
    headers: {
      Authorization: "Basic <base64_encoded_credentials>",
      "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));

Resposta

OK

​

Requisição com a configuração max_threads do ClickHouse definida como 8

SQL do Query API Endpoint:

SELECT * FROM system.tables;

GET (cURL)

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

POST (cURL)

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

JavaScript

fetch(
  "https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?max_threads=8",
  {
    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));

​

Solicite a resposta e faça o parse como fluxo

SQL do Query API Endpoint:

SELECT name, database FROM system.tables;

TypeScript

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("Fluxo encerrado.");
  });

  reader.on("error", (err) => {
    console.error("Erro no fluxo:", err);
  });
}

const endpointUrl =
  "https://console-api.clickhouse.cloud/.api/query-endpoints/<id do endpoint>/run?format=JSONEachRow";
const openApiKeyId = "<myOpenApiKeyId>";
const openApiKeySecret = "<myOpenApiKeySecret>";
// Exemplo de uso
fetchAndLogChunks(endpointUrl, openApiKeyId, openApiKeySecret).catch((err) =>
  console.error(err)
);

Saída

> npx tsx index.ts
> {"name":"COLUMNS","database":"INFORMATION_SCHEMA"}
> {"name":"KEY_COLUMN_USAGE","database":"INFORMATION_SCHEMA"}
...
> Fluxo 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:

"user_id","json","name"
"1","{""name"":""John"",""age"":30}","John"
"2","{""name"":""Jane"",""age"":25}","Jane"

SQL para CREATE TABLE:

create table default.my_first_table
(
    user_id String,
    json String,
    name String,
) ENGINE = MergeTree()
ORDER BY user_id;

SQL do Query API Endpoint:

INSERT INTO default.my_first_table

cat ./samples/my_first_table_2024-07-11.csv | curl --user '<openApiKeyId:openApiKeySecret>' \
                                                   -X POST \
                                                   -H 'Content-Type: application/octet-stream' \
                                                   -H 'x-clickhouse-endpoint-version: 2' \
                                                   "https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=CSV" \
                                                   --data-binary @-