Configuración de endpoint de la API de consultas

Cree fácilmente endpoints de API REST a partir de sus consultas guardadas

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.

Permisos mínimos

Para consultar un endpoint de API, la clave de API necesita el rol de organización Member con acceso al servicio Query Endpoints. El rol de la base de datos se configura cuando creas el endpoint.

1. ​

   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.

   Aplicar LIMIT al número de filas

   El tutorial del dataset de ejemplo inserta una gran cantidad de datos: 4,65 mil millones de filas, lo que puede tardar algún tiempo. Para esta guía, recomendamos usar la cláusula LIMIT para insertar una cantidad menor de datos, por ejemplo, 10 millones de filas.

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

2. ​

   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 API podrán acceder al endpoint:

   Después de seleccionar una clave 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>'
   
3. ​

   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.

4. ​

   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:

1. Incluya el encabezado x-clickhouse-endpoint-upgrade establecido en 1
2. 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

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

Respuesta

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

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'

Respuesta

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

Respuesta

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

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'

Respuesta

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

Respuesta

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

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

Respuesta

OK

​

Solicitud con el ajuste de ClickHouse max_threads establecido en 8

SQL del endpoint de la API de consultas:

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

​

Solicitar y procesar la respuesta como un flujo

SQL de endpoint de la API de consultas:

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

Salida

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