Consulta de datos multivalor - Time Series Database - Centro de documentación de Alibaba Cloud

Consulta puntos de datos multivariados, es decir, datos almacenados con varios campos por métrica, mediante el endpoint /api/mquery. Para datos univariados, utilice /api/query.

Importante

Las rutas de escritura y consulta varían según el modelo de datos. Utilice /api/mput para escribir datos multivariados y /api/mquery para consultarlos. Para los datos univariados, use /api/put y /api/query. Estos dos modelos no son intercambiables.

Solicitud

Endpoint

Ruta	Método
`/api/mquery`	POST

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Obligatorio	Predeterminado	Descripción
`start`	Long	Sí	—	Hora de inicio. Acepta marcas de tiempo Unix en segundos o milisegundos. Consulte Unidades de marca de tiempo.
`end`	Long	No	Hora actual del servidor	Hora de finalización. Acepta marcas de tiempo Unix en segundos o milisegundos. Consulte Unidades de marca de tiempo.
`queries`	Array	Sí	—	Arreglo de objetos de subconsulta. Consulte Parámetros de subconsulta.
`msResolution`	Boolean	No	`false`	Cuando es `true`, devuelve marcas de tiempo en milisegundos para los puntos de datos almacenados en segundos. No tiene efecto en los datos almacenados en milisegundos, ya que estos siempre devuelven marcas de tiempo en milisegundos.
`hint`	Object	No	—	Indicación de consulta para limitar el uso de índices. Requiere TSDB V2.6.1 o posterior. Consulte Indicaciones de consulta.

Parámetros de subconsulta

Cada objeto del arreglo queries admite a continuación los siguientes parámetros:

Parámetro	Tipo	Obligatorio	Predeterminado	Descripción
`metric`	String	Sí	—	Nombre de la métrica.
`fields`	Array	Sí	—	Arreglo de objetos de consulta de campo. Consulte Parámetros de consulta de campo.
`rate`	Boolean	No	`false`	Calcula la tasa de crecimiento entre valores consecutivos: `(Vt − Vt-1) / (t − t-1)`.
`delta`	Boolean	No	`false`	Calcula el delta entre valores consecutivos: `Vt − Vt-1`. Consulte Operador delta.
`limit`	Integer	No	`0`	Número máximo de puntos de datos que se devuelven por línea de tiempo. El valor `0` indica que no hay límite. Se aplica únicamente a consultas multivariadas paginadas, no a consultas de campos individuales.
`offset`	Integer	No	`0`	Cantidad de puntos de datos que se omiten por línea de tiempo. Úselo junto con `limit` para la paginación.
`dpValue`	String	No	—	Filtra los puntos de datos devueltos por valor. Operadores compatibles: `>`, `<`, `=`, `<=`, `>=`, `!=`. Si se establece como una cadena, solo se admiten `=` y `!=`.
`preDpValue`	String	No	—	Filtra los puntos de datos durante el escaneo, antes de la agregación. A diferencia de `dpValue`, que filtra los resultados después de la agregación, `preDpValue` excluye los puntos de datos coincidentes de todas las consultas y cálculos.
`downsample`	String	No	—	Expresión de reducción de muestreo. Consulte Reducción de muestreo.
`tags`	Object	No	—	Pares clave-valor de etiquetas para filtrar datos. Entra en conflicto con `filters`. Si se especifican ambos, surte efecto el que aparece después en el JSON.
`filters`	Array	No	—	Objetos de filtro para el filtrado basado en etiquetas. Entra en conflicto con `tags`. Consulte Filtros.
`hint`	Object	No	—	Indicación de consulta a nivel de subconsulta. Anula la indicación de nivel superior para esta subconsulta.

Parámetros de consulta de campo

Cada objeto del arreglo fields admite a continuación los siguientes parámetros:

Parámetro	Tipo	Obligatorio	Predeterminado	Descripción
`aggregator`	String	Sí	—	Función de agregación que se aplicará. Establezca este valor en `none` para omitir la agregación. Si se especifica en alguna consulta de campo, debe especificarse en todas las consultas de campo dentro de la misma subconsulta.
`field`	String	Sí	—	Nombre del campo. Utilice `*` para consultar todos los campos de la métrica.
`alias`	String	No	—	Alias del nombre de campo devuelto.
`downsample`	String	No	—	Expresión de reducción de muestreo. Todas las consultas de campo de una misma subconsulta deben usar el mismo intervalo.
`rate`	Boolean	No	`false`	Calcula la tasa de crecimiento de este campo.
`dpValue`	String	No	—	Filtra los valores devueltos de este campo. Operadores compatibles: `>`, `<`, `=`, `<=`, `>=`, `!=`. Se aplica de forma independiente por campo y no afecta a otros campos.
`where`	String	No	—	Se usa únicamente cuando `field` es `*`. Filtra los campos antes de devolver los resultados con la misma lógica que `dpValue`. Por ejemplo: `speed>10`.

Una sola consulta puede incluir un máximo de 200 valores de campo en todas las subconsultas. Para contarlos, sume la cantidad de valores de field en todos los arreglos fields de todas las subconsultas.

Unidades de marca de tiempo

TSDB determina la unidad de la marca de tiempo a partir del valor numérico:

Rango	Unidad	Rango de fechas correspondiente
`[4284768, 9999999999]`	Segundos	1970-02-20 a 2286-11-21
`[10000000000, 9999999999999]`	Milisegundos	1970-04-27 a 2286-11-21
Fuera de ambos rangos	No válido	—

Estas reglas se aplican a /api/put, /api/mput, /api/query y /api/mquery.

Para consultar datos en un único punto en el tiempo, establezca start y end con el mismo valor. Por ejemplo: "start": 1356998400, "end": 1356998400.

Ejemplo de solicitud

POST /api/mquery

{
  "start": 1346846400,
  "end": 1346846411,
  "msResolution": true,
  "queries": [
    {
      "metric": "wind",
      "fields": [
        {
          "field": "speed",
          "aggregator": "sum",
          "downsample": "2s-last",
          "alias": "speed_sum"
        },
        {
          "field": "*",
          "aggregator": "sum",
          "downsample": "2s-count",
          "where": "speed>10"
        }
      ]
    }
  ]
}

Reducción de muestreo

La reducción de muestreo agrega datos en intervalos de tiempo fijos y disminuye la cantidad de puntos de datos devueltos. Utilícela al consultar rangos de tiempo largos donde no se requiere granularidad por segundo.

Formato de la expresión

<interval><units>-<aggregator>[-fill policy]

interval: un valor numérico como 5 o 60. Use 0all para agregar todos los puntos de datos del rango en un solo valor.

units:

Unidad	Significado
`s`	Segundos
`m`	Minutos
`h`	Horas
`d`	Días
`n`	Meses
`y`	Años

Agregue c para usar la alineación de calendario. Por ejemplo, 1dc representa el periodo de 24 horas desde las 00:00 del día actual. Sin c, las marcas de tiempo se alinean con la siguiente fórmula: aligned timestamp = data timestamp − (data timestamp % interval).

Opciones de aggregator:

Operador	Descripción
`avg`	Valor promedio
`count`	Cantidad de puntos de datos
`first`	Primer valor (marca de tiempo alineada)
`last`	Último valor (marca de tiempo alineada)
`min`	Valor mínimo (marca de tiempo alineada)
`max`	Valor máximo (marca de tiempo alineada)
`sum`	Suma de valores
`zimsum`	Suma de valores
`rfirst`	Primer valor con la marca de tiempo original (no alineada)
`rlast`	Último valor con la marca de tiempo original (no alineada)
`rmin`	Valor mínimo con la marca de tiempo original (no alineada)
`rmax`	Valor máximo con la marca de tiempo original (no alineada)

Los operadores rfirst , rlast , rmin y rmax no se pueden usar con una política de relleno.

Expansión de la ventana de tiempo

Después de especificar downsample, TSDB amplía automáticamente el rango de consulta en un intervalo por cada lado. Por ejemplo, si el rango es [1346846401, 1346846499] y el intervalo es 5m, el rango de consulta real se convierte en [1346846101, 1346846799].

Política de relleno

Cuando un intervalo de tiempo no contiene puntos de datos, la política de relleno determina qué valor se reporta para ese intervalo.

Política de relleno	Valor
`none`	No se rellena ningún valor. Este es el valor predeterminado.
`nan`	NaN
`null`	null
`zero`	0
`linear`	El valor calculado mediante interpolación lineal.
`previous`	El valor anterior.
`near`	El valor adyacente.
`after`	El valor siguiente.
`fixed`	Un valor fijo especificado por el usuario. Consulte Política de relleno fijo.

Política de relleno fijo

Agregue un valor fijo al formato mediante #:

<interval><units>-<aggregator>-fixed#<number>

El valor fijo puede ser positivo o negativo. Por ejemplo: 1h-sum-fixed#6, 1h-avg-fixed#-8.

Ejemplos de reducción de muestreo

Tres expresiones válidas de reducción de muestreo: 1m-avg, 1h-sum-zero, 1h-sum-near.

Importante

El parámetro downsample es opcional en las consultas de campo. Para deshabilitar explícitamente la reducción de muestreo, establézcalo en null o en una cadena vacía: {"downsample": null} o {"downsample": ""}. Si una consulta de campo dentro de una subconsulta especifica downsample, todas las consultas de campo de esa subconsulta deben especificar el mismo intervalo.

Agregador

Después de la reducción de muestreo, varias líneas de tiempo pueden compartir marcas de tiempo alineadas. El parámetro aggregator fusiona esas líneas de tiempo en una sola al agregar los valores de cada marca de tiempo. Si solo existe una línea de tiempo, no se realiza ninguna agregación.

Importante

El parámetro aggregator es obligatorio en todas las consultas de campo. Establezca este valor en none para omitir la agregación. Si alguna consulta de campo de una subconsulta especifica aggregator, todas las consultas de campo de esa subconsulta deben especificarlo. No se admite la agregación parcial dentro de una subconsulta.

Interpolación

Al agregar varias líneas de tiempo, si una línea no tiene valor en una marca de tiempo alineada pero otra sí, TSDB interpola un valor para la línea faltante. Esto solo aplica cuando no se ha configurado ninguna política de relleno.

El método de interpolación depende del agregador:

Agregador	Método de interpolación
`avg`	Interpolación lineal
`count`	Interpola cero
`min`	Interpolación lineal
`max`	Interpolación lineal
`mimmin`	Interpola el valor máximo
`mimmax`	Interpola el valor mínimo
`none`	Interpola cero
`sum`	Interpolación lineal
`zimsum`	Interpola cero

Operador delta

Cuando delta se establece en true, el valor value de cada par clave-valor dps se reemplaza por el delta calculado (Vt − Vt-1).

Importante

Si el resultado original contiene n pares clave-valor, el resultado del delta contendrá n-1 pares. El primer par se descarta porque no existe un valor previo con el cual calcularlo. El operador delta también se aplica después de la reducción de muestreo.

Parámetros de deltaOptions

Parámetro	Tipo	Obligatorio	Predeterminado	Descripción
`counter`	Boolean	No	`false`	Trata los valores de la métrica como contadores monótonos crecientes o decrecientes. El servidor no valida la monotonicidad.
`counterMax`	Integer	No	—	Delta absoluto máximo permitido. Los deltas que superan este umbral se consideran anómalos y se descartan o se restablecen a `0`. Solo aplica cuando `counter` es `true`.
`dropReset`	Boolean	No	`false`	Requiere `counterMax`. Cuando se detecta un delta anómalo, el valor `true` lo descarta; el valor `false` (o su omisión) lo restablece a `0`.

Ejemplo

{
  "start": 1346046400,
  "end": 1347056500,
  "queries": [
    {
      "metric": "sys.cpu.0",
      "aggregator": "none",
      "downsample": "5s-avg",
      "delta": true,
      "deltaOptions": {
        "counter": true,
        "counterMax": 100
      },
      "dpValue": ">=50",
      "tags": {
        "host": "localhost",
        "appName": "hitsdb"
      }
    }
  ]
}

Paginación con limit y offset

Utilice limit y offset para paginar resultados en varias líneas de tiempo.

limit: número máximo de puntos de datos por línea de tiempo y página. El valor 0 indica que no hay límite (valor predeterminado).
offset: cantidad de puntos de datos que se omiten por línea de tiempo.

Importante

Ni limit ni offset pueden ser negativos. Estos parámetros se aplican a consultas multivariadas paginadas y no se pueden usar en consultas de un solo campo.

Ejemplo: para devolver los puntos de datos clasificados del 1001 al 1500, establezca limit en 500 y offset en 1000.

{
  "start": 1346846400,
  "end": 1346846411,
  "msResolution": true,
  "queries": [
    {
      "metric": "wind",
      "fields": [
        {
          "field": "*",
          "aggregator": "sum",
          "downsample": "2s-count"
        }
      ],
      "filters": [
        {
          "filter": "IOTE_8859_0005|IOTE_8859_0004",
          "tagk": "sensor",
          "type": "literal_or"
        }
      ],
      "limit": 500,
      "offset": 1000
    }
  ]
}

Filtros

Los filtros seleccionan qué líneas de tiempo se incluyen en una consulta según los valores de las etiquetas. El parámetro filters entra en conflicto con tags. Si ambos aparecen en el JSON, surte efecto el que se encuentre en la última posición.

Parámetros del objeto de filtro

Parámetro	Tipo	Obligatorio	Predeterminado	Descripción
`type`	String	Sí	—	Tipo de filtro. Consulte los tipos de filtro a continuación.
`tagk`	String	Sí	—	Clave de etiqueta sobre la cual se filtra.
`filter`	String	Sí	—	Expresión de filtro.
`groupBy`	Boolean	No	`false`	Agrupa los resultados por valores de etiqueta.

Tipos de filtro

Tipo	Ejemplo	Descripción
`literal_or`	`web01	web02`	Se agregan los valores de cada tagv. Este filtro distingue entre mayúsculas y minúsculas.
`wildcard`	`*.example.com`	Se agregan los valores de etiqueta que contienen el comodín especificado para cada tagv. Este filtro distingue entre mayúsculas y minúsculas.

También puede especificar filtros mediante la notación abreviada de etiquetas:

tagk = *: agrupa todos los valores de etiqueta para esa clave y los agrega por valor distinto.
tagk = tagv1|tagv2: agrupa los valores de tagv1 entre sí y los valores de tagv2 entre sí.

Ejemplo con filtros

{
  "start": 1346846400,
  "end": 1346846411,
  "msResolution": true,
  "queries": [
    {
      "metric": "wind",
      "fields": [
        {
          "field": "speed",
          "aggregator": "none",
          "alias": "column_speed"
        },
        {
          "field": "*",
          "aggregator": "none",
          "alias": "column_"
        }
      ],
      "filters": [
        {
          "filter": "IOTE_8859_0005|IOTE_8859_0004",
          "tagk": "sensor",
          "type": "literal_or"
        }
      ]
    }
  ]
}

Respuesta

Una consulta exitosa devuelve HTTP 200 con un arreglo JSON.

Campos de respuesta

Campo	Descripción
`metric`	Nombre de la métrica.
`columns`	Columnas devueltas.
`tags`	Etiquetas cuyos valores no se agregaron (se aplicaron como filtros exactos).
`aggregatedTags`	Etiquetas cuyos valores se agregaron entre líneas de tiempo.
`values`	Arreglo de tuplas. Cada tupla corresponde a una fila de datos identificada por `columns`.

Ejemplo: aggregator establecido en none

Devuelve un objeto de resultado por cada línea de tiempo coincidente (sin agregación entre sensores):

[
  {
    "metric": "wind",
    "columns": [
      "timestamp",
      "column_speed",
      "column_description",
      "column_direction",
      "column_level",
      "column_speed"
    ],
    "tags": {
      "city": "hangzhou",
      "country": "china",
      "province": "zhejiang",
      "sensor": "IOTE_8859_0005"
    },
    "aggregatedTags": [],
    "values": [
      [1346846406000, null, "Fresh breeze", "East", 0.5, null],
      [1346846407000, null, "Fresh breeze", "South", 1.5, null]
    ]
  },
  {
    "metric": "wind",
    "columns": [
      "timestamp",
      "column_speed",
      "column_description",
      "column_direction",
      "column_level",
      "column_speed"
    ],
    "tags": {
      "city": "hangzhou",
      "country": "china",
      "province": "zhejiang",
      "sensor": "IOTE_8859_0004"
    },
    "aggregatedTags": [],
    "values": [
      [1346846400000, 40.4, "Fresh breeze", "East", 0.4, 40.4],
      [1346846401000, 41.4, "Fresh breeze", "South", 1.4, 41.4],
      [1346846402000, 42.4, "Fresh breeze", "West", 2.4, 42.4],
      [1346846403000, 43.4, "Fresh breeze", "North", 3.4, 43.4]
    ]
  }
]

Ejemplo: aggregator establecido en avg

Devuelve la velocidad y el nivel promedio del viento, agregados entre todos los sensores de la ciudad:

[
  {
    "metric": "wind",
    "columns": ["timestamp", "avg_level", "avg_speed"],
    "tags": {
      "city": "hangzhou"
    },
    "aggregatedTags": ["country", "province", "sensor"],
    "values": [
      [1346846400000, 0.25, 40.25],
      [1346846401000, 1.25, 41.25],
      [1346846402000, 2.5, 42.5],
      [1346846411000, 5.5, null]
    ]
  }
]

Indicaciones de consulta

Una indicación de consulta le indica a TSDB qué índices de etiquetas debe usar u omitir al resolver líneas de tiempo. Esto reduce el tiempo de respuesta cuando el conjunto de líneas de tiempo definido por un grupo de etiquetas es un subconjunto conocido de otro.

Importante

Requiere TSDB V2.6.1 o posterior.

Formato

Especifique los nombres de las claves de etiqueta en hint.tagk con los valores 0 (omitir índice) o 1 (usar índice). Todos los valores de una misma indicación deben ser exclusivamente 0 o 1. Mezclarlos genera un error.

Indicación aplicada a una subconsulta

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": ["speed"],
      "hint": {
        "tagk": { "dc": 1 }
      }
    }
  ]
}

Indicación aplicada a toda la consulta

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": ["speed"]
    }
  ],
  "hint": {
    "tagk": { "dc": 1 }
  }
}

Error: mezcla de 0 y 1 en la misma indicación

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "tags": {
        "dc": "lga",
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 1,
      "host": 0
    }
  }
}

Devuelve:

{
  "error": {
    "code": 400,
    "message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1",
    "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
  }
}

Error: valor de indicación no válido

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "tags": {
        "dc": "lga",
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 100
    }
  }
}

Devuelve:

{
  "error": {
    "code": 400,
    "message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in",
    "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
  }
}