> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Compatibilidad con la API HTTP de Prometheus en ClickHouse: escritura remota, lectura remota y consultas PromQL sobre una tabla TimeSeries.

# API HTTP de Prometheus y PromQL

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'Vista previa privada'}
        </div>;
};

<PrivatePreviewBadge />

ClickHouse implementa la API HTTP de Prometheus sobre una tabla [`TimeSeries`](/es/reference/engines/table-engines/integrations/time-series). Un handler gestiona la escritura remota, la lectura remota, las consultas PromQL instantáneas y las consultas PromQL de rango.

Para exponer las propias métricas de ClickHouse y que un servidor de Prometheus las recopile, consulta el [endpoint de métricas de Prometheus](/es/concepts/features/interfaces/prometheus-metrics).

<h2 id="prerequisites">
  Requisitos previos
</h2>

Los pasos de configuración difieren entre ClickHouse Cloud y ClickHouse autogestionado. Siga la sección correspondiente a su Implementación.

<h3 id="prerequisites-cloud">
  ClickHouse Cloud
</h3>

<Note>
  La compatibilidad con PromQL en ClickHouse Cloud está en private preview. Los servicios que participan en la private preview ya tienen configurado el SETTING `enable_time_series_table` y los API endpoints de Prometheus. El resto de los servicios de ClickHouse Cloud no cuentan con esta configuración, y no es posible habilitar la feature por cuenta propia en dichos servicios. La sentencia `SET enable_time_series_table` y la configuración `http_handlers` de las secciones siguientes se aplican a Implementaciones autogestionadas.
</Note>

Si su servicio participa en la private preview, continúe en [Crear una tabla TimeSeries](#create-a-timeseries-table). El servicio expone las rutas de endpoint que se enumeran en la [tabla de endpoints](#configure-prometheus-api).

<h3 id="enable-the-timeseries-setting">
  Autogestionado: habilite el SETTING TimeSeries
</h3>

Habilite el SETTING `enable_time_series_table` para el usuario que crea la tabla y accede a ella:

```sql theme={null}
SET enable_time_series_table = 1;
```

Para las solicitudes a la API HTTP, habilite `enable_time_series_table` en el perfil del usuario de la API.

<h3 id="configure-prometheus-api">
  Autogestionado: configure los endpoints de la API de Prometheus
</h3>

Configure un handler enrutado por prefijo en el puerto HTTP principal de ClickHouse:

```xml theme={null}
<http_handlers>
    <defaults/>
    <rule>
        <url_prefix>/prometheus/api/v1</url_prefix>
        <handler>
            <type>prometheus_api_v1</type>
        </handler>
    </rule>
</http_handlers>
```

`<defaults/>` conserva los handler integrados para endpoints como `/ping` y para solicitudes SQL. El prefijo anterior expone estos endpoints mediante un único handler:

| Endpoint | Finalidad |
| - | - |
| `/prometheus/api/v1/write` | Escritura remota de Prometheus |
| `/prometheus/api/v1/read` | Lectura remota de Prometheus |
| `/prometheus/api/v1/query` | Consultas PromQL instantáneas |
| `/prometheus/api/v1/query_range` | Consultas PromQL de rango |
| `/prometheus/api/v1/format_query` | Formato de expresiones PromQL |
| `/prometheus/api/v1/series` | Metadatos de series |
| `/prometheus/api/v1/metadata` | Metadatos de la familia de métricas |

El ejemplo omite `database` y `table` del handler. Cada solicitud debe incluir el parámetro de consulta `table` (excepto `/format_query`, que solo analiza la expresión PromQL indicada y no necesita una tabla). También puede incluir `database`, usar un nombre de tabla completo como `prometheus.metrics` u omitir la base de datos para usar `default`. Esto permite que un único handler atienda varias tablas `TimeSeries`.

Para usar una tabla fija en todas las solicitudes, configúrela en el handler:

```xml theme={null}
<handler>
    <type>prometheus_api_v1</type>
    <database>prometheus</database>
    <table>metrics</table>
</handler>
```

Una tabla configurada en el handler no puede sobrescribirse mediante parámetros de la solicitud.

Configuración de enrutamiento y del handler:

| Nombre | Predeterminado | Descripción |
| - | - | - |
| `url_prefix` | ninguno | Regla de filtrado que coincide con todas las rutas de solicitud que comienzan con el prefijo configurado. |
| `table` | ninguno | El nombre de una tabla `TimeSeries`. Si se omite, la solicitud debe incluir el parámetro de consulta `table`. El nombre configurado puede incluir una base de datos. |
| `database` | ninguno | La base de datos que contiene la tabla. Una solicitud puede proporcionarla como parámetro de consulta. Si se omite, ClickHouse usa la base de datos de un valor `table` calificado o recurre a `default`. |

<h3 id="create-a-timeseries-table">
  Cree una tabla TimeSeries
</h3>

Cree una base de datos y una tabla `TimeSeries`:

```sql theme={null}
CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;
```

<h2 id="remote-write">
  Ingeste métricas mediante escritura remota
</h2>

ClickHouse admite el [protocolo de escritura remota de Prometheus](https://prometheus.io/docs/specs/remote_write_spec/). Configure Prometheus para que escriba en el handler:

```yaml theme={null}
remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>
```

Prometheus envía muestras a la tabla `prometheus.metrics`.

Para agrupar los datos de muchas solicitudes simultáneas de escritura remota en menos partes, habilite las [inserciones asíncronas](/es/reference/settings/session-settings/async-insert#async_insert) añadiendo la configuración `async_insert` a la URL (o habilitándola en el perfil de usuario):

```yaml theme={null}
remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics&async_insert=1
```

ClickHouse confirma una solicitud de escritura remota asíncrona solo después de que los datos se hayan vaciado en todas las tablas internas de la tabla `TimeSeries`, independientemente de la configuración de [`wait_for_async_insert`](/es/reference/settings/session-settings/wait-for#wait_for_async_insert): el protocolo de escritura remota considera duradera una escritura confirmada. Si el vaciado falla, la solicitud devuelve un error y Prometheus la reintenta.

<h2 id="promql-query-support">
  Consultas con PromQL
</h2>

Utilice el endpoint de consulta instantánea para evaluar una expresión de PromQL en un momento dado:

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"
```

Use el endpoint de consulta de rango para evaluar una expresión en un intervalo de tiempo:

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "start=2026-08-15T12:00:00Z" \
  --data-urlencode "end=2026-08-15T13:00:00Z" \
  --data-urlencode "step=60s" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"
```

Los endpoints de consulta también aceptan los parámetros en el cuerpo de un formulario. Sin `--get`, curl envía los parámetros como `application/x-www-form-urlencoded` mediante `POST`:

```bash theme={null}
curl --user default:<password> \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "start=2026-08-15T12:00:00Z" \
  --data-urlencode "end=2026-08-15T13:00:00Z" \
  --data-urlencode "step=60s" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"
```

Utilice el endpoint de formato de consulta para analizar y formatear una expresión de PromQL sin evaluarla:

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/format_query" \
  --data-urlencode "query=sum by(job)(http_requests_total{code=\"200\"})/2"
```

La expresión se devuelve serializada a partir de la consulta analizada, con los espacios en blanco normalizados, los comentarios eliminados, los paréntesis redundantes suprimidos y las duraciones convertidas a número de segundos: `sum by (job) (http_requests_total{code="200"}) / 2`. Este endpoint no evalúa la expresión, por lo que no necesita los parámetros `database` ni `table`.

Consulte las [funcionalidades de PromQL compatibles](/es/reference/functions/table-functions/prometheusQueryRange#supported-promql-features) para obtener la lista de funciones y operadores de agregación que utilizan la API HTTP, el dialecto `promql` y las funciones de tabla.

<h3 id="grafana">
  Grafana
</h3>

Configure una fuente de datos de Prometheus con una URL base que termine antes de `/api/v1`:

```yaml theme={null}
apiVersion: 1
datasources:
  - name: ClickHouse Prometheus
    type: prometheus
    access: proxy
    url: https://clickhouse.example.com:8443/prometheus
    basicAuth: true
    basicAuthUser: default
    jsonData:
      httpMethod: POST
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>
```

Grafana agrega `/api/v1/query` o `/api/v1/query_range` a esta URL base y añade `customQueryParameters` a cada solicitud.

Con `httpMethod: POST`, Grafana envía los parámetros de consulta en el cuerpo de la solicitud. ClickHouse lee el cuerpo de la solicitud y la cadena de consulta de la URL, por lo que `customQueryParameters` sigue aplicándose. Use `POST` para expresiones PromQL largas, ya que una URL tiene un límite de longitud.

<Note>
  Solo están implementados los endpoints de consulta `/api/v1/query`, `/api/v1/query_range` y `/api/v1/format_query` y los endpoints de metadatos `/api/v1/series`, `/api/v1/labels`, `/api/v1/label/<name>/values` y `/api/v1/metadata`. `/api/v1/series` requiere al menos un selector de series `match[]`, admite los parámetros opcionales `start`, `end` y `limit`, y devuelve la unión de las series coincidentes con cada selector. `/api/v1/labels` acepta los mismos parámetros, con `match[]` como opcional, y devuelve los nombres de etiquetas ordenados de las series coincidentes (o de todas las series cuando no se proporcionan selectores). `/api/v1/label/<name>/values` acepta los mismos parámetros que `/api/v1/labels` y devuelve los valores ordenados de una etiqueta, donde `<name>` puede usar opcionalmente el escapado `U__...` de Prometheus para nombres de etiquetas que contienen caracteres fuera de `[a-zA-Z0-9_]`. Estos endpoints cubren lo que utiliza un origen de datos de Prometheus en Grafana para explorar etiquetas, variables de plantilla y el autocompletado del constructor de consultas.
</Note>

<h3 id="sql-entry-points">
  Puntos de entrada de SQL
</h3>

ClickHouse utiliza el mismo convertidor de PromQL para la API HTTP, el dialecto `promql` y las funciones de tabla [`prometheusQuery`](/es/reference/functions/table-functions/prometheusQuery) y [`prometheusQueryRange`](/es/reference/functions/table-functions/prometheusQueryRange).

Ejecute PromQL directamente con `clickhouse-client`:

```bash theme={null}
clickhouse-client \
  --dialect promql \
  --promql_database prometheus \
  --promql_table metrics \
  --query 'rate(http_requests_total[5m])'
```

Utilice las funciones de tabla para integrar PromQL en una consulta SQL:

```sql theme={null}
SELECT *
FROM prometheusQuery(
    prometheus.metrics,
    'rate(http_requests_total[5m])',
    now()
);
```

<h2 id="metadata">
  Consultar metadatos de métricas
</h2>

El endpoint `/prometheus/api/v1/metadata` devuelve los metadatos de las métricas almacenados en la tabla de destino `Metrics` de la tabla `TimeSeries`: el tipo, el texto de ayuda y la unidad de cada familia de métricas. Admite los siguientes parámetros de Prometheus en la cadena de consulta de la URL:

| Parámetro | Descripción |
| - | - |
| `metric` | Devuelve metadatos solo para esta familia de métricas. |
| `limit` | Limita el número de familias de métricas devueltas. Un valor negativo indica que no hay límite; cero no devuelve ninguna familia de métricas. |
| `limit_per_metric` | Limita el número de objetos de metadatos devueltos para cada familia de métricas. Los valores cero y negativos indican que no hay límite. |

La tabla de destino `Metrics` predeterminada es una `ReplacingMergeTree` ordenada por el nombre de la familia de métricas: conserva la entrada de metadatos escrita más recientemente para cada familia de métricas. Solo se devuelven varias entradas por familia mientras la tabla de destino las almacene: antes de que se fusionen sus partes o cuando la tabla se define con un motor que las conserva.

```bash theme={null}
curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/metadata" \
  --data-urlencode "metric=http_requests_total" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"
```

<h2 id="remote-read">
  Leer métricas mediante lectura remota
</h2>

ClickHouse admite el [protocolo de lectura remota de Prometheus](https://prometheus.io/docs/prometheus/latest/querying/remote_read_api/) en `/prometheus/api/v1/read`.

Configure un servidor Prometheus para que lea de la misma tabla `TimeSeries`:

```yaml theme={null}
remote_read:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>
```