# Sintaxis de InfluxQL

## **Características principales:**

* Sintaxis familiar para usuarios de SQL.
* Operaciones optimizadas para series temporales.
* Amplio soporte para funciones de agregación y análisis.
* Compatible con InfluxDB 2.x mediante el endpoint de compatibilidad y mapeos DBRP.

## **Estructura General de una Consulta InfluxQL** <a href="#undefined" id="undefined"></a>

La estructura básica de una consulta InfluxQL es:

{% code title="sql" overflow="wrap" %}

```sql
SELECT <field_key>[, <field_key>, <tag_key>] FROM <measurement>
[WHERE <condición>]
[GROUP BY <tag_key>[, <tag_key>]]
[ORDER BY time DESC]
[LIMIT n OFFSET m]
```

{% endcode %}

* Se deben seleccionar al menos uno o más fields; los tags pueden acompañar pero no pueden ir solos en el SELECT.

## **Componentes principales**

* **SELECT**: Especifica los campos y/o etiquetas a consultar.
* **FROM**: Indica la medición o mediciones de origen.
* **WHERE**: Filtra los datos según condiciones.
* **GROUP BY**: Agrupa los resultados por tiempo o etiquetas.
* **ORDER BY**: Ordena los resultados.
* **LIMIT / OFFSET**: Controla la cantidad de resultados devueltos.

## **Identificadores y Literales** <a href="#undefined" id="undefined"></a>

### **Identificadores**

* Pueden ser nombres de bases de datos, políticas de retención, mediciones, fields o tags.
* **Sin comillas**: Solo letras, dígitos y guión bajo, no pueden comenzar con dígito.
* **Con comillas dobles**: Permiten cualquier carácter Unicode excepto salto de línea. Se usan para palabras reservadas o nombres especiales.

**Ejemplos:**

{% code title="sq" overflow="wrap" %}

```sql
cpu
_cpu_stats
"1h"
"temperatura ambiente"
```

{% endcode %}

### **Literales**

* **Números**: Enteros o decimales.
* **Cadenas**: Entre comillas simples.
* **Booleanos**: `true`, `false`.
* **Tiempos**: ISO8601 o epoch, entre comillas simples.

### **SELECT y FROM: Selección de fields y tags** <a href="#undefined" id="undefined"></a>

* **SELECT**: Permite seleccionar fields y tags. Si un nombre se repite como field y tag, se puede especificar con `::field` o `::tag`.

{% code title="sql" overflow="wrap" %}

```sql
SELECT * FROM temperatura
SELECT "valor", "ubicación" FROM sensores
```

{% endcode %}

* `SELECT * FROM sensores` (todos los fields y tags)
* `SELECT "temperatura", "ubicacion" FROM sensores`
* `SELECT "temperatura"::field, "ubicacion"::tag FROM sensores` (desambiguación)
* **FROM**: Indica la medición de origen. Puede especificar base de datos y política de retención si es necesario.

{% code title="sql" overflow="wrap" %}

```sql
FROM medicion
FROM "base"."retencion"."medicion"
```

{% endcode %}

### **WHERE: Filtrado por fields, tags y tiempo** <a href="#undefined" id="undefined"></a>

{% code title="sql" overflow="wrap" %}

```sql
SELECT ... FROM ... WHERE <condición>
```

{% endcode %}

* **Filtrar por tag**: Muy eficiente, ya que los tags están indexados.
  * `WHERE "ubicacion" = 'Madrid'`
* **Filtrar por field**: Menos eficiente, ya que requiere escanear los datos.
  * `WHERE "temperatura" > 25`
* **Filtrar por tiempo**:
  * `WHERE time >= '2025-01-01T00:00:00Z'`

**Operadores soportados**:

* `=`, `!=`, `<`, `>`, `<=`, `>=` (fields y tags)
* `=~`, `!~` (expresiones regulares en tags y fields tipo string)

| Operador | Significado                    | Tipos soportados    |
| -------- | ------------------------------ | ------------------- |
| =        | Igual a                        | Todos               |
| !=, <>   | Distinto de                    | Todos               |
| >, >=    | Mayor, mayor o igual           | Numérico, timestamp |
| <, <=    | Menor, menor o igual           | Numérico, timestamp |
| =\~      | Coincide con expresión regular | Strings             |
| !\~      | No coincide con expresión reg. | Strings             |

**Notas sobre comillas:**

* Comillas simples para literales (`'Madrid'`).
* Comillas dobles para identificadores (`"ubicación"`).

No se pueden consultar múltiples rangos de tiempo con `OR` en la cláusula WHERE

### **GROUP BY: Agrupación por tags y tiempo** <a href="#undefined" id="undefined"></a>

{% code title="sql" overflow="wrap" %}

```sql
SELECT MEAN("valor") FROM temperatura GROUP BY time(1h), "ubicación"
```

{% endcode %}

`time(<intervalo>)`: Agrupa por ventanas de tiempo (ej: 1h, 10m)

* Agrupar por uno o más tags:
  * `GROUP BY "ubicacion"`
  * `GROUP BY "ubicacion", "dispositivo"`
* Agrupar por tiempo y tags:
  * `GROUP BY time(1h), "ubicacion"`
* Agrupar por todos los tags:
  * `GROUP BY *` (útil para obtener series por cada combinación de tags).

### **Funciones de Agregación sobre fields** <a href="#undefined" id="undefined"></a>

InfluxQL soporta funciones como:

* **MEAN()**: Promedio.
* **SUM()**: Suma.
* **MIN()**, **MAX()**: Mínimo y máximo.
* **COUNT()**: Conteo de puntos.
* **DERIVATIVE()**: Derivada.
* **DIFFERENCE()**: Diferencia entre valores consecutivos.
* **SPREAD()**: Rango (max - min).

Las funciones de agregación solo se aplican sobre fields

**Ejemplo:**

{% code title="sql" overflow="wrap" %}

```sql
SELECT MEAN("temperatura") FROM sensores WHERE time >= now() - 1d GROUP BY time(1h), "ubicacion"
```

{% endcode %}

> **Nota:** No se puede mezclar una función de agregación con fields o tags sin función en el mismo SELECT.

### **Orden, Límite y Desplazamiento** <a href="#undefined" id="undefined"></a>

* `ORDER BY time DESC` (por defecto es ascendente)
* `LIMIT n` (limita el número de resultados)
* `OFFSET m` (omite los primeros m resultados)

## **Exploración de Esquema: fields y tags** <a href="#undefined" id="undefined"></a>

InfluxQL permite explorar el esquema de la base de datos:

* **`SHOW DATABASES`**: Lista bases de datos.
* **`SHOW MEASUREMENTS`**: Lista mediciones.
* **`SHOW TAG KEYS / VALUES`**: Lista claves y valores de etiquetas.
  * **Mostrar valores posibles de un tag**: `SHOW TAG VALUES WITH KEY = "<tag_key>" [FROM <measurement>]`
* **`SHOW FIELD KEYS`**`[FROM <measurement>]`: Lista claves de campos.
* **`SHOW RETENTION POLICIES`**: Lista políticas de retención.

## **Operadores Matemáticos y Expresiones** <a href="#undefined" id="undefined"></a>

* Soporta operadores aritméticos: `+`, `-`, `*`, `/`.
* Se pueden combinar funciones y operadores en el SELECT.

**Ejemplo:**

{% code title="sql" overflow="wrap" %}

```sql
SELECT ("valor1" + "valor2") / 2 AS "promedio" FROM sensores
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://darioaplicano.gitbook.io/influxdb2.x/sesion-2/guion-de-la-sesion/documentacion/lenguaje-de-consultas-en-influxdb/influxql/sintaxis-de-influxql.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.