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

> Suporte à API HTTP do Prometheus no ClickHouse: gravação remota, leitura remota e consultas PromQL em uma tabela TimeSeries.

# API HTTP do Prometheus e 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>
            {'Em prévia privada'}
        </div>;
};

<PrivatePreviewBadge />

O ClickHouse implementa a API HTTP do Prometheus em uma tabela [`TimeSeries`](/pt-BR/reference/engines/table-engines/integrations/time-series). Um handler atende a gravação remota, a leitura remota, consultas PromQL instantâneas e consultas PromQL de intervalo.

Para expor as métricas do próprio ClickHouse para que um servidor Prometheus as colete, consulte o [endpoint de métricas do Prometheus](/pt-BR/concepts/features/interfaces/prometheus-metrics).

<h2 id="prerequisites">
  Pré-requisitos
</h2>

As etapas de configuração diferem entre o ClickHouse Cloud e o ClickHouse autogerenciado. Siga a seção correspondente à sua implantação.

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

<Note>
  O suporte a PromQL no ClickHouse Cloud está em private preview. Os serviços que participam do private preview já possuem a configuração `enable_time_series_table` e os endpoints da API do Prometheus configurados. Os demais serviços do ClickHouse Cloud não têm essa configuração, e não é possível habilitar o recurso por conta própria nesses serviços. O comando `SET enable_time_series_table` e a configuração `http_handlers` descritos nas próximas seções aplicam-se a implantações autogerenciadas.
</Note>

Em um serviço que participa do private preview, prossiga para [Criar uma tabela TimeSeries](#create-a-timeseries-table). O serviço disponibiliza os caminhos de endpoint listados na [tabela de endpoints](#configure-prometheus-api).

<h3 id="enable-the-timeseries-setting">
  Autogerenciado: habilite a configuração TimeSeries
</h3>

Habilite a configuração `enable_time_series_table` para o usuário que cria e acessa a tabela:

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

Para solicitações à API HTTP, habilite `enable_time_series_table` no perfil do usuário da API.

<h3 id="configure-prometheus-api">
  Autogerenciado: configure os endpoints da API do Prometheus
</h3>

Configure um handler roteado por prefixo na porta HTTP principal do 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/>` preserva os handlers integrados para endpoints como `/ping` e solicitações SQL. O prefixo acima expõe esses endpoints por meio de um único handler:

| Endpoint | Finalidade |
| - | - |
| `/prometheus/api/v1/write` | gravação remota do Prometheus |
| `/prometheus/api/v1/read` | leitura remota do Prometheus |
| `/prometheus/api/v1/query` | consultas PromQL instantâneas |
| `/prometheus/api/v1/query_range` | consultas PromQL de intervalo |
| `/prometheus/api/v1/format_query` | formatação de expressões PromQL |
| `/prometheus/api/v1/series` | Metadados de séries |
| `/prometheus/api/v1/metadata` | Metadados da família de métricas |

O exemplo omite `database` e `table` do handler. Cada solicitação deve fornecer o parâmetro de consulta `table` (exceto para `/format_query`, que apenas analisa a expressão PromQL fornecida e não precisa de uma tabela). Ela também pode fornecer `database`, usar um nome de tabela qualificado, como `prometheus.metrics`, ou omitir o banco de dados para usar `default`. Isso permite que um único handler atenda a várias tabelas `TimeSeries`.

Para usar uma tabela fixa em todas as solicitações, configure-a no handler:

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

Uma tabela configurada no handler não pode ser substituída por parâmetros da solicitação.

Configurações de roteamento e do handler:

| Nome | Padrão | Descrição |
| - | - | - |
| `url_prefix` | nenhum | Filtro de regras que corresponde a todos os caminhos de solicitação que começam com o prefixo configurado. |
| `table` | nenhum | O nome de uma tabela `TimeSeries`. Quando omitido, a solicitação deve fornecer o parâmetro de consulta `table`. O nome configurado pode incluir um banco de dados. |
| `database` | nenhum | O banco de dados que contém a tabela. Uma solicitação pode fornecê-lo como parâmetro de consulta. Quando omitido, o ClickHouse usa o banco de dados de um valor `table` qualificado ou recorre a `default`. |

<h3 id="create-a-timeseries-table">
  Crie uma tabela TimeSeries
</h3>

Crie um banco de dados e uma tabela `TimeSeries`:

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

<h2 id="remote-write">
  Faça a ingestão de métricas com gravação remota
</h2>

O ClickHouse oferece suporte ao [protocolo gravação remota do Prometheus](https://prometheus.io/docs/specs/remote_write_spec/). Configure o Prometheus para gravar no 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>
```

O Prometheus envia amostras para a tabela `prometheus.metrics`.

Para agrupar dados de várias solicitações simultâneas de gravação remota em menos partes, habilite as [inserções assíncronas](/pt-BR/reference/settings/session-settings/async-insert#async_insert) adicionando a configuração `async_insert` à URL (ou habilitando-a no perfil de usuário):

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

O ClickHouse confirma uma solicitação assíncrona de gravação remota somente depois que os dados são gravados em todas as tabelas internas da tabela `TimeSeries`, independentemente da configuração [`wait_for_async_insert`](/pt-BR/reference/settings/session-settings/wait-for#wait_for_async_insert): o protocolo de gravação remota considera uma gravação confirmada como durável. Se a gravação falhar, a solicitação retorna um erro e o Prometheus tenta novamente.

<h2 id="promql-query-support">
  Consulta com PromQL
</h2>

Use o endpoint de consulta instantânea para avaliar uma expressão PromQL em um momento específico:

```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 o endpoint de consulta por intervalo para avaliar uma expressão em um intervalo de tempo:

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

Os endpoints de consulta também aceitam os parâmetros no corpo de um formulário. Sem `--get`, o curl envia os parâmetros como `application/x-www-form-urlencoded` via `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"
```

Use o endpoint de formatação de consulta para analisar e formatar uma expressão PromQL sem avaliá-la:

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

A expressão é retornada serializada a partir da consulta analisada sintaticamente, com os espaços em branco normalizados, os comentários removidos, os parênteses redundantes descartados e as durações convertidas em números de segundos: `sum by (job) (http_requests_total{code="200"}) / 2`. Esse endpoint não avalia a expressão, portanto não precisa dos parâmetros `database` e `table`.

Consulte os [recursos do PromQL compatíveis](/pt-BR/reference/functions/table-functions/prometheusQueryRange#supported-promql-features) para ver a lista de funções e operadores de agregação usados pela API HTTP, pelo dialeto `promql` e pelas funções de tabela.

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

Configure uma fonte de dados do Prometheus com a URL base terminando 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>
```

O Grafana acrescenta `/api/v1/query` ou `/api/v1/query_range` a esta URL base e adiciona `customQueryParameters` a cada solicitação.

Com `httpMethod: POST`, o Grafana envia os parâmetros da consulta no corpo da requisição. O ClickHouse lê o corpo da requisição e a string de consulta da URL, portanto `customQueryParameters` continua se aplicando. Use `POST` para expressões PromQL longas, porque uma URL tem limite de comprimento.

<Note>
  Apenas os endpoints de consulta `/api/v1/query`, `/api/v1/query_range` e `/api/v1/format_query` e os endpoints de metadados `/api/v1/series`, `/api/v1/labels`, `/api/v1/label/<name>/values` e `/api/v1/metadata` estão implementados. `/api/v1/series` requer pelo menos um seletor de séries `match[]`, oferece suporte aos parâmetros opcionais `start`, `end` e `limit` e retorna a união das séries correspondentes a cada seletor. `/api/v1/labels` aceita os mesmos parâmetros, com `match[]` sendo opcional, e retorna os nomes de rótulos ordenados das séries correspondentes (ou de todas as séries quando nenhum seletor é informado). `/api/v1/label/<name>/values` aceita os mesmos parâmetros que `/api/v1/labels` e retorna os valores ordenados de um rótulo, sendo que `<name>` pode opcionalmente usar o escaping `U__...` do Prometheus para nomes de rótulos que contenham caracteres fora de `[a-zA-Z0-9_]`. Esses endpoints cobrem o que uma fonte de dados Prometheus no Grafana usa para navegar por rótulos, variáveis de Template e preenchimento automático no construtor de consultas.
</Note>

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

O ClickHouse usa o mesmo conversor de PromQL para a API HTTP, o dialeto `promql` e as funções de tabela [`prometheusQuery`](/pt-BR/reference/functions/table-functions/prometheusQuery) e [`prometheusQueryRange`](/pt-BR/reference/functions/table-functions/prometheusQueryRange).

Execute PromQL diretamente com o `clickhouse-client`:

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

Use as funções de tabela para incorporar PromQL a uma consulta SQL:

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

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

O endpoint `/prometheus/api/v1/metadata` retorna os metadados das métricas armazenados na tabela de destino `Metrics` da tabela `TimeSeries`: o tipo, o texto de ajuda e a unidade de cada família de métricas. Ele aceita os seguintes parâmetros do Prometheus na string de consulta da URL:

| Parâmetro | Descrição |
| - | - |
| `metric` | Retorna metadados apenas para esta família de métricas. |
| `limit` | Limita o número de famílias de métricas retornadas. Um valor negativo significa sem limite; zero não retorna nenhuma família de métricas. |
| `limit_per_metric` | Limita o número de objetos de metadados retornados para cada família de métricas. Valores zero e negativos significam sem limite. |

A tabela de destino `Metrics` padrão é uma `ReplacingMergeTree` ordenada pelo nome da família de métricas: ela mantém a entrada de metadados gravada mais recentemente para cada família de métricas. Várias entradas por família são retornadas apenas enquanto a tabela de destino as armazena — antes da mesclagem de suas partes ou quando a tabela é definida com um mecanismo que as preserva.

```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">
  Leia métricas com leitura remota
</h2>

O ClickHouse oferece suporte ao [protocolo de leitura remota do Prometheus](https://prometheus.io/docs/prometheus/latest/querying/remote_read_api/) em `/prometheus/api/v1/read`.

Configure um servidor Prometheus para ler da mesma tabela `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>
```