> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Uso do construtor de consultas no plugin do ClickHouse para Grafana
# Construtor de consultas
export const ClickHouseSupportedBadge = () => {
return
Suportado pelo ClickHouse
;
};
export const Image = ({img, alt, size}) => {
return
;
};
É possível executar qualquer consulta com o plugin do ClickHouse.
O construtor de consultas é uma opção prática para consultas mais simples, mas, para consultas mais complexas, você precisará usar o [SQL Editor](#sql-editor).
Todas as consultas no construtor de consultas têm um [tipo de consulta](#query-types) e exigem que pelo menos uma coluna seja selecionada.
Os tipos de consulta disponíveis são:
* [Table](#table): o tipo de consulta mais simples para exibir dados em formato de tabela. Funciona bem como uma opção genérica tanto para consultas simples quanto para consultas complexas que contêm funções de agregação.
* [Logs](#logs): otimizado para criar consultas de logs. Funciona melhor na visualização Explore com as [configurações padrão definidas](/pt-BR/integrations/connectors/data-visualization/grafana/config#logs).
* [Time Series](#time-series): mais indicado para criar consultas de séries temporais. Permite selecionar uma coluna de tempo específica e adicionar funções de agregação.
* [Traces](#traces): otimizado para pesquisar/visualizar rastreamentos. Funciona melhor na visualização Explore com as [configurações padrão definidas](/pt-BR/integrations/connectors/data-visualization/grafana/config#traces).
* [SQL Editor](#sql-editor): o SQL Editor pode ser usado quando você quiser controle total sobre a consulta. Nesse modo, qualquer consulta SQL pode ser executada.
## Tipos de consulta
A configuração *Tipo de consulta* altera o layout do construtor de consultas para corresponder ao tipo de consulta que está sendo criada.
O tipo de consulta também determina qual painel é usado para visualizar os dados.
### Tabela
O tipo de consulta mais flexível é a consulta de tabela. Ela funciona como uma categoria genérica para os outros construtores de consulta, projetada para lidar com consultas simples e de agregação.
| Campo | Descrição |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Modo do construtor | Consultas simples não incluem Aggregates nem Group By, enquanto consultas de agregação incluem essas opções. |
| Colunas | As colunas selecionadas. É possível digitar SQL puro neste campo para usar funções e aliases de coluna. |
| Agregações | Uma lista de [funções de agregação](/pt-BR/reference/functions/aggregate-functions/index). Permite valores personalizados para função e coluna. Visível apenas no modo Aggregate. |
| Agrupar por | Uma lista de expressões [GROUP BY](/pt-BR/reference/statements/select/group-by). Visível apenas no modo Aggregate. |
| ORDER BY | Uma lista de expressões [ORDER BY](/pt-BR/reference/statements/select/order-by). |
| Limite | Adiciona uma instrução [LIMIT](/pt-BR/reference/statements/select/limit) ao final da consulta. Se definido como `0`, será omitido. Algumas visualizações podem exigir que isso seja definido como `0` para exibir todos os dados. |
| Filtros | Uma lista de filtros a serem aplicados na cláusula `WHERE`. |
Esse tipo de consulta exibirá os dados como uma tabela.
### Logs
O tipo de consulta de logs oferece um construtor de consultas voltado para consultar dados de logs.
Os padrões podem ser configurados na [configuração de logs](/pt-BR/integrations/connectors/data-visualization/grafana/config#logs) da fonte de dados, permitindo que o construtor de consultas seja pré-carregado com um database/table e colunas padrão.
OpenTelemetry também pode ser habilitado para selecionar automaticamente as colunas de acordo com uma versão do esquema.
Os filtros **Time** e **Level** são adicionados por padrão, juntamente com um Order By para a coluna Time.
Esses filtros estão vinculados aos respectivos campos e serão atualizados conforme as colunas forem alteradas.
O filtro **Level** é excluído do SQL por padrão; ao alterá-lo da opção `IS ANYTHING`, ele será habilitado.
O tipo de consulta de logs oferece suporte a [links de dados](#data-links).
| Campo | Descrição |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Usar OTel | Habilita colunas do OpenTelemetry. Substitui as colunas selecionadas para usar as colunas definidas pela versão do esquema OTel selecionada (desabilita a seleção de colunas). |
| Colunas | Colunas extras a serem adicionadas às linhas de log. É possível digitar SQL bruto neste campo para permitir funções e aliases de colunas. |
| Time | A coluna de timestamp principal do log. Exibe tipos semelhantes a tempo, mas permite valores/funções personalizados. |
| Nível do log | Opcional. O *level* ou *severity* do log. Os valores normalmente são como `INFO`, `error`, `Debug` etc. |
| Mensagem | O conteúdo da mensagem de log. |
| Order By | Uma lista de expressões [ORDER BY](/pt-BR/reference/statements/select/order-by). |
| Limite | Anexa uma instrução [LIMIT](/pt-BR/reference/statements/select/limit) ao final da consulta. Se definido como `0`, ele será excluído, mas isso não é recomendado para grandes datasets de logs. |
| Filtros | Uma lista de filtros a serem aplicados na cláusula `WHERE`. |
| Filtro de mensagem | Um campo de texto para filtrar logs de forma prática usando `LIKE %value%`. Excluído quando a entrada estiver vazia. |
Esse tipo de consulta renderiza os dados no painel de logs, juntamente com um painel de histograma de logs na parte superior.
As colunas extras selecionadas na consulta podem ser visualizadas na linha de log expandida:
### Séries temporais
O tipo de consulta de séries temporais é semelhante a [table](#table), mas com foco em dados de séries temporais.
As duas visualizações são, em grande parte, iguais, com estas diferenças importantes:
* Um campo *Time* dedicado.
* No modo Aggregate, uma macro de intervalo de tempo é aplicada automaticamente junto com um Agrupar por para o campo Time.
* No modo Aggregate, o campo "coluna" fica oculto.
* Um filtro de intervalo de tempo e um ORDER BY são adicionados automaticamente para o campo **Time**.
**A visualização está sem dados?**
Em alguns casos, o painel de séries temporais pode parecer cortado porque o limite padrão é `1000`.
Tente remover a cláusula `LIMIT` definindo-a como `0` (se o seu conjunto de dados permitir).
| Campo | Descrição |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| modo do construtor | Consultas simples não incluem agregações nem Agrupar por, enquanto consultas agregadas incluem essas opções. |
| Time | A coluna de tempo principal da consulta. Exibe tipos de dados temporais, mas permite valores/funções personalizados. |
| coluna | As colunas selecionadas. É possível digitar SQL bruto neste campo para permitir funções e aliases de coluna. Visível apenas no modo Simple. |
| agregação | Uma lista de [funções de agregação](/pt-BR/reference/functions/aggregate-functions/index). Permite valores personalizados para função e coluna. Visível apenas no modo Aggregate. |
| Agrupar por | Uma lista de expressões [GROUP BY](/pt-BR/reference/statements/select/group-by). Visível apenas no modo Aggregate. |
| ORDER BY | Uma lista de expressões [ORDER BY](/pt-BR/reference/statements/select/order-by). |
| Limite | Adiciona uma instrução [LIMIT](/pt-BR/reference/statements/select/limit) ao final da consulta. Se for definido como `0`, ele será omitido; isso é recomendado para alguns conjuntos de dados de séries temporais a fim de exibir a visualização completa. |
| Filters | Uma lista de filtros a serem aplicados na cláusula `WHERE`. |
Esse tipo de consulta exibirá os dados no painel de séries temporais.
### Rastreamentos
O tipo de consulta de rastreamento oferece um construtor de consultas para pesquisar e visualizar rastreamentos com facilidade.
Ele foi projetado para dados do OpenTelemetry, mas é possível selecionar colunas para renderizar rastreamentos de um esquema diferente.
Os padrões podem ser configurados na [configuração de rastreamento](/pt-BR/integrations/connectors/data-visualization/grafana/config#traces) da fonte de dados para permitir que o construtor de consultas seja pré-carregado com um banco de dados/tabela e colunas padrão. Se houver padrões configurados, a seleção de colunas ficará recolhida por padrão.
O OpenTelemetry também pode ser ativado para selecionar automaticamente as colunas de acordo com uma versão do esquema.
Filtros padrão são adicionados com o objetivo de mostrar apenas spans de nível superior.
Também é incluído um ORDER BY para as colunas Time e Duration Time.
Esses filtros estão vinculados aos respectivos campos e serão atualizados conforme as colunas forem alteradas.
O filtro **Service Name** é excluído do SQL por padrão; ao alterá-lo da opção `IS ANYTHING`, ele será ativado.
O tipo de consulta de rastreamento oferece suporte a [links de dados](#data-links).
| Field | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Trace Mode | Altera a consulta de Trace Search para Trace ID lookup. |
| Use OTel | Ativa colunas do OpenTelemetry. Substitui as colunas selecionadas para usar as colunas definidas pela versão de esquema OTel selecionada (desativa a seleção de colunas). |
| Trace ID Column | O ID do rastreamento. |
| Span ID Column | ID do span. |
| Parent Span ID Column | ID do span pai. Geralmente fica vazio em rastreamentos de nível superior. |
| Service Name Column | Nome do serviço. |
| Operation Name Column | Nome da operação. |
| Start Time Column | A coluna de tempo principal do trace span. O momento em que o span foi iniciado. |
| Duration Time Column | A duração do span. Por padrão, o Grafana espera que seja um float em milissegundos. Uma conversão é aplicada automaticamente por meio do menu suspenso `Duration Unit`. |
| Duration Unit | A unidade de tempo usada para a duração. O padrão é nanossegundos. A unidade selecionada será convertida em um float em milissegundos, conforme exigido pelo Grafana. |
| Tags Column | Tags do span. Exclua esta coluna se não estiver usando um esquema baseado em OTel, pois é esperado um tipo específico de coluna map. |
| Service Tags Column | Tags do serviço. Exclua esta coluna se não estiver usando um esquema baseado em OTel, pois é esperado um tipo específico de coluna map. |
| Order By | Uma lista de expressões [ORDER BY](/pt-BR/reference/statements/select/order-by). |
| Limit | Acrescenta uma instrução [LIMIT](/pt-BR/reference/statements/select/limit) ao final da consulta. Se definido como `0`, ele será excluído, mas isso não é recomendado para grandes datasets de rastreamento. |
| Filters | Uma lista de filtros a serem aplicados na cláusula `WHERE`. |
| Trace ID | O Trace ID pelo qual filtrar. Usado apenas no modo Trace ID e ao abrir um [link de dados](#data-links) de Trace ID. |
Esse tipo de consulta renderiza os dados na visualização de tabela no modo Trace Search e no painel de rastreamento no modo Trace ID.
## SQL Editor
Para consultas complexas demais para o construtor de consultas, você pode usar o SQL Editor.
Isso dá a você controle total sobre a consulta, permitindo escrever e executar ClickHouse SQL puro.
O SQL Editor pode ser aberto selecionando "SQL Editor" na parte superior do editor de consultas.
[Funções de macro](#macros) ainda podem ser usadas nesse modo.
Você pode alternar entre tipos de consulta para obter a visualização que melhor se adapta à sua consulta.
Essa alternância também tem efeito na visualização de dashboard, especialmente com dados de séries temporais.
## Links de dados
Os [links de dados](https://grafana.com/docs/grafana/latest/panels-visualizations/configure-data-links) do Grafana
podem ser usados para direcionar para novas consultas.
Esse recurso foi habilitado no plugin do ClickHouse para vincular um trace a logs e vice-versa. Ele funciona melhor com o OpenTelemetry configurado tanto para logs quanto para rastreamento na [configuração da fonte de dados](/pt-BR/integrations/connectors/data-visualization/grafana/config#opentelemetry)
Exemplo de links de trace em uma tabela
Exemplo de links de trace em logs
### Como criar um link de dados
Você pode criar um link de dados selecionando uma coluna chamada `traceID` na sua consulta. Esse nome não diferencia maiúsculas de minúsculas e permite adicionar um sublinhado antes de "ID". Por exemplo: `traceId`, `TraceId`, `TRACE_ID` e `tracE_iD` seriam todos válidos.
Se o OpenTelemetry estiver habilitado em uma consulta de [logs](#logs) ou [traces](#traces), uma coluna de trace ID será incluída automaticamente.
Ao incluir uma coluna de trace ID, os links "**View Trace**" e "**View Logs**" serão associados aos dados.
### Recursos de vinculação
Com os links de dados disponíveis, você pode abrir rastreamento e logs usando o trace ID fornecido.
"**View Trace**" abrirá um painel dividido com o trace, e "**View Logs**" abrirá uma consulta de logs filtrada pelo trace ID.
Se o link for clicado em um dashboard em vez da visualização Explore, ele será aberto em uma nova aba na visualização Explore.
É necessário ter padrões configurados tanto para [logs](/pt-BR/integrations/connectors/data-visualization/grafana/config#logs) quanto para [rastreamento](/pt-BR/integrations/connectors/data-visualization/grafana/config#traces) ao alternar entre tipos de consulta (de logs para rastreamento e de rastreamento para logs). Os padrões não são necessários ao abrir um link do mesmo tipo de consulta, já que a consulta pode ser simplesmente copiada.
Exemplo de visualização de um trace (painel direito) a partir de uma consulta de logs (painel esquerdo)
## Macros
Macros são uma forma simples de adicionar SQL dinâmico à sua consulta.
Antes de uma consulta ser enviada ao servidor ClickHouse, o plugin expandirá a macro e a substituirá pela expressão completa.
Consultas tanto do SQL Editor quanto do Query Builder podem usar macros.
### Usando macros
As macros podem ser incluídas em qualquer parte da consulta, várias vezes, se necessário.
Veja um exemplo de uso da macro `$__timeFilter`:
Entrada:
```sql theme={null}
SELECT log_time, log_message
FROM logs
WHERE $__timeFilter(log_time)
```
Saída final da consulta:
```sql theme={null}
SELECT log_time, log_message
FROM logs
WHERE log_time >= toDateTime(1415792726) AND log_time <= toDateTime(1447328726)
```
Neste exemplo, o intervalo de tempo do dashboard do Grafana é aplicado à coluna `log_time`.
O plugin também aceita a notação com chaves `{}`. Use essa notação quando for necessário usar consultas dentro de [parâmetros](/pt-BR/reference/syntax#defining-and-using-query-parameters).
### Lista de macros
Esta é uma lista de todas as macros disponíveis no plugin:
| Macro | Descrição | Exemplo de saída |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `$__dateFilter(columnName)` | Substituído por um filtro de intervalo de tempo na coluna informada usando o intervalo de tempo do painel do Grafana como [Date](/pt-BR/reference/data-types/date). | `columnName >= toDate('2022-10-21') AND columnName <= toDate('2022-10-23')` |
| `$__timeFilter(columnName)` | Substituído por um filtro de intervalo de tempo na coluna informada usando o intervalo de tempo do painel do Grafana como [DateTime](/pt-BR/reference/data-types/datetime). | `columnName >= toDateTime(1415792726) AND time <= toDateTime(1447328726)` |
| `$__timeFilter_ms(columnName)` | Substituído por um filtro de intervalo de tempo na coluna informada usando o intervalo de tempo do painel do Grafana como [DateTime64](/pt-BR/reference/data-types/datetime64). | `columnName >= fromUnixTimestamp64Milli(1415792726123) AND columnName <= fromUnixTimestamp64Milli(1447328726456)` |
| `$__dateTimeFilter(dateColumn, timeColumn)` | Abreviação que combina `$__dateFilter()` e `$__timeFilter()` usando colunas separadas de Date e DateTime. Alias `$__dt()` | `$__dateFilter(dateColumn) AND $__timeFilter(timeColumn)` |
| `$__fromTime` | Substituído pelo horário inicial do intervalo do painel do Grafana convertido para [DateTime](/pt-BR/reference/data-types/datetime). | `toDateTime(1415792726)` |
| `$__fromTime_ms` | Substituído pelo horário inicial do intervalo do painel convertido para [DateTime64](/pt-BR/reference/data-types/datetime64). | `fromUnixTimestamp64Milli(1415792726123)` |
| `$__toTime` | Substituído pelo horário final do intervalo do painel do Grafana convertido para [DateTime](/pt-BR/reference/data-types/datetime). | `toDateTime(1447328726)` |
| `$__toTime_ms` | Substituído pelo horário final do intervalo do painel convertido para [DateTime64](/pt-BR/reference/data-types/datetime64). | `fromUnixTimestamp64Milli(1447328726456)` |
| `$__timeInterval(columnName)` | Substituído por uma função que calcula o intervalo com base no tamanho da janela em segundos. | `toStartOfInterval(toDateTime(columnName), INTERVAL 20 second)` |
| `$__timeInterval_ms(columnName)` | Substituído por uma função que calcula o intervalo com base no tamanho da janela em milissegundos. | `toStartOfInterval(toDateTime64(columnName, 3), INTERVAL 20 millisecond)` |
| `$__interval_s` | Substituído pelo intervalo do dashboard em segundos. | `20` |
| `$__conditionalAll(condition, $templateVar)` | Substituído pelo primeiro parâmetro quando a variável de template no segundo parâmetro não seleciona todos os valores. Substituído por `1=1` quando a variável de template seleciona todos os valores. | `condition` ou `1=1` |