Referência do InfluxQL - Time Series Database: Central de Documentação do Alibaba Cloud

O InfluxQL (Influx Query Language) é uma linguagem de consulta semelhante ao SQL para o TSDB for InfluxDB. Esta referência abrange a especificação completa da sintaxe, incluindo notação, literais, instruções, cláusulas, expressões e detalhes internos do mecanismo de consulta.

Nesta página

Notação
Elementos de consulta
Literais
Consultas
Instruções
Cláusulas
Expressões
Outros elementos gramaticais
Comentários
Detalhes internos do mecanismo de consulta

Notação

A sintaxe do InfluxQL usa a Forma Backus-Naur Estendida (EBNF), a mesma notação da especificação da linguagem de programação Go.

Production  = production_name "=" [ Expression ] "." .
Expression  = Alternative { "|" Alternative } .
Alternative = Term { Term } .
Term        = production_name | token [ "…" token ] | Group | Option | Repetition .
Group       = "(" Expression ")" .
Option      = "[" Expression "]" .
Repetition  = "{" Expression "}" .

Operadores de notação em ordem crescente de precedência:

|   alternation
()  grouping
[]  option (0 or 1 times)
{}  repetition (0 to n times)

Elementos de consulta

Caracteres

O InfluxQL aceita texto Unicode codificado em UTF-8.

newline      = /* the Unicode code point U+000A */ .
unicode_char = /* an arbitrary Unicode code point except newline */ .

Letras e dígitos

As letras do InfluxQL incluem caracteres ASCII e sublinhados. O caractere sublinhado (U+005F) comporta-se como uma letra. O InfluxQL aceita apenas dígitos decimais.

letter       = ascii_letter | "_" .
ascii_letter = "A" … "Z" | "a" … "z" .
digit        = "0" … "9" .

Identificadores

Identificadores nomeiam bancos de dados, políticas de retenção, usuários, medições, chaves de tag e chaves de campo.

Identificadores entre aspas duplas podem:

Conter caracteres Unicode (exceto quebras de linha)
Usar \" para escapar aspas duplas
Conter palavras-chave do InfluxQL

Identificadores sem aspas devem:

Começar com uma letra ASCII ou sublinhado
Conter apenas letras ASCII, dígitos e sublinhados

identifier          = unquoted_identifier | quoted_identifier .
unquoted_identifier = ( letter ) { letter | digit } .
quoted_identifier   = `"` unicode_char { unicode_char } `"` .

Exemplos:

cpu
_cpu_stats
"1h"
"anything really"
"1_Crazy-1337.identifier>NAME"

Palavras-chave

ALL           ALTER         ANY           AS            ASC           BEGIN
BY            CREATE        CONTINUOUS    DATABASE      DATABASES     DEFAULT
DELETE        DESC          DESTINATIONS  DIAGNOSTICS   DISTINCT      DROP
DURATION      END           EVERY         EXPLAIN       FIELD         FOR
FROM          GRANT         GRANTS        GROUP         GROUPS        IN
INF           INSERT        INTO          KEY           KEYS          KILL
LIMIT         SHOW          MEASUREMENT   MEASUREMENTS  NAME          OFFSET
ON            ORDER         PASSWORD      POLICY        POLICIES      PRIVILEGES
QUERIES       QUERY         READ          REPLICATION   RESAMPLE      RETENTION
REVOKE        SELECT        SERIES        SET           SHARD         SHARDS
SLIMIT        SOFFSET       STATS         SUBSCRIPTION  SUBSCRIPTIONS TAG
TO            USER          USERS         VALUES        WHERE         WITH
WRITE

Use palavras-chave como identificadores em instruções de consulta apenas entre aspas duplas.

Exceção: time

Use a palavra-chave time como identificador sem aspas duplas nos seguintes nomes: consulta contínua, banco de dados, medição, política de retenção, assinatura e usuário. No entanto, não use time como chave de campo ou chave de tag. Tentar gravar dados com time como chave de campo ou tag resulta em erro.

Literais

Inteiros

O InfluxQL aceita apenas inteiros decimais. Não há suporte para inteiros hexadecimais e octais.

int_lit = ( "1" … "9" ) { digit } .

Ponto flutuante

O InfluxQL aceita números de ponto flutuante, mas não expoentes.

float_lit = int_lit "." int_lit .

Strings

Delimite strings com aspas simples. Use \' para escapar aspas simples dentro de uma string.

string_lit = `'` { unicode_char } `'` .

Durações

Um literal de duração consiste em um inteiro seguido imediatamente por uma unidade de tempo, sem espaços entre eles. Combine várias unidades para expressar uma duração.

duration_lit  = int_lit duration_unit .
duration_unit = "ns" | "u" | "µ" | "ms" | "s" | "m" | "h" | "d" | "w" .

Unidades válidas

Unidade	Descrição
`ns`	Nanossegundo (um bilionésimo de segundo)
`u` ou `µ`	Microssegundo (um milionésimo de segundo)
`ms`	Milissegundo (um milésimo de segundo)
`s`	Segundo
`m`	Minuto
`h`	Hora
`d`	Dia
`w`	Semana

Data e hora

A formatação de data e hora no InfluxQL segue as regras do Go, e não a EBNF. O timestamp de referência — 2 de janeiro de 2006, 15:04:05 — define o formato obrigatório:

time_lit = "2006-01-02 15:04:05.999999" | "2006-01-02" .

Valores booleanos

bool_lit = TRUE | FALSE .

Expressões regulares

regex_lit = "/" { unicode_char } "/" .

Operadores: =~ corresponde, !~ não corresponde.

Use expressões regulares para:

Chaves de campo e chaves de tag em cláusulas SELECT
Medições em cláusulas FROM
Valores de tag em cláusulas WHERE
Chaves de tag em cláusulas GROUP BY

Não use expressões regulares para:

Valores de campo não string em cláusulas WHERE
Bancos de dados
Políticas de retenção

Consultas

Uma consulta consiste em uma ou mais instruções separadas por ponto e vírgula (;).

query     = statement { ";" statement } .

statement = alter_retention_policy_stmt |
            create_continuous_query_stmt |
            create_database_stmt |
            create_retention_policy_stmt |
            create_subscription_stmt |
            create_user_stmt |
            delete_stmt |
            drop_continuous_query_stmt |
            drop_database_stmt |
            drop_measurement_stmt |
            drop_retention_policy_stmt |
            drop_series_stmt |
            drop_shard_stmt |
            drop_subscription_stmt |
            drop_user_stmt |
            explain_stmt |
            explain_analyze_stmt |
            grant_stmt |
            kill_query_statement |
            revoke_stmt |
            select_stmt |
            show_continuous_queries_stmt |
            show_databases_stmt |
            show_diagnostics_stmt |
            show_field_key_cardinality_stmt |
            show_field_keys_stmt |
            show_grants_stmt |
            show_measurement_cardinality_stmt |
            show_measurement_exact_cardinality_stmt |
            show_measurements_stmt |
            show_queries_stmt |
            show_retention_policies_stmt |
            show_series_cardinality_stmt |
            show_series_exact_cardinality_stmt |
            show_series_stmt |
            show_shard_groups_stmt |
            show_shards_stmt |
            show_stats_stmt |
            show_subscriptions_stmt |
            show_tag_key_cardinality_stmt |
            show_tag_key_exact_cardinality_stmt |
            show_tag_keys_stmt |
            show_tag_values_stmt |
            show_tag_values_cardinality_stmt |
            show_users_stmt .

Instruções

DELETE

Importante

O TSDB for InfluxDB® aceita operações de exclusão. Devido à sintaxe subjacente de exclusão no InfluxDB®, essas operações podem causar deadlocks e resultar em falhas de leitura/gravação. Evite executar operações de exclusão no TSDB for InfluxDB®.

delete_stmt = "DELETE" ( from_clause | where_clause | from_clause where_clause ) .

Exemplos:

DELETE FROM "cpu"
DELETE FROM "cpu" WHERE time < '2000-01-01T00:00:00Z'
DELETE WHERE time < '2000-01-01T00:00:00Z'

EXPLAIN

O comando EXPLAIN analisa e planeja uma consulta, retornando um resumo estimado do custo de recursos.

Diferente de mecanismos SQL que aceitam junções, o InfluxQL não oferece suporte a joins. A saída do plano reflete custos específicos das consultas InfluxQL: o número de séries temporais acessadas, o número de iteradores lendo arquivos Time-Structured Merge Tree (TSM) e o número de blocos TSM verificados.

Um resultado de EXPLAIN inclui:

Expressão
Campos auxiliares
Número de shards
Número de séries
Valores em cache
Número de arquivos
Número de blocos
Tamanho dos blocos

Exemplo:

> EXPLAIN SELECT sum(pointReq) FROM "_internal"."monitor"."write" GROUP BY hostname;
QUERY PLAN
----------
EXPRESSION: sum(pointReq::integer)
NUMBER OF SHARDS: 2
NUMBER OF SERIES: 2
CACHED VALUES: 110
NUMBER OF FILES: 1
NUMBER OF BLOCKS: 1
SIZE OF BLOCKS: 931

EXPLAIN ANALYZE

O comando EXPLAIN ANALYZE executa uma consulta InfluxQL e retorna os custos reais de recursos medidos durante a execução.

explain_analyze_stmt = "EXPLAIN ANALYZE" select_stmt .

Exemplo:

> EXPLAIN ANALYZE SELECT sum(pointReq) FROM "_internal"."monitor"."write" GROUP BY hostname;
EXPLAIN ANALYZE
---------------
.
└── select
    ├── execution_time: 242.167µs
    ├── planning_time: 2.165637ms
    ├── total_time: 2.407804ms
    └── field_iterators
        ├── labels
        │   └── statement: SELECT sum(pointReq::integer) FROM "_internal"."monitor"."write" GROUP BY hostname
        └── expression
            ├── labels
            │   └── expr: sum(pointReq::integer)
            ├── create_iterator
            │   ├── labels
            │   │   ├── measurement: write
            │   │   └── shard_id: 57
            │   ├── cursors_ref: 1
            │   ├── cursors_aux: 0
            │   ├── cursors_cond: 0
            │   ├── float_blocks_decoded: 0
            │   ├── float_blocks_size_bytes: 0
            │   ├── integer_blocks_decoded: 1
            │   ├── integer_blocks_size_bytes: 931
            │   ├── unsigned_blocks_decoded: 0
            │   ├── unsigned_blocks_size_bytes: 0
            │   ├── string_blocks_decoded: 0
            │   ├── string_blocks_size_bytes: 0
            │   ├── boolean_blocks_decoded: 0
            │   ├── boolean_blocks_size_bytes: 0
            │   └── planning_time: 1.401099ms
            └── create_iterator
                ├── labels
                │   ├── measurement: write
                │   └── shard_id: 58
                ├── cursors_ref: 1
                ├── cursors_aux: 0
                ├── cursors_cond: 0
                ├── float_blocks_decoded: 0
                ├── float_blocks_size_bytes: 0
                ├── integer_blocks_decoded: 0
                ├── integer_blocks_size_bytes: 0
                ├── unsigned_blocks_decoded: 0
                ├── unsigned_blocks_size_bytes: 0
                ├── string_blocks_decoded: 0
                ├── string_blocks_size_bytes: 0
                ├── boolean_blocks_decoded: 0
                ├── boolean_blocks_size_bytes: 0
                └── planning_time: 76.192µs

KILL QUERY

O comando KILL QUERY interrompe uma consulta em execução pelo seu ID de consulta.

kill_query_statement = "KILL QUERY" query_id .

Para encontrar o ID da consulta, execute SHOW QUERIES. O campo qid no resultado é o ID da consulta.

Exemplo:

-- Kill the query with qid 36
KILL QUERY 36

SELECT

select_stmt = "SELECT" fields from_clause [ into_clause ] [ where_clause ]
              [ group_by_clause ] [ order_by_clause ] [ limit_clause ]
              [ offset_clause ] [ slimit_clause ] [ soffset_clause ] [ timezone_clause ] .

Exemplos:

Consulte dados de todas as medições com prefixo cpu e grave os resultados nos mesmos nomes de medição na política de retenção cpu_1h:

SELECT mean("value") INTO "cpu_1h".:MEASUREMENT FROM /cpu.*/

Consulte dados da medição cpu, agrupados por dia no fuso horário America/Chicago:

SELECT mean("value") FROM "cpu" GROUP BY region, time(1d) fill(0) tz('America/Chicago')

SHOW CARDINALITY

O comando SHOW CARDINALITY representa uma família de comandos para consultar a cardinalidade de medições, séries, chaves de tag, valores de tag e chaves de campo.

Dois modos estão disponíveis:

Cardinalidade estimada: calculada a partir de um plano interno. Baixa sobrecarga, independentemente do tamanho dos dados. Use este modo por padrão.
Cardinalidade exata: calculada a partir de dados TSM. Alta sobrecarga para grandes conjuntos de dados. Utilize apenas quando seu caso de uso exigir precisão absoluta.

A filtragem baseada em tempo está disponível somente se o recurso Time Series Index (TSI) estiver ativado para o seu banco de dados.

Para a sintaxe de cada instrução individual, consulte:

SHOW FIELD KEY CARDINALITY
SHOW MEASUREMENT CARDINALITY
SHOW SERIES CARDINALITY
SHOW TAG KEY CARDINALITY
SHOW TAG VALUES CARDINALITY

SHOW CONTINUOUS QUERIES

show_continuous_queries_stmt = "SHOW CONTINUOUS QUERIES" .

Exemplo:

-- List all continuous queries
SHOW CONTINUOUS QUERIES

SHOW DATABASES

show_databases_stmt = "SHOW DATABASES" .

Exemplo:

-- List all databases
SHOW DATABASES

SHOW DIAGNOSTICS

Retorna informações do nó, incluindo dados de compilação, detalhes de runtime, nome do host, configuração do servidor, uso de memória e diagnósticos do runtime Go.

show_diagnostics_stmt = "SHOW DIAGNOSTICS" .

SHOW FIELD KEY CARDINALITY

Retorna a cardinalidade estimada ou exata do conjunto de chaves de campo. Sem uma cláusula ON, o sistema usa o banco de dados atual.

O uso de cláusulas opcionais retorna a cardinalidade exata. A filtragem por tempo requer TSI; não use o filtro time em cláusulas WHERE.

show_field_key_cardinality_stmt =
    "SHOW FIELD KEY CARDINALITY"
    [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

show_field_key_exact_cardinality_stmt =
    "SHOW FIELD KEY EXACT CARDINALITY"
    [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

Exemplos:

-- Estimated cardinality for the current database
SHOW FIELD KEY CARDINALITY

-- Exact cardinality for a specified database
SHOW FIELD KEY EXACT CARDINALITY ON mydb

SHOW FIELD KEYS

show_field_keys_stmt = "SHOW FIELD KEYS" [ on_clause ] [ from_clause ] .

Exemplos:

-- Show field keys and value types from all measurements
SHOW FIELD KEYS

-- Show field keys and value types from a specific measurement
SHOW FIELD KEYS FROM "cpu"

SHOW GRANTS

show_grants_stmt = "SHOW GRANTS FOR" user_name .

Exemplo:

-- Show grants for jdoe
SHOW GRANTS FOR "jdoe"

SHOW MEASUREMENT CARDINALITY

Retorna a cardinalidade estimada ou exata do conjunto de medições. Sem uma cláusula ON, o sistema usa o banco de dados atual.

O uso de cláusulas opcionais retorna a cardinalidade exata. A filtragem por tempo requer TSI; não use o filtro time em cláusulas WHERE.

show_measurement_cardinality_stmt =
    "SHOW MEASUREMENT CARDINALITY"
    [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

show_measurement_exact_cardinality_stmt =
    "SHOW MEASUREMENT EXACT CARDINALITY"
    [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

Exemplos:

-- Estimated cardinality for the current database
SHOW MEASUREMENT CARDINALITY

-- Exact cardinality for a specified database
SHOW MEASUREMENT EXACT CARDINALITY ON mydb

SHOW MEASUREMENTS

show_measurements_stmt = "SHOW MEASUREMENTS" [ on_clause ] [ with_measurement_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] .

Exemplos:

-- List all measurements
SHOW MEASUREMENTS

-- Measurements where region = 'uswest' and host = 'serverA'
SHOW MEASUREMENTS WHERE "region" = 'uswest' AND "host" = 'serverA'

-- Measurements starting with 'h2o'
SHOW MEASUREMENTS WITH MEASUREMENT =~ /h2o.*/

SHOW QUERIES

show_queries_stmt = "SHOW QUERIES" .

Exemplo:

-- List all currently running queries
SHOW QUERIES

SHOW RETENTION POLICIES

show_retention_policies_stmt = "SHOW RETENTION POLICIES" [ on_clause ] .

Exemplo:

-- List all retention policies for a database
SHOW RETENTION POLICIES ON "mydb"

SHOW SERIES

show_series_stmt = "SHOW SERIES" [ on_clause ] [ from_clause ] [ where_clause ] [ limit_clause ] [ offset_clause ] .

Exemplo:

SHOW SERIES FROM "telegraf"."autogen"."cpu" WHERE cpu = 'cpu8'

SHOW SERIES CARDINALITY

Retorna a cardinalidade estimada ou exata do conjunto de séries. Sem uma cláusula ON, o sistema usa o banco de dados atual.

A cardinalidade de séries afeta diretamente o uso de RAM.

O uso de cláusulas opcionais retorna a cardinalidade exata. A filtragem por tempo requer TSI; não use o filtro time em cláusulas WHERE.

show_series_cardinality_stmt =
    "SHOW SERIES CARDINALITY"
    [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

show_series_exact_cardinality_stmt =
    "SHOW SERIES EXACT CARDINALITY"
    [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

Exemplos:

-- Estimated cardinality for the current database
SHOW SERIES CARDINALITY

-- Estimated cardinality for a specified database
SHOW SERIES CARDINALITY ON mydb

-- Exact cardinality for the current database
SHOW SERIES EXACT CARDINALITY

-- Exact cardinality for a specified database
SHOW SERIES EXACT CARDINALITY ON mydb

SHOW SHARD GROUPS

show_shard_groups_stmt = "SHOW SHARD GROUPS" .

Exemplo:

SHOW SHARD GROUPS

SHOW SHARDS

show_shards_stmt = "SHOW SHARDS" .

Exemplo:

SHOW SHARDS

SHOW STATS

Retorna informações estatísticas sobre um nó do TSDB for InfluxDB e seus componentes disponíveis.

show_stats_stmt = "SHOW STATS [ FOR '<component>' | 'indexes' ]"

SHOW STATS

Retorna estatísticas para todos os componentes, exceto o uso de memória de índice. Os valores estatísticos residem na memória e retornam a zero na reinicialização do nó. O TSDB for InfluxDB executa automaticamente SHOW STATS a cada 10 segundos para popular o banco de dados _internal.

SHOW STATS FOR \<component\>

Retorna estatísticas para um componente específico. Para o componente runtime, retorna um resumo de uso de memória baseado no pacote de runtime do Go.

SHOW STATS FOR 'indexes'

Retorna o uso estimado de memória para todos os índices. Essa informação é excluída de SHOW STATS porque seu cálculo consome muitos recursos.

Exemplo:

> SHOW STATS
name: runtime
-------------
Alloc   Frees   HeapAlloc  HeapIdle   HeapInUse  HeapObjects  HeapReleased  HeapSys   Lookups  Mallocs  NumGC  NumGoroutine  PauseTotalNs  Sys        TotalAlloc
4136056 6684537 4136056    34586624   5816320    49412        0             40402944  110      6733949  83     44            36083006      46692600   439945704

name: graphite
tags: proto=tcp
batches_tx  bytes_rx  connections_active  connections_handled  points_rx  points_tx
----------  --------  ------------------  -------------------  ---------  ---------
159         3999750   0                   1                    158110     158110

SHOW SUBSCRIPTIONS

show_subscriptions_stmt = "SHOW SUBSCRIPTIONS" .

Exemplo:

SHOW SUBSCRIPTIONS

SHOW TAG KEY CARDINALITY

Retorna a cardinalidade estimada ou exata do conjunto de chaves de tag. Sem uma cláusula ON, o sistema usa o banco de dados atual.

O uso de cláusulas opcionais retorna a cardinalidade exata. A filtragem por tempo requer TSI; não use o filtro time em cláusulas WHERE.

show_tag_key_cardinality_stmt =
    "SHOW TAG KEY CARDINALITY"
    [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

show_tag_key_exact_cardinality_stmt =
    "SHOW TAG KEY EXACT CARDINALITY"
    [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ]

Exemplos:

-- Estimated tag key cardinality
SHOW TAG KEY CARDINALITY

-- Exact tag key cardinality
SHOW TAG KEY EXACT CARDINALITY

SHOW TAG KEYS

show_tag_keys_stmt = "SHOW TAG KEYS" [ on_clause ] [ from_clause ] [ where_clause ]
                     [ limit_clause ] [ offset_clause ] .

Exemplos:

-- List all tag keys
SHOW TAG KEYS

-- Tag keys from the cpu measurement
SHOW TAG KEYS FROM "cpu"

-- Tag keys from cpu where region = 'uswest'
SHOW TAG KEYS FROM "cpu" WHERE "region" = 'uswest'

-- Tag keys where host = 'serverA'
SHOW TAG KEYS WHERE "host" = 'serverA'

SHOW TAG VALUES

show_tag_values_stmt = "SHOW TAG VALUES" [ on_clause ] [ from_clause ] with_tag_clause [ where_clause ]
                       [ limit_clause ] [ offset_clause ] .

Exemplos:

-- All tag values for the region tag across all measurements
SHOW TAG VALUES WITH KEY = "region"

-- Tag values for the region tag from the cpu measurement
SHOW TAG VALUES FROM "cpu" WITH KEY = "region"

-- Tag values for all tag keys that don't contain the letter 'c'
SHOW TAG VALUES WITH KEY !~ /.*c.*/

-- Tag values for region and host from cpu where service = 'redis'
SHOW TAG VALUES FROM "cpu" WITH KEY IN ("region", "host") WHERE "service" = 'redis'

SHOW TAG VALUES CARDINALITY

Retorna a cardinalidade estimada ou exata dos valores de tag para chaves de tag especificadas. Sem uma cláusula ON, o sistema usa o banco de dados atual.

O uso de cláusulas opcionais retorna a cardinalidade exata. A filtragem por tempo requer TSI.

show_tag_values_cardinality_stmt =
    "SHOW TAG VALUES CARDINALITY"
    [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] with_key_clause

show_tag_values_exact_cardinality_stmt =
    "SHOW TAG VALUES EXACT CARDINALITY"
    [ on_clause ] [ from_clause ] [ where_clause ] [ group_by_clause ] [ limit_clause ] [ offset_clause ] with_key_clause

Exemplos:

-- Estimated cardinality for a tag key
SHOW TAG VALUES CARDINALITY WITH KEY = "myTagKey"

-- Exact cardinality for a tag key
SHOW TAG VALUES EXACT CARDINALITY WITH KEY = "myTagKey"

SHOW USERS

show_users_stmt = "SHOW USERS" .

Exemplo:

-- List all users
SHOW USERS

Cláusulas

from_clause     = "FROM" measurements .

group_by_clause = "GROUP BY" dimensions fill(fill_option) .

into_clause     = "INTO" ( measurement | back_ref ) .

limit_clause    = "LIMIT" int_lit .

offset_clause   = "OFFSET" int_lit .

slimit_clause   = "SLIMIT" int_lit .

soffset_clause  = "SOFFSET" int_lit .

timezone_clause = tz(string_lit) .

on_clause       = "ON" db_name .

order_by_clause = "ORDER BY" sort_fields .

to_clause       = "TO" user_name .

where_clause    = "WHERE" expr .

with_measurement_clause = "WITH MEASUREMENT" ( "=" measurement | "=~" regex_lit ) .

with_tag_clause = "WITH KEY" ( "=" tag_key | "!=" tag_key | "=~" regex_lit | "IN (" tag_keys ")" ) .

Expressões

binary_op  = "+" | "-" | "*" | "/" | "%" | "&" | "|" | "^" | "AND" |
             "OR" | "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=" .

expr       = unary_expr { binary_op unary_expr } .

unary_expr = "(" expr ")" | var_ref | time_lit | string_lit | int_lit |
             float_lit | bool_lit | duration_lit | regex_lit .

Outros elementos gramaticais

alias            = "AS" identifier .

back_ref         = ( policy_name ".:MEASUREMENT" ) |
                   ( db_name "." [ policy_name ] ".:MEASUREMENT" ) .

db_name          = identifier .

dimension        = expr .

dimensions       = dimension { "," dimension } .

field_key        = identifier .

field            = expr [ alias ] .

fields           = field { "," field } .

fill_option      = "null" | "none" | "previous" | int_lit | float_lit | "linear" .

host             = string_lit .

measurement      = measurement_name |
                   ( policy_name "." measurement_name ) |
                   ( db_name "." [ policy_name ] "." measurement_name ) .

measurements     = measurement { "," measurement } .

measurement_name = identifier | regex_lit .

password         = string_lit .

policy_name      = identifier .

privilege        = "ALL" [ "PRIVILEGES" ] | "READ" | "WRITE" .

query_id         = int_lit .

query_name       = identifier .

retention_policy = identifier .

retention_policy_option      = retention_policy_duration |
                               retention_policy_replication |
                               retention_policy_shard_group_duration |
                               "DEFAULT" .

retention_policy_duration    = "DURATION" duration_lit .

retention_policy_replication = "REPLICATION" int_lit .

retention_policy_shard_group_duration = "SHARD DURATION" duration_lit .

retention_policy_name = "NAME" identifier .

series_id        = int_lit .

shard_id         = int_lit .

sort_field       = field_key [ ASC | DESC ] .

sort_fields      = sort_field { "," sort_field } .

subscription_name = identifier .

tag_key          = identifier .

tag_keys         = tag_key { "," tag_key } .

user_name        = identifier .

var_ref          = measurement .

Comentários

Adicione comentários nas instruções InfluxQL para documentar suas consultas.

Comentário de linha única: começa com -- e termina na próxima quebra de linha. Não pode abranger várias linhas.
Comentário de múltiplas linhas: começa com /* e termina com */. Pode abranger várias linhas. Não há suporte para comentários aninhados de múltiplas linhas.

Detalhes internos do mecanismo de consulta

Compreender como o mecanismo de consulta executa o InfluxQL ajuda você a escrever consultas eficientes e interpretar a saída do EXPLAIN ANALYZE.

Ciclo de vida da consulta

Cada consulta InfluxQL segue quatro etapas:

O sistema tokeniza e analisa a instrução em uma árvore de sintaxe abstrata (AST) — a representação da consulta na memória.
A AST vai para o executor de consultas, que a encaminha ao manipulador apropriado. Consultas de metadados vão para o serviço de metadados; instruções SELECT são executadas nos shards.
O mecanismo de consulta identifica os shards correspondentes ao intervalo de tempo na instrução SELECT e cria um iterador para cada campo consultado.
Os iteradores vão para um emissor, que libera os iteradores, combina os pontos de dados resultantes, converte pontos de dados simples baseados em tempo em objetos complexos e os retorna ao cliente.

Iteradores

Os iteradores são a abstração central do mecanismo de consulta. Cada iterador fornece uma interface simples para streaming de pontos de dados. Por exemplo, um FloatIterator faz streaming de pontos de dados de ponto flutuante:

type FloatIterator interface {
    Next() *FloatPoint
}

Crie iteradores por meio da interface IteratorCreator:

type IteratorCreator interface {
    CreateIterator(opt *IteratorOptions) (Iterator, error)
}

O IteratorOptions especifica quais campos ler, o intervalo de tempo e as dimensões de agrupamento. O IteratorCreator está disponível nos níveis de Shards, Shard e Engine, permitindo que o mecanismo faça pushdown de operações — por exemplo, pré-agregando dados antes que COUNT() retorne resultados.

É possível compor iteradores: o DistinctIterator calcula valores distintos dentro de cada janela de tempo a partir de um iterador de entrada; o FillIterator gera valores de substituição para pontos de dados ausentes.

Um exemplo composto — calculando a derivada de uma média:

SELECT DERIVATIVE(MEAN(value), 20m) FROM cpu GROUP BY time(10m)

Isso produz um mean iterator (dos shards), encapsulado por um derivative iterator no nível do mecanismo.

Campos auxiliares

Funções seletoras como FIRST(), LAST(), MIN() e MAX() retornam tanto o ponto de dados selecionado quanto campos relacionados da mesma linha.

Por exemplo:

SELECT FIRST(value), host FROM cpu GROUP BY time(1h)

Isso retorna o value do primeiro ponto de dados em cada hora, juntamente com o host associado. Internamente, o mecanismo usa um único tipo de ponto de dados value e anexa host como um campo auxiliar — um campo transportado junto com o valor principal até chegar ao emissor. O emissor então separa os campos auxiliares e os roteia para seus respectivos iteradores.

Iteradores integrados

O mecanismo de consulta fornece os seguintes tipos de iteradores integrados:

Iterador	Finalidade
Merge iterator	Mescla um ou mais iteradores do mesmo tipo sem ordenar por tempo. Adequado para consultas agregadas que precisam de acesso rápido e não exigem ordenação.
Sorted merge iterator	Mescla e ordena pontos de dados por tempo. Mais lento que os merge iterators. Projetado para consultas não agregadas que retornam dados brutos em ordem temporal.
Limit iterator	Limita pontos de dados por nome ou grupo de tags, com base nas cláusulas `LIMIT` e `OFFSET`.
Fill iterator	Gera valores de substituição para pontos de dados ausentes: `null`, `none`, o valor anterior, um valor numérico especificado ou interpolação linear.
Buffered iterator	Retorna pontos de dados a um estado não lido para que possam ser relidos. Recomendado para operações de look-ahead em janelas de tempo.
Reduce iterator	Aplica uma função de redução a cada ponto de dados em uma janela de tempo, retornando todos os resultados após o fechamento da janela. Indicado para agregações simples como `COUNT()`.
Reduce slice iterator	Coleta todos os pontos de dados em uma janela de tempo e passa o slice completo para uma função de redução. Utilizado para agregações como `DERIVATIVE()`.
Transform iterator	Aplica uma função de transformação a cada ponto de dados de entrada para produzir um resultado de expressão binária.
Dedupe iterator	Deduplica pontos de dados e retorna apenas valores únicos. Consome muitos recursos; adequado apenas para pequenos conjuntos de dados, como consultas de metadados.

Iteradores de chamada

As funções do InfluxQL são executadas em dois níveis:

Nível de shard: funções como COUNT() são executadas dentro de cada shard. Um count iterator agrega vários iteradores de contagem por shard em um total. Crie esses iteradores usando NewCallIterator().
Nível de mecanismo: funções como DERIVATIVE() exigem todos os pontos de dados em uma janela de tempo antes de calcular os resultados. Esses iteradores não podem sofrer pushdown para shards individuais — o mecanismo de consulta os constrói após coletar a saída dos shards.

InfluxDB® é uma marca registrada da InfluxData, que não é afiliada e não endossa o TSDB for InfluxDB®.