Configuración de endpoint de la API de consultas

La función endpoint de la API de consultas le permite crear un endpoint de API directamente a partir de cualquier consulta SQL guardada en la consola de ClickHouse Cloud. Podrá acceder a los endpoints de API a través de HTTP para ejecutar sus consultas guardadas sin necesidad de conectarse a su servicio de ClickHouse Cloud mediante un driver nativo.

Requisitos previos

Antes de continuar, asegúrate de tener lo siguiente:

Una clave de API con los permisos adecuados
Un rol de Admin Console

Puedes seguir esta guía para crear una clave de API si aún no tienes una.

Crear una consulta guardada

Si ya tienes una consulta guardada, puedes omitir este paso.

Abre una nueva pestaña de consulta. Para esta demostración, usaremos el dataset de YouTube, que contiene aproximadamente 4,5 mil millones de registros. Sigue los pasos de la sección "Create table" para crear la tabla en tu servicio Cloud e insertar datos en ella.

Como consulta de ejemplo, devolveremos los 10 uploaders con mayor promedio de visualizaciones por vídeo, usando un parámetro year introducido por el usuario.

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

Ten en cuenta que esta consulta contiene un parámetro (year), que aparece resaltado en el fragmento anterior. Puedes especificar parámetros de consulta usando { } junto con el tipo del parámetro. El editor de consultas de la consola SQL detecta automáticamente las expresiones de parámetros de consulta de ClickHouse y proporciona un campo de entrada para cada parámetro.

Vamos a ejecutar rápidamente esta consulta para asegurarnos de que funciona, especificando el año 2010 en el campo de variables de consulta situado a la derecha del editor SQL:

A continuación, guarda la consulta:

Puedes encontrar más documentación sobre las consultas guardadas en la sección "Saving a query".

Configurar el endpoint de la API de consultas

Los endpoints de la API de consultas se pueden configurar directamente desde la vista de consulta haciendo clic en el botón Share y seleccionando API Endpoint. Se te pedirá que especifiques qué claves de API podrán acceder al endpoint:

Después de seleccionar una clave de API, se te pedirá que:

Selecciones el rol de base de datos que se usará para ejecutar la consulta (Full access, Read only o Create a custom role)
Especifiques los dominios permitidos para el uso compartido de recursos entre orígenes (CORS)

Después de seleccionar estas opciones, el endpoint de la API de consultas se aprovisionará automáticamente.

Se mostrará un comando curl de ejemplo para que puedas enviar una solicitud de prueba:

A continuación se muestra, para mayor comodidad, el comando curl que aparece en la interfaz:

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

Parámetros de la API de consultas

Los parámetros de consulta pueden especificarse con la sintaxis {parameter_name: type}. Estos parámetros se detectarán automáticamente y el payload de solicitud de ejemplo contendrá un objeto queryVariables mediante el cual podrás pasarlos.

Pruebas y monitorización

Una vez creado un endpoint de la API de consultas, puedes comprobar que funciona usando curl o cualquier otro cliente HTTP:

Después de enviar tu primera solicitud, debería aparecer de inmediato un nuevo botón a la derecha del botón Share. Al hacer clic en él, se abrirá un panel lateral con datos de monitorización sobre la consulta:

Detalles de implementación

Este endpoint ejecuta consultas en los endpoints de endpoint de la API de consultas que has guardado. Admite varias versiones, formatos de respuesta flexibles, consultas parametrizadas y respuestas en streaming opcionales (solo en la versión 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 con parámetros	Pase las variables de consulta mediante parámetros de URL (`?param_name=value`)
POST	Consultas complejas o cuando se usa el cuerpo de la solicitud	Pase las variables de consulta en el cuerpo de la solicitud (objeto `queryVariables`)

Cuándo usar GET:

Consultas simples sin datos anidados complejos
Los parámetros pueden codificarse fácilmente en la URL
El almacenamiento en caché se beneficia de la semántica de HTTP GET

Cuándo usar POST:

Variables de consulta complejas (arrays, objetos, cadenas largas)
Cuando se prefiere el cuerpo de la solicitud por motivos de seguridad o privacidad
Subida de archivos en streaming o grandes volúmenes de datos

Autenticación

Requerido: Sí Método: Autenticación básica con OpenAPI Key/Secret Permisos: Permisos adecuados para el endpoint de consulta

Configuración de la solicitud

Parámetros de URL

Parámetro	Obligatorio	Descripción
`queryEndpointId`	Sí	El identificador único del endpoint de consulta que se ejecutará

Parámetros de consulta

Parámetro	Obligatorio	Descripción	Ejemplo
`format`	No	Formato de la respuesta (admite todos los formatos de ClickHouse)	`?format=JSONEachRow`
`param_:name`	No	Variables de la consulta cuando el cuerpo de la solicitud es un flujo. Reemplaza `:name` por el nombre de tu variable	`?param_year=2024`
`request_timeout`	No	Tiempo de espera de la consulta en milisegundos (valor predeterminado: 30000)	`?request_timeout=60000`
`:clickhouse_setting`	No	Cualquier ajuste de ClickHouse admitido	`?max_threads=8`

Cabeceras

Cabecera	Obligatorio	Descripción	Valores
`x-clickhouse-endpoint-version`	No	Especifica la versión del endpoint	`1` o `2` (de forma predeterminada, la última versión guardada)
`x-clickhouse-endpoint-upgrade`	No	Desencadena la actualización de la versión del endpoint (úselo con la cabecera de versión)	`1` para actualizar

Cuerpo de la solicitud

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`queryVariables`	objeto	No	Variables que se usarán en la consulta
`format`	String	No	Formato de la respuesta

Formatos compatibles

Versión	Formatos compatibles
Versión 2	Todos los formatos compatibles con ClickHouse
Versión 1 (limitada)	TabSeparated TabSeparatedWithNames TabSeparatedWithNamesAndTypes JSON JSONEachRow CSV CSVWithNames CSVWithNamesAndTypes

Respuestas

Éxito

Status: 200 OK La consulta se ejecutó correctamente.

Códigos de error

Código de estado	Descripción
`400 Bad Request`	La solicitud estaba mal formada
`401 Unauthorized`	Falta autenticación o no hay permisos suficientes
`404 Not Found`	No se encontró el endpoint de consulta especificado

Buenas prácticas para la gestión de errores

Asegúrese de incluir credenciales de autenticación válidas en la solicitud
Valide queryEndpointId y queryVariables antes de enviarlos
Implemente una gestión de errores adecuada con mensajes de error claros

Actualización de versiones del endpoint

Para actualizar de la versión 1 a la versión 2:

Incluya el encabezado x-clickhouse-endpoint-upgrade establecido en 1
Incluya el encabezado x-clickhouse-endpoint-version establecido en 2

Esto habilita el acceso a las funciones de la versión 2, entre ellas:

Compatibilidad con todos los formatos de ClickHouse
Capacidades de streaming de respuestas
Mejoras de rendimiento y funcionalidad

Ejemplos

Solicitud básica

SQL del endpoint de la API de consultas:

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

Versión 1

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

Respuestajson

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

Versión 2

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

Respuestaapplication/x-ndjson

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

Respuestaapplication/x-ndjson

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

Solicitud con variables de consulta y versión 2 en formato JSONCompactEachRow

SQL del endpoint de la API de consultas:

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

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'

Respuestaapplication/x-ndjson

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

Respuestaapplication/x-ndjson

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

Solicitud con un array en las variables de la consulta para insertar datos en una tabla

SQL de la tabla:

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

SQL del endpoint de la API de consultas:

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

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

Respuestatext

OK

Solicitud con el ajuste de ClickHouse `max_threads` establecido en 8

SQL del endpoint de la API de consultas:

SELECT * FROM system.tables;

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

Solicitar y procesar la respuesta como un flujo

SQL de endpoint de la API de consultas:

SELECT name, database FROM system.tables;

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(`HTTP error! 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 ended.");
  });

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

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

Salidashell

> npx tsx index.ts
> {"name":"COLUMNS","database":"INFORMATION_SCHEMA"}
> {"name":"KEY_COLUMN_USAGE","database":"INFORMATION_SCHEMA"}
...
> Stream ended.

Insertar un flujo de datos desde un archivo en una tabla

Cree un archivo ./samples/my_first_table_2024-07-11.csv con el siguiente contenido:

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

SQL de CREATE TABLE:

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

SQL del endpoint de la API de consultas:

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

Configuración de endpoint de la API de consultas

Requisitos previos

Detalles de implementación

Métodos HTTP

Autenticación

Configuración de la solicitud

Parámetros de URL

Parámetros de consulta

Cabeceras

Cuerpo de la solicitud

Parámetros

Formatos compatibles

Respuestas

Éxito

Códigos de error

Buenas prácticas para la gestión de errores

Actualización de versiones del endpoint

Ejemplos

Solicitud básica

Versión 1

Versión 2

Solicitud con variables de consulta y versión 2 en formato JSONCompactEachRow

Solicitud con un array en las variables de la consulta para insertar datos en una tabla

Solicitud con el ajuste de ClickHouse max_threads establecido en 8

Solicitar y procesar la respuesta como un flujo

Insertar un flujo de datos desde un archivo en una tabla

Solicitud con el ajuste de ClickHouse `max_threads` establecido en 8