Interrogation de données multivariées - Time Series Database

Requête

Endpoint

Path	Method
`/api/mquery`	POST

Paramètres du corps de la requête

Parameter	Type	Required	Default	Description
`start`	Long	Oui	—	Heure de début. Accepte les horodatages Unix en secondes ou en millisecondes. Consultez la section Unités d'horodatage.
`end`	Long	Non	Heure actuelle du serveur	Heure de fin. Accepte les horodatages Unix en secondes ou en millisecondes. Consultez la section Unités d'horodatage.
`queries`	Array	Oui	—	Tableau d'objets de sous-requête. Consultez la section Paramètres de sous-requête.
`msResolution`	Boolean	Non	`false`	Si défini sur `true`, renvoie les horodatages en millisecondes pour les points de données stockés en secondes. Sans effet sur les données stockées en millisecondes, qui renvoient toujours des horodatages en millisecondes.
`hint`	Object	Non	—	Indice de requête permettant de limiter l'utilisation de l'index. Nécessite TSDB V2.6.1 ou version ultérieure. Consultez la section Indices de requête.

Paramètres de sous-requête

Chaque objet du tableau queries prend en charge les paramètres suivants :

Parameter	Type	Required	Default	Description
`metric`	String	Oui	—	Nom de la métrique.
`fields`	Array	Oui	—	Tableau d'objets de requête de champ. Consultez la section Paramètres de requête de champ.
`rate`	Boolean	Non	`false`	Calcule le taux de croissance entre les valeurs consécutives : `(Vt − Vt-1) / (t − t-1)`.
`delta`	Boolean	Non	`false`	Calcule la différence entre les valeurs consécutives : `Vt − Vt-1`. Consultez la section Opérateur Delta.
`limit`	Integer	Non	`0`	Nombre maximal de points de données à renvoyer par série chronologique. La valeur `0` signifie qu'il n'y a aucune limite. S'applique uniquement aux requêtes multivariées paginées, et non aux requêtes de champ individuelles.
`offset`	Integer	Non	`0`	Nombre de points de données à ignorer par série chronologique. À utiliser conjointement avec `limit` pour la pagination.
`dpValue`	String	Non	—	Filtre les points de données renvoyés par valeur. Opérateurs pris en charge : `>`, `<`, `=`, `<=`, `>=`, `!=`. Si la valeur est une chaîne de caractères, seuls les opérateurs `=` et `!=` sont pris en charge.
`preDpValue`	String	Non	—	Filtre les points de données lors de l'analyse, avant l'agrégation. Contrairement à `dpValue` (qui filtre les résultats post-agrégation), `preDpValue` exclut les points de données correspondants de toutes les requêtes et calculs.
`downsample`	String	Non	—	Expression d'échantillonnage. Consultez la section Échantillonnage.
`tags`	Object	Non	—	Paires clé-valeur de tag pour filtrer les données. Entre en conflit avec `filters` ; si les deux sont spécifiés, celui qui apparaît en dernier dans le JSON l'emporte.
`filters`	Array	Non	—	Objets de filtre pour le filtrage basé sur les tags. Entre en conflit avec `tags`. Consultez la section Filtres.
`hint`	Object	Non	—	Indice de requête au niveau de la sous-requête. Remplace l'indice de niveau supérieur pour cette sous-requête.

Paramètres de requête de champ

Chaque objet du tableau fields prend en charge les paramètres suivants :

Parameter	Type	Required	Default	Description
`aggregator`	String	Oui	—	Fonction d'agrégation à appliquer. Définissez-la sur `none` pour ignorer l'agrégation. Si ce paramètre est spécifié dans une requête de champ, il doit l'être dans toutes les requêtes de champ de la même sous-requête.
`field`	String	Oui	—	Nom du champ. Utilisez `*` pour interroger tous les champs de la métrique.
`alias`	String	Non	—	Alias pour le nom du champ renvoyé.
`downsample`	String	Non	—	Expression d'échantillonnage. Toutes les requêtes de champ d'une même sous-requête doivent utiliser le même intervalle.
`rate`	Boolean	Non	`false`	Calcule le taux de croissance pour ce champ.
`dpValue`	String	Non	—	Filtre les valeurs renvoyées pour ce champ. Opérateurs pris en charge : `>`, `<`, `=`, `<=`, `>=`, `!=`. Appliqué indépendamment par champ ; ne s'applique pas entre les champs.
`where`	String	Non	—	Utilisé uniquement lorsque `field` est défini sur `*`. Filtre les champs avant de renvoyer les résultats, en utilisant la même logique que `dpValue`. Exemple : `speed>10`.

Une seule requête peut inclure au maximum 200 valeurs de champ dans l'ensemble des sous-requêtes. Pour compter : additionnez le nombre de valeurs field dans tous les tableaux fields de toutes les sous-requêtes.

Unités d'horodatage

TSDB détermine l'unité d'horodatage à partir de la valeur numérique :

Range	Unit	Corresponding date range
`[4284768, 9999999999]`	Secondes	1970-02-20 à 2286-11-21
`[10000000000, 9999999999999]`	Millisecondes	1970-04-27 à 2286-11-21
En dehors des deux plages	Invalide	—

Ces règles s'appliquent aux endpoints /api/put, /api/mput, /api/query et /api/mquery.

Pour interroger des données à un instant précis, définissez start et end avec la même valeur. Par exemple : "start": 1356998400, "end": 1356998400.

Exemple de requête

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"
        }
      ]
    }
  ]
}

Échantillonnage

L'échantillonnage agrège les données sur des intervalles de temps fixes, réduisant ainsi le nombre de points de données renvoyés. Utilisez-le lorsque vous interrogez de longues périodes où la granularité à la seconde n'est pas nécessaire.

Format de l'expression

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

interval : une valeur numérique telle que 5 ou 60. Utilisez 0all pour agréger tous les points de données de la plage en une seule valeur.

units :

Unit	Meaning
`s`	Secondes
`m`	Minutes
`h`	Heures
`d`	Jours
`n`	Mois
`y`	Années

Ajoutez c pour utiliser l'alignement calendaire (par exemple, 1dc représente la période de 24 heures allant de 00:00 du jour actuel). Sans c, les horodatages sont alignés selon la formule suivante : aligned timestamp = data timestamp − (data timestamp % interval).

Options pour aggregator :

Operator	Description
`avg`	Valeur moyenne
`count`	Nombre de points de données
`first`	Première valeur (horodatage aligné)
`last`	Dernière valeur (horodatage aligné)
`min`	Valeur minimale (horodatage aligné)
`max`	Valeur maximale (horodatage aligné)
`sum`	Somme des valeurs
`zimsum`	Somme des valeurs
`rfirst`	Première valeur avec horodatage d'origine (non aligné)
`rlast`	Dernière valeur avec horodatage d'origine (non aligné)
`rmin`	Valeur minimale avec horodatage d'origine (non aligné)
`rmax`	Valeur maximale avec horodatage d'origine (non aligné)

Les opérateurs rfirst , rlast , rmin et rmax ne peuvent pas être utilisés avec une politique de remplissage.

Extension de la fenêtre temporelle

Après avoir spécifié downsample, TSDB étend automatiquement la plage de requête d'un intervalle de chaque côté. Par exemple, si la plage est [1346846401, 1346846499] et l'intervalle est 5m, la plage de requête réelle devient [1346846101, 1346846799].

Politique de remplissage

Lorsqu'un compartiment temporel ne contient aucun point de données, une politique de remplissage détermine la valeur à signaler pour ce compartiment.

Fill policy	Value
`none`	Aucune valeur n'est remplie. Il s'agit de la valeur par défaut.
`nan`	NaN
`null`	null
`zero`	0
`linear`	Valeur calculée par interpolation linéaire.
`previous`	Valeur précédente.
`near`	Valeur adjacente.
`after`	Valeur suivante.
`fixed`	Valeur fixe spécifiée par l'utilisateur. Consultez la section Politique de remplissage fixe.

Politique de remplissage fixe

Ajoutez une valeur fixe au format en utilisant # :

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

La valeur fixe peut être positive ou négative. Exemples : 1h-sum-fixed#6, 1h-avg-fixed#-8.

Exemples d'échantillonnage

Trois expressions d'échantillonnage valides : 1m-avg, 1h-sum-zero, 1h-sum-near.

Important

Le paramètre downsample est facultatif dans les requêtes de champ. Pour désactiver explicitement l'échantillonnage, définissez-le sur null ou sur une chaîne vide : {"downsample": null} ou {"downsample": ""}. Si une requête de champ d'une sous-requête spécifie downsample, toutes les requêtes de champ de cette sous-requête doivent spécifier le même intervalle.

Agrégateur

Après l'échantillonnage, plusieurs séries chronologiques peuvent partager des horodatages alignés. L'aggregator fusionne ces séries chronologiques en une seule en agrégeant les valeurs à chaque horodatage. Si une seule série chronologique existe, aucune agrégation n'est effectuée.

Important

L'aggregator est obligatoire dans toutes les requêtes de champ. Définissez-le sur none pour ignorer l'agrégation. Si une requête de champ d'une sous-requête spécifie aggregator, toutes les requêtes de champ de cette sous-requête doivent le spécifier. L'agrégation partielle au sein d'une sous-requête n'est pas prise en charge.

Interpolation

Lors de l'agrégation de plusieurs séries chronologiques, si une série n'a aucune valeur à un horodatage aligné alors qu'une autre en a une, TSDB interpole une valeur pour la série manquante. Cela s'applique uniquement lorsqu'aucune politique de remplissage n'est définie.

La méthode d'interpolation dépend de l'agrégateur :

Aggregator	Interpolation method
`avg`	Interpolation linéaire
`count`	Interpole zéro
`min`	Interpolation linéaire
`max`	Interpolation linéaire
`mimmin`	Interpole la valeur maximale
`mimmax`	Interpole la valeur minimale
`none`	Interpole zéro
`sum`	Interpolation linéaire
`zimsum`	Interpole zéro

Opérateur Delta

Lorsque delta est défini sur true, la value de chaque paire clé-valeur dps est remplacée par la différence calculée (Vt − Vt-1).

Important

Si le résultat original contient n paires clé-valeur, le résultat delta contient n-1 paires : la première paire est supprimée car il n'existe aucune valeur précédente pour le calcul. L'opérateur delta s'applique également après l'échantillonnage.

Paramètres deltaOptions

Parameter	Type	Required	Default	Description
`counter`	Boolean	Non	`false`	Traite les valeurs de métrique comme des compteurs monotones croissants ou décroissants. Le serveur ne valide pas la monotonie.
`counterMax`	Integer	Non	—	Différence absolue maximale autorisée. Les différences dépassant ce seuil sont considérées comme anormales et sont soit supprimées, soit réinitialisées à `0`. S'applique uniquement lorsque `counter` est défini sur `true`.
`dropReset`	Boolean	Non	`false`	Requiert `counterMax`. Lorsqu'une différence anormale est détectée, `true` la supprime ; `false` (ou omission) la réinitialise à `0`.

Exemple

{
  "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"
      }
    }
  ]
}

Pagination avec limit et offset

Utilisez limit et offset pour paginer les résultats sur plusieurs séries chronologiques.

limit : nombre maximal de points de données par série chronologique et par page. La valeur 0 signifie qu'il n'y a aucune limite (valeur par défaut).
offset : nombre de points de données à ignorer par série chronologique.

Important

Ni limit ni offset ne peuvent être négatifs. Ces paramètres s'appliquent aux requêtes multivariées paginées et ne peuvent pas être utilisés pour les requêtes à champ unique.

Exemple : Pour renvoyer les points de données classés de 1001 à 1500, définissez limit sur 500 et offset sur 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
    }
  ]
}

Filtres

Les filtres sélectionnent les séries chronologiques à inclure dans une requête en fonction des valeurs de tag. Le paramètre filters entre en conflit avec tags ; si les deux apparaissent dans le JSON, celui qui se trouve à la position ultérieure l'emporte.

Paramètres de l'objet de filtre

Parameter	Type	Required	Default	Description
`type`	String	Oui	—	Type de filtre. Consultez les types de filtre ci-dessous.
`tagk`	String	Oui	—	Clé de tag sur laquelle filtrer.
`filter`	String	Oui	—	Expression de filtre.
`groupBy`	Boolean	Non	`false`	Regroupe les résultats par valeurs de tag.

Types de filtre

Type	Example	Description
`literal_or`	`web01	web02`	Les valeurs de chaque tagv sont agrégées. Ce filtre est sensible à la casse.
`wildcard`	`*.example.com`	Les valeurs de tag contenant le caractère générique spécifié pour chaque tagv sont agrégées. Ce filtre est sensible à la casse.

Vous pouvez également spécifier des filtres à l'aide de la notation abrégée des tags :

tagk = * : regroupe toutes les valeurs de tag pour cette clé et agrège par valeur distincte.
tagk = tagv1|tagv2 : regroupe les valeurs tagv1 ensemble et les valeurs tagv2 ensemble.

Exemple avec filtres

{
  "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"
        }
      ]
    }
  ]
}

Réponse

Une requête réussie renvoie un code HTTP 200 avec un tableau JSON.

Champs de réponse

Field	Description
`metric`	Nom de la métrique.
`columns`	Colonnes renvoyées.
`tags`	Tags dont les valeurs n'ont pas été agrégées (appliqués comme filtres exacts).
`aggregatedTags`	Tags dont les valeurs ont été agrégées sur plusieurs séries chronologiques.
`values`	Tableau de tuples. Chaque tuple correspond à une ligne de données identifiée par `columns`.

Exemple : agrégateur défini sur none

Renvoie un objet de résultat par série chronologique correspondante (aucune agrégation entre les capteurs) :

[
  {
    "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]
    ]
  }
]

Exemple : agrégateur défini sur avg

Renvoie la vitesse moyenne du vent et le niveau agrégés pour tous les capteurs de la ville :

[
  {
    "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]
    ]
  }
]

Indices de requête

Un indice de requête indique à TSDB quels index de tag utiliser (ou ignorer) lors de la résolution des séries chronologiques, ce qui réduit le temps de réponse lorsque l'ensemble des séries chronologiques ciblé par un jeu de tags est un sous-ensemble connu d'un autre.

Important

Nécessite TSDB V2.6.1 ou version ultérieure.

Format

Spécifiez les noms de clés de tag sous hint.tagk avec les valeurs 0 (ignorer l'index) ou 1 (utiliser l'index). Toutes les valeurs d'un même indice doivent être soit toutes 0, soit toutes 1 ; les mélanger renvoie une erreur.

Indice limité à une sous-requête

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

Indice limité à l'ensemble de la requête

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

Erreur : mélange de 0 et 1 dans le même indice

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

Renvoie :

{
  "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=[])"
  }
}

Erreur : valeur d'indice invalide

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

Renvoie :

{
  "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=[])"
  }
}