Configurando endpoints da Query API - ClickHouse Documentation

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ínimasPara 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, 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 linhasO 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”.

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

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:

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:

Inclua o header x-clickhouse-endpoint-upgrade com o valor 1
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
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));

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

Resposta

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

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

Resposta

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

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
JavaScript

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

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)
POST (cURL)
JavaScript

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

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' \

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 stream`

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

  reader.on("error", (err) => {
    console.error("Erro no stream:", 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"}
...
> 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:

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

​Pré-requisitos

​Criar uma consulta salva

​Configurar o endpoint da Query API

​Parâmetros da API de consulta

​Testes e monitoramento

​Detalhes de implementação

​Métodos HTTP

​Autenticação

​Configuração da requisição

​Parâmetros da URL

​Parâmetros da consulta

​Cabeçalhos

​Corpo da requisição

​Parâmetros

​Formatos compatíveis

​Respostas

​Sucesso

​Códigos de erro

​Boas práticas para tratamento de erros

​Atualizando versões de endpoint

​Exemplos

​Requisição básica

​Versão 1

​Versão 2

​Requisição com variáveis de consulta, versão 2 e formato JSONCompactEachRow

​Requisição com array nas variáveis da consulta que insere dados em uma tabela

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

​Solicite a resposta e faça o parse como stream`

​Inserir um fluxo de dados de um arquivo em uma tabela

Pré-requisitos

Criar uma consulta salva

Configurar o endpoint da Query API

Parâmetros da API de consulta

Testes e monitoramento

Detalhes de implementação

Métodos HTTP

Autenticação

Configuração da requisição

Parâmetros da URL

Parâmetros da consulta

Cabeçalhos

Corpo da requisição

Parâmetros

Formatos compatíveis

Respostas

Sucesso

Códigos de erro

Boas práticas para tratamento de erros

Atualizando versões de endpoint

Exemplos

Requisição básica

Versão 1

Versão 2

Requisição com variáveis de consulta, versão 2 e formato JSONCompactEachRow

Requisição com array nas variáveis da consulta que insere dados em uma tabela

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

Solicite a resposta e faça o parse como stream`

Inserir um fluxo de dados de um arquivo em uma tabela