> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Cree fácilmente endpoints de API REST a partir de sus consultas guardadas
# Configuración de endpoint de la API de consultas
export const Image = ({img, alt, size}) => {
return
;
};
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](/es/products/cloud/features/admin-features/api/openapi) 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.
### 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](/es/get-started/sample-datasets/youtube-dislikes), que contiene aproximadamente 4,5 mil millones de registros.
Sigue los pasos de la sección ["Create table"](/es/get-started/sample-datasets/youtube-dislikes#create-the-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.
```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
```
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"](/es/products/cloud/features/sql-console-features/sql-console#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 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:
```bash theme={null}
curl -H "Content-Type: application/json" -s --user ':' '?format=JSONEachRow¶m_year='
```
### 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:**
```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 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](/es/reference/settings/session-settings) admitido | `?max_threads=8` |
| 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:**
```sql theme={null}
SELECT database, name AS num_tables FROM system.tables LIMIT 3;
```
#### Versión 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="Respuesta" 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"]
]
}
}
```
#### Versión 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="Respuesta" 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="Respuesta" theme={null}
{"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:**
```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="Respuesta" 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="Respuesta" theme={null}
["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:**
```SQL theme={null}
CREATE TABLE default.t_arr
(
`arr` Array(Array(Array(UInt32)))
)
ENGINE = MergeTree
ORDER BY tuple()
```
**SQL del endpoint de la API de consultas:**
```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="Respuesta" theme={null}
OK
```
### Solicitud con el ajuste de ClickHouse `max_threads` establecido en 8
**SQL del endpoint de la API de consultas:**
```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));
```
### Solicitar y procesar la respuesta como un flujo\`
**SQL de endpoint de la API de consultas:**
```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(`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//run?format=JSONEachRow";
const openApiKeyId = "";
const openApiKeySecret = "";
// Ejemplo de uso
fetchAndLogChunks(endpointUrl, openApiKeyId, openApiKeySecret).catch((err) =>
console.error(err)
);
```
```shell title="Salida" theme={null}
> 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:
```csv theme={null}
"user_id","json","name"
"1","{""name"":""John"",""age"":30}","John"
"2","{""name"":""Jane"",""age"":25}","Jane"
```
**SQL de 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 del endpoint de la API de consultas:**
```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 @-
```