InfluxQL reference - Time Series Database - Centro de documentación de Alibaba Cloud

InfluxQL (Influx Query Language) es un lenguaje de consulta similar a SQL para TSDB for InfluxDB. Esta referencia abarca la especificación completa de la sintaxis, incluida la notación, los literales, las instrucciones, las cláusulas, las expresiones y los componentes internos del motor de consultas.

En esta página

Notación
Elementos de consulta
Literales
Consultas
Instrucciones
Cláusulas
Expresiones
Otros elementos gramaticales
Comentarios
Componentes internos del motor de consultas

Notación

La sintaxis de InfluxQL se especifica mediante la Forma Extendida de Backus-Naur (EBNF), la misma notación que utiliza la especificación del lenguaje de programación 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 notación en orden creciente de precedencia:

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

Elementos de consulta

Caracteres

InfluxQL admite texto Unicode codificado en UTF-8.

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

Letras y dígitos

Las letras en InfluxQL incluyen caracteres ASCII y guiones bajos. Los guiones bajos (U+005F) se comportan como letras. InfluxQL solo admite dígitos decimales.

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

Identificadores

Los identificadores nombran bases de datos, directivas de retención, usuarios, mediciones, claves de etiqueta y claves de campo.

Los identificadores entre comillas dobles pueden:

Contener caracteres Unicode (pero no saltos de línea)
Usar \" para escapar comillas dobles
Contener palabras clave de InfluxQL

Los identificadores sin comillas deben:

Comenzar con una letra ASCII o un guion bajo
Contener únicamente letras ASCII, dígitos y guiones bajos

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

Ejemplos:

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

Palabras clave

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

Cuando se usan como identificadores en instrucciones de consulta, las palabras clave deben encerrarse entre comillas dobles.

Excepción: time

La palabra clave time puede usarse como identificador sin comillas dobles en los siguientes nombres: consulta continua, base de datos, medición, directiva de retención, suscripción y usuario. Sin embargo, time no puede utilizarse como clave de campo ni como clave de etiqueta; intentar escribir datos con time como clave de campo o de etiqueta devuelve un error.

Literales

Enteros

InfluxQL solo admite enteros decimales. No se admiten enteros hexadecimales ni octales.

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

Flotantes

InfluxQL admite números de punto flotante, pero no exponentes.

float_lit = int_lit "." int_lit .

Cadenas

Las cadenas deben encerrarse entre comillas simples. Use \' para escapar comillas simples dentro de una cadena.

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

Duraciones

Un literal de duración consiste en un entero seguido inmediatamente por una unidad de tiempo, sin espacios entre ellos. Se pueden combinar varias unidades para expresar una duración.

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

Unidades válidas

Unidad	Descripción
`ns`	Nanosegundo (una milmillonésima de segundo)
`u` o `µ`	Microsegundo (una millonésima de segundo)
`ms`	Milisegundo (una milésima de segundo)
`s`	Segundo
`m`	Minuto
`h`	Hora
`d`	Día
`w`	Semana

Fecha y hora

El formato de fecha y hora en InfluxQL sigue las reglas de formato y análisis de Go en lugar de EBNF. La marca de tiempo de referencia (2 de enero de 2006, 15:04:05) define el formato requerido:

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

Valores booleanos

bool_lit = TRUE | FALSE .

Expresiones regulares

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

Operadores: =~ coincide, !~ no coincide.

Las expresiones regulares pueden usarse para:

Claves de campo y claves de etiqueta en cláusulas SELECT
Mediciones en cláusulas FROM
Valores de etiqueta en cláusulas WHERE
Claves de etiqueta en cláusulas GROUP BY

Las expresiones regulares no pueden usarse para:

Valores de campo no string en cláusulas WHERE
Bases de datos
Directivas de retención

Consultas

Una consulta consta de una o más instrucciones separadas por punto y coma (;).

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 .

Instrucciones

DELETE

Importante

TSDB for InfluxDB® admite operaciones de eliminación. Debido a la sintaxis subyacente de eliminación en InfluxDB®, estas operaciones pueden causar interbloqueos y provocar fallos de lectura o escritura. Evite ejecutar operaciones de eliminación en TSDB for InfluxDB®.

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

Ejemplos:

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

EXPLAIN

EXPLAIN analiza y planifica una consulta, y luego devuelve un resumen estimado del costo de recursos.

A diferencia de los motores SQL que admiten operaciones de unión, InfluxQL no las soporta. La salida del plan refleja costos específicos de las consultas InfluxQL: el número de series temporales accedidas, el número de iteradores que leen archivos Time-Structured Merge Tree (TSM) y el número de bloques TSM escaneados.

Un resultado de EXPLAIN incluye:

Expresión
Campos auxiliares
Número de shards
Número de series
Valores en caché
Número de archivos
Número de bloques
Tamaño de los bloques

Ejemplo:

> 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

EXPLAIN ANALYZE ejecuta una consulta InfluxQL y devuelve los costos reales de recursos medidos durante la ejecución.

explain_analyze_stmt = "EXPLAIN ANALYZE" select_stmt .

Ejemplo:

> 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

KILL QUERY detiene una consulta en ejecución mediante su ID de consulta.

kill_query_statement = "KILL QUERY" query_id .

Para obtener el ID de consulta, ejecute SHOW QUERIES. El campo qid en el resultado corresponde al ID de la consulta.

Ejemplo:

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

Ejemplos:

Consulte datos de todas las mediciones con prefijo cpu y escriba los resultados en los mismos nombres de medición dentro de la directiva de retención cpu_1h:

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

Consulte datos de la medición cpu, agrupados por día en la zona horaria America/Chicago:

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

SHOW CARDINALITY

SHOW CARDINALITY es una familia de comandos para consultar la cardinalidad de mediciones, series, claves de etiqueta, valores de etiqueta y claves de campo.

Hay dos modos disponibles:

Cardinalidad estimada: se calcula a partir de un plan interno. Tiene una sobrecarga baja independientemente del tamaño de los datos. Úsela de forma predeterminada.
Cardinalidad exacta: se calcula a partir de datos TSM. Genera una alta sobrecarga en conjuntos de datos grandes. Úsela solo si su caso de uso requiere precisión.

El filtrado basado en tiempo solo está disponible cuando la función Time Series Index (TSI) está habilitada para su base de datos.

Para consultar la sintaxis de cada instrucción 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" .

Ejemplo:

-- List all continuous queries
SHOW CONTINUOUS QUERIES

SHOW DATABASES

show_databases_stmt = "SHOW DATABASES" .

Ejemplo:

-- List all databases
SHOW DATABASES

SHOW DIAGNOSTICS

Devuelve información del nodo, incluidos detalles de compilación, información de tiempo de ejecución, nombre de host, configuración del servidor, uso de memoria y diagnósticos del entorno de ejecución de Go.

show_diagnostics_stmt = "SHOW DIAGNOSTICS" .

SHOW FIELD KEY CARDINALITY

Devuelve la cardinalidad estimada o exacta del conjunto de claves de campo. Si no se incluye una cláusula ON, se utiliza la base de datos actual.

El uso de cláusulas opcionales devuelve la cardinalidad exacta. El filtrado por tiempo requiere TSI; el filtro time no puede usarse en 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 ]

Ejemplos:

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

Ejemplos:

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

Ejemplo:

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

SHOW MEASUREMENT CARDINALITY

Devuelve la cardinalidad estimada o exacta del conjunto de mediciones. Si no se incluye una cláusula ON, se utiliza la base de datos actual.

El uso de cláusulas opcionales devuelve la cardinalidad exacta. El filtrado por tiempo requiere TSI; el filtro time no puede usarse en 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 ]

Ejemplos:

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

Ejemplos:

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

Ejemplo:

-- List all currently running queries
SHOW QUERIES

SHOW RETENTION POLICIES

show_retention_policies_stmt = "SHOW RETENTION POLICIES" [ on_clause ] .

Ejemplo:

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

Ejemplo:

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

SHOW SERIES CARDINALITY

Devuelve la cardinalidad estimada o exacta del conjunto de series. Si no se incluye una cláusula ON, se utiliza la base de datos actual.

La cardinalidad de series afecta directamente el uso de RAM.

El uso de cláusulas opcionales devuelve la cardinalidad exacta. El filtrado por tiempo requiere TSI; el filtro time no puede usarse en 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 ]

Ejemplos:

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

Ejemplo:

SHOW SHARD GROUPS

SHOW SHARDS

show_shards_stmt = "SHOW SHARDS" .

Ejemplo:

SHOW SHARDS

SHOW STATS

Devuelve información estadística sobre un nodo de TSDB for InfluxDB y sus componentes disponibles.

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

SHOW STATS

Devuelve estadísticas de todos los componentes, excepto el uso de memoria de índices. Los valores estadísticos se almacenan en memoria y se restablecen a cero al reiniciar el nodo. TSDB for InfluxDB ejecuta automáticamente SHOW STATS cada 10 segundos para poblar la base de datos _internal.

SHOW STATS FOR \<component\>

Devuelve estadísticas de un componente específico. Para el componente runtime, devuelve un resumen del uso de memoria basado en el paquete de tiempo de ejecución de Go.

SHOW STATS FOR 'indexes'

Devuelve el uso estimado de memoria para todos los índices. Esta información se excluye de SHOW STATS porque su cálculo consume muchos recursos.

Ejemplo:

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

Ejemplo:

SHOW SUBSCRIPTIONS

SHOW TAG KEY CARDINALITY

Devuelve la cardinalidad estimada o exacta del conjunto de claves de etiqueta. Si no se incluye una cláusula ON, se utiliza la base de datos actual.

El uso de cláusulas opcionales devuelve la cardinalidad exacta. El filtrado por tiempo requiere TSI; el filtro time no puede usarse en 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 ]

Ejemplos:

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

Ejemplos:

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

Ejemplos:

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

Devuelve la cardinalidad estimada o exacta de los valores de etiqueta para las claves de etiqueta especificadas. Si no se incluye una cláusula ON, se utiliza la base de datos actual.

El uso de cláusulas opcionales devuelve la cardinalidad exacta. El filtrado por tiempo requiere 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

Ejemplos:

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

Ejemplo:

-- 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 ")" ) .

Expresiones

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 .

Otros elementos gramaticales

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 .

Comentarios

Agregue comentarios en las instrucciones de InfluxQL para documentar sus consultas.

Comentario de una sola línea: comienza con -- y termina en el siguiente salto de línea. No puede abarcar varias líneas.
Comentario de varias líneas: comienza con /* y termina con */. Puede abarcar varias líneas. No se admiten comentarios anidados de varias líneas.

Funcionamiento interno del motor de consultas

Comprender cómo ejecuta el motor de consultas InfluxQL le ayuda a escribir consultas eficientes e interpretar la salida de EXPLAIN ANALYZE.

Ciclo de vida de la consulta

Cada consulta de InfluxQL sigue cuatro pasos:

La instrucción se tokeniza y se analiza sintácticamente para generar un árbol de sintaxis abstracta (AST), que es la representación de la consulta en memoria.
El AST se pasa al ejecutor de consultas, que lo enruta al controlador correspondiente. Las consultas de metadatos van al servicio de metadatos; las instrucciones SELECT se ejecutan en los shards.
El motor de consultas identifica los shards que coinciden con el intervalo de tiempo en la instrucción SELECT y luego crea un iterador para cada campo consultado.
Los iteradores se pasan a un emisor, que libera los iteradores, combina los puntos de datos resultantes, convierte los puntos de datos simples basados en tiempo en objetos complejos y los devuelve al cliente.

Iteradores

Los iteradores son la abstracción principal del motor de consultas. Cada iterador proporciona una interfaz simple para hacer streaming de puntos de datos. Por ejemplo, un FloatIterator hace streaming de puntos de datos de punto flotante:

type FloatIterator interface {
    Next() *FloatPoint
}

Los iteradores se crean mediante la interfaz IteratorCreator:

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

IteratorOptions especifica qué campos leer, el intervalo de tiempo y las dimensiones de agrupación. IteratorCreator está disponible en los niveles de Shards, Shard y Engine, lo que permite al motor delegar operaciones hacia abajo; por ejemplo, preagregar datos antes de que COUNT() devuelva resultados.

Los iteradores pueden componerse: DistinctIterator calcula valores distintos dentro de cada ventana de tiempo a partir de un iterador de entrada; FillIterator genera valores de reemplazo para los puntos de datos faltantes.

Un ejemplo de composición — cálculo de la derivada de un promedio:

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

Esto produce un mean iterator (desde los shards), envuelto por un derivative iterator a nivel del motor.

Campos auxiliares

Las funciones selectoras como FIRST(), LAST(), MIN() y MAX() devuelven tanto el punto de datos seleccionado como los campos relacionados de la misma fila.

Por ejemplo:

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

Esto devuelve el value del primer punto de datos en cada hora junto con el host asociado. Internamente, el motor utiliza un único tipo de punto de datos value y adjunta host como un campo auxiliar, es decir, un campo que se transporta junto con el valor principal hasta llegar al emisor. Luego, el emisor separa los campos auxiliares y los enruta a sus respectivos iteradores.

Iteradores integrados

El motor de consultas proporciona los siguientes tipos de iteradores integrados:

Iterador	Propósito
Iterador de fusión	Fusiona uno o más iteradores del mismo tipo sin ordenarlos por tiempo. Se usa en consultas agregadas que requieren acceso rápido y no necesitan ordenamiento.
Iterador de fusión ordenada	Fusiona y ordena los puntos de datos por tiempo. Es más lento que los iteradores de fusión. Se usa en consultas no agregadas que devuelven datos sin procesar en orden cronológico.
Iterador de límite	Limita los puntos de datos por nombre o grupo de etiquetas, según las cláusulas `LIMIT` y `OFFSET`.
Iterador de relleno	Genera valores de reemplazo para puntos de datos faltantes: `null`, `none`, el valor anterior, un valor numérico específico o interpolación lineal.
Iterador con búfer	Devuelve los puntos de datos a un estado no leído para que puedan volver a leerse. Se usa en operaciones de anticipación de ventanas de tiempo.
Iterador de reducción	Aplica una función de reducción a cada punto de datos en una ventana de tiempo y devuelve todos los resultados después de que se cierra la ventana. Se usa para agregaciones simples como `COUNT()`.
Iterador de reducción por segmento	Recopila todos los puntos de datos en una ventana de tiempo y luego pasa el segmento completo a una función de reducción. Se usa para agregaciones como `DERIVATIVE()`.
Iterador de transformación	Aplica una función de transformación a cada punto de datos de entrada para producir un resultado de expresión binaria.
Iterador de deduplicación	Deduplica los puntos de datos y devuelve solo valores únicos. Consume muchos recursos; solo es adecuado para conjuntos de datos pequeños, como consultas de metadatos.

Iteradores de llamada

Las funciones de InfluxQL se ejecutan en dos niveles:

Nivel de shard: funciones como COUNT() se ejecutan dentro de cada shard. Un count iterator agrega varios iteradores de conteo por shard en un total. Estos iteradores se crean mediante NewCallIterator().
Nivel de motor: funciones como DERIVATIVE() requieren todos los puntos de datos en una ventana de tiempo antes de calcular los resultados. Estos iteradores no pueden delegarse a shards individuales; el motor de consultas los construye después de recopilar la salida de los shards.

InfluxDB® es una marca registrada de InfluxData, que no está afiliada ni avala TSDB for InfluxDB®.