Todos os produtos
Search
Central de documentação

Time Series Database:Consultar dados

Última atualização: Jun 27, 2026

Consulta pontos de dados de uma ou mais séries temporais em um intervalo de tempo especificado. Envie uma requisição POST para /api/query com um corpo JSON que defina o intervalo de tempo e uma ou mais subconsultas.

Sintaxe da requisição

POST /api/query

Parâmetros da requisição

Parâmetro

Tipo

Obrigatório

Padrão

Descrição

start

Long

Sim

Início do intervalo de tempo. Unidade: segundos ou milissegundos. O TSDB determina a unidade com base no valor numérico. Consulte Unidades de timestamp.

end

Long

Não

Hora atual do servidor

Fim do intervalo de tempo. Unidade: segundos ou milissegundos. O padrão é a hora atual no servidor TSDB. Consulte Unidades de timestamp.

queries

Array

Sim

Array de subconsultas. Consulte Parâmetros de subconsulta.

msResolution

Boolean

Não

false

Define se os timestamps devem ser retornados em milissegundos. Aplica-se apenas quando os pontos de dados consultados usam timestamps com precisão de segundos. Se true, todos os timestamps na resposta são convertidos para milissegundos. Se false, a unidade original é preservada. Pontos de dados armazenados com timestamps em milissegundos sempre são retornados em milissegundos, independentemente desta configuração.

hint

Map

Não

Dica de consulta para reduzir o tempo de resposta. Consulte Parâmetro: hint.

Unidades de timestamp

O TSDB determina a unidade do timestamp a partir do valor numérico:

Intervalo

Unidade

Período de datas

[4294968, 4294967295]

Segundos

1970-02-20 01:02:48 – 2106-02-07 14:28:15

[4294967296, 9999999999999]

Milissegundos

1970-02-20 01:02:47.296 – 2286-11-21 01:46:39.999

(-∞, 4294968) ou (9999999999999, +∞)

Inválido

Estas regras aplicam-se tanto a /api/put (escrita) quanto a /api/query (consulta).

Para consultar pontos de dados em um único momento, defina start e end com o mesmo valor — por exemplo, 1356998400.

Parâmetros de subconsulta

Cada objeto no array queries aceita os seguintes parâmetros:

Parâmetro

Tipo

Obrigatório

Padrão

Descrição

aggregator

String

Sim

Função de agregação. Consulte Parâmetro: aggregator. Exemplo: sum.

metric

String

Sim

Nome da métrica. Exemplo: sys.cpu0.

rate

Boolean

Não

false

Define se deve calcular a taxa de variação entre valores consecutivos. Fórmula: (Vt − Vt-1) / (t − t-1).

delta

Boolean

Não

false

Define se deve calcular o delta entre valores consecutivos. Fórmula: Vt − Vt-1. Consulte Parâmetro: delta.

limit

Integer

Não

0

Número máximo de pontos de dados a retornar por série temporal por página. 0 significa sem limite.

offset

Integer

Não

0

Quantidade de pontos de dados a pular por série temporal por página. 0 indica que nenhum ponto de dado será ignorado.

dpValue

String

Não

Filtra os pontos de dados retornados por valor. Operadores suportados: >, <, =, <=, >=, !=. Se o valor for uma string, apenas = e != são suportados. Aplicado após a agregação.

preDpValue

String

Não

Filtra pontos de dados brutos durante a varredura, antes da agregação. Usa os mesmos operadores de dpValue. Pontos de dados reprovados neste filtro são excluídos de todos os cálculos.

downsample

String

Não

Configuração de downsample. Consulte Parâmetro: downsample. Exemplo: 60m-avg.

tags

Map

Não

Condições de filtro baseadas em tags. Mutuamente exclusivo com filters. Se ambos forem especificados, aquele que aparecer posteriormente no JSON terá efeito.

filters

List

Não

Condições de filtro no formato JSON. Mutuamente exclusivo com tags. Se ambos forem especificados, aquele que aparecer posteriormente no JSON terá efeito. Consulte Parâmetro: filters.

hint

Map

Não

Dica de consulta no nível da subconsulta. Consulte Parâmetro: hint.

forecasting

String

Não

Previsão de pontos de dados futuros usando treinamento de IA. Consulte Parâmetro: forecasting.

abnormaldetect

String

Não

Detecção de anomalias em uma série temporal usando treinamento de IA. Consulte Parâmetro: abnormaldetect.

Uma única requisição suporta no máximo 200 subconsultas.
Caso tags e filters sejam especificados simultaneamente, o parâmetro que aparecer posteriormente no JSON prevalecerá.

Exemplo de requisição

POST /api/query
{
  "start": 1356998400,
  "end": 1356998460,
  "queries": [
    {
      "aggregator": "sum",
      "metric": "sys.cpu.0"
    },
    {
      "aggregator": "sum",
      "metric": "sys.cpu.1"
    }
  ]
}

Elementos da resposta

Uma requisição bem-sucedida retorna HTTP 200 com um array JSON. Cada elemento corresponde ao resultado de uma subconsulta.

Parâmetro

Descrição

metric

Nome da métrica.

tags

Tags cujos valores não foram agregados.

aggregateTags

Tags cujos valores foram agregados.

dps

Pontos de dados como pares timestamp-valor.

Exemplo de resposta

[
  {
    "metric": "tsd.hbase.puts",
    "tags": {"appName": "hitsdb"},
    "aggregateTags": ["host"],
    "dps": {
      "1365966001": 25595461080,
      "1365966061": 25595542522,
      "1365966062": 25595543979,
      "1365973801": 25717417859
    }
  }
]

Parâmetro: limit e offset

Use limit e offset em conjunto para paginar resultados dentro de uma subconsulta.

  • limit: número máximo de pontos de dados a retornar por série temporal. O padrão 0 significa sem limite.

  • offset: quantidade de pontos de dados a pular por série temporal. O padrão 0 indica que nenhum ponto de dado será ignorado.

Importante

Nem limit nem offset podem ser definidos com um número negativo.

Para recuperar pontos de dados classificados de 1001 a 1500, defina limit como 500 e offset como 1000:

{
  "start": 1346046400,
  "end": 1347056500,
  "queries": [
    {
      "aggregator": "avg",
      "downsample": "2s-sum",
      "metric": "sys.cpu.0",
      "limit": "500",
      "offset": "1000",
      "tags": {
        "host": "localhost",
        "appName": "hitsdb"
      }
    }
  ]
}

Parâmetro: dpValue

Filtra pontos de dados por valor após a agregação. Operadores suportados: >, <, =, <=, >=, !=.

Importante

Quando o valor do filtro for uma string, apenas = e != são suportados.

Exemplo

{
  "start": 1346046400,
  "end": 1347056500,
  "queries": [
    {
      "aggregator": "avg",
      "downsample": "2s-sum",
      "metric": "sys.cpu.0",
      "dpValue": ">=500",
      "tags": {
        "host": "localhost",
        "appName": "hitsdb"
      }
    }
  ]
}

Parâmetro: delta

Quando delta é definido como true, cada valor na resposta dps representa o delta calculado entre pontos de dados consecutivos. Se o resultado original contiver n pares chave-valor, o resultado delta conterá n−1 pares — o primeiro par é descartado porque não existe valor anterior para cálculo. O operador delta também se aplica aos valores após o downsample.

deltaOptions

Configure deltaOptions na subconsulta para controlar como os deltas são calculados.

Parâmetro

Tipo

Obrigatório

Padrão

Descrição

counter

Boolean

Não

false

Trata os valores da métrica como contagens cumulativas monotonicamente crescentes ou decrescentes (semelhante a um contador). O servidor não valida os valores da métrica.

counterMax

Integer

Não

Limiar para valores delta quando counter é true. Se o delta absoluto exceder este limiar, o delta é considerado anormal. Quando não definido, nenhum limiar é aplicado.

dropReset

Boolean

Não

false

Controla o comportamento para deltas anormais quando counterMax está definido. Se true, deltas anormais são descartados. Se false, deltas anormais são redefinidos para 0.

Exemplo

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

Parâmetro: downsample

O downsample agrega dados em um intervalo de tempo especificado, sendo útil ao consultar dados em longos períodos. O intervalo de tempo é dividido em janelas do tamanho especificado, e cada timestamp retornado marca o início de uma janela.

Formato

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

Quando downsample é especificado, o TSDB estende automaticamente o intervalo de consulta em um intervalo para ambos os lados. Por exemplo, um intervalo de [1346846401, 1346846499] com um intervalo de 5 minutos torna-se [1346846101, 1346846799].

Campos

interval

Valor numérico como 5 ou 60. Use 0all para agregar todos os pontos de dados do intervalo em um único valor.

units

Valor

Unidade

s

Segundos

m

Minutos

h

Horas

d

Dias

n

Meses

y

Anos

Por padrão, os timestamps são alinhados usando truncamento modular: Timestamp alinhado = Timestamp dos dados − (Timestamp dos dados % Intervalo de tempo) .
Para alinhar por intervalo de calendário (por exemplo, das 00:00 às 00:00 do dia seguinte), adicione c à unidade: 1dc .

aggregator

Operador

Descrição

avg

Valor médio

count

Número de pontos de dados

first

Primeiro valor

last

Último valor

min

Valor mínimo

max

Valor máximo

median

Valor mediano

sum

Soma dos valores

zimsum

Soma dos valores (interpolação zero)

rfirst

Igual a first, mas retorna o timestamp original em vez do timestamp alinhado

rlast

Igual a last, mas retorna o timestamp original em vez do timestamp alinhado

rmin

Igual a min, mas retorna o timestamp original em vez do timestamp alinhado

rmax

Igual a max, mas retorna o timestamp original em vez do timestamp alinhado

Os operadores rfirst , rlast , rmin e rmax não podem ser usados com uma política de preenchimento na mesma expressão de downsample.

Políticas de preenchimento

As políticas de preenchimento definem como o TSDB preenche valores ausentes nos resultados do downsample. Quando não há dados em uma janela de tempo, o TSDB aplica a política de preenchimento para gerar um valor.

Política de preenchimento

Preenche valores ausentes com

none

Sem preenchimento (padrão)

nan

null

null

null

zero

0

linear

Valor calculado por interpolação linear

previous

Valor anterior

near

Valor adjacente mais próximo

after

Próximo valor

fixed

Valor fixo especificado pelo usuário

Política de preenchimento fixo

Para preencher valores ausentes com um número fixo, use o formato:

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

O valor fixo pode ser positivo ou negativo. Exemplos: 1h-sum-fixed#6, 1h-avg-fixed#-8.

Exemplos de downsample

1m-avg, 1h-sum-zero, 1h-sum-near

Importante

downsample é opcional. Para desativar explicitamente o downsample, defina-o como null ou uma string vazia: {"downsample": null} ou {"downsample": ""}.

Parâmetro: aggregator

Após o downsample, o TSDB mescla várias linhas do tempo em uma só, agregando valores em cada timestamp alinhado. A agregação é ignorada quando apenas uma linha do tempo corresponde à consulta.

Interpolação

Ao agregar múltiplas linhas do tempo, uma linha sem valor em um determinado timestamp recebe um valor interpolado — desde que nenhuma política de preenchimento seja especificada e pelo menos outra linha tenha um valor nesse timestamp.

Por exemplo, ao mesclar duas linhas do tempo com {"downsample": "10s-avg", "aggregator": "sum"}:

  • A Linha do tempo 1 tem valores em t+0, t+10, t+20, t+30.

  • A Linha do tempo 2 tem valores em t+0, t+20, t+30.

Antes da agregação, o TSDB interpola um valor para a Linha do tempo 2 em t+10. O método de interpolação depende do agregador:

Operador

Descrição

Método de interpolação

avg

Valor médio

Interpolação linear

count

Número de pontos de dados

0 interpolado

mimmin

Valor mínimo

Valor máximo interpolado

mimmax

Valor máximo

Valor mínimo interpolado

min

Valor mínimo

Interpolação linear

max

Valor máximo

Interpolação linear

none

Ignora agregação

0 interpolado

sum

Soma dos valores

Interpolação linear

zimsum

Soma dos valores

0 interpolado

Parâmetro: filters

O parâmetro filters aceita uma lista de objetos de filtro JSON para filtragem baseada em tags. É mutuamente exclusivo com o parâmetro tags.

Parâmetros do objeto de filtro

Parâmetro

Tipo

Obrigatório

Padrão

Descrição

type

String

Sim

Tipo de filtro. Consulte Tipos de filtro. Exemplo: literal_or.

tagk

String

Sim

Chave da tag para filtrar. Exemplo: host.

filter

String

Sim

Expressão de filtro. Exemplo: `web01

web02`.

groupBy

Boolean

Não

false

Define se deve executar uma operação GROUP BY nos valores de tag correspondentes.

Também é possível usar expressões abreviadas de tags diretamente na subconsulta:

  • tagk = *: executa um GROUP BY em todos os valores da chave da tag.

  • tagk = tagv1|tagv2: agrega valores de tagv1 e valores de tagv2 separadamente.

Tipos de filtro

Tipo de filtro

Exemplo

Descrição

literal_or

`web01

web02`

Corresponde a valores exatos de tag separados por `

`. Sensível a maiúsculas e minúsculas.

wildcard

*.example.com

Corresponde a valores de tag usando um padrão curinga. Sensível a maiúsculas e minúsculas.

Exemplo sem filtros

{
  "start": 1356998400,
  "end": 1356998460,
  "queries": [
    {
      "aggregator": "sum",
      "metric": "sys.cpu.0",
      "rate": "true",
      "tags": {
        "host": "*",
        "dc": "lga"
      }
    }
  ]
}

Exemplo com filtros

{
  "start": 1356998400,
  "end": 1356998460,
  "queries": [
    {
      "aggregator": "sum",
      "metric": "sys.cpu.0",
      "rate": "true",
      "filters": [
        {
          "type": "wildcard",
          "tagk": "host",
          "filter": "*",
          "groupBy": true
        },
        {
          "type": "literal_or",
          "tagk": "dc",
          "filter": "lga|lga1|lga2",
          "groupBy": false
        }
      ]
    }
  ]
}

Parâmetro: hint

Uma dica de consulta reduz o tempo de resposta controlando quais índices de chave de tag o TSDB usa durante a execução da consulta. Por exemplo, se as séries temporais correspondentes ao conjunto de tags B forem um subconjunto daquelas correspondentes ao conjunto de tags A, você pode orientar o TSDB a usar apenas o índice de B — evitando a sobrecarga de leitura de A.

O parâmetro hint pode ser definido no nível superior (aplica-se a toda a consulta) ou dentro de uma subconsulta (aplica-se apenas a essa subconsulta).

A versão atual do TSDB suporta apenas o parâmetro tagk em uma dica.

Formato

No mapa tagk, defina cada chave de tag como 1 para usar seu índice, ou 0 para ignorá-lo. Todos os valores devem ser 0 ou 1 — misturar ambos na mesma dica causa um erro.

Requisito de versão: TSDB V2.6.1 e posterior.

Dica aplicada a uma subconsulta

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

Dica aplicada a toda a consulta

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

Casos de erro

Valores 0 e 1 misturados

A seguinte requisição causa um erro porque dc é 1 e host é 0:

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

Resposta de erro:

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

Valor diferente de 0 ou 1

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

Resposta de erro:

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

Parâmetro: forecasting

Usa treinamento de IA em dados históricos de séries temporais para prever pontos de dados futuros. O TSDB treina com os dados existentes para identificar tendências e ciclos, projetando os valores adiante.

Formato

<AlgorithmName>-<ForecastPointCount>[-<ForecastPolicy>]

Algoritmos suportados

  • arima — AutoRegressive Integrated Moving Average (ARIMA). O ForecastPolicy para ARIMA possui dois campos:

    • delta: ordem de diferenciação. Padrão: 1. Aumente para reduzir flutuações nos dados.

    • seasonality: duração do ciclo em número de pontos de dados. Padrão: 1. Defina para corresponder ao ciclo natural dos dados (por exemplo, 10 se os dados flutuarem a cada 10 pontos).

  • holtwinters — Suavização exponencial de Holt-Winters. O ForecastPolicy para Holt-Winters possui um campo:

    • seasonality: igual ao ARIMA. Padrão: 1.

Exemplos: arima-1, arima-48-1-48, holtwinters-1-1

Exemplo

Dados existentes na série:

[
  {
    "metric": "sys.cpu.nice",
    "tags": {"dc": "lga", "host": "web00"},
    "aggregateTags": [],
    "dps": {
      "1346837400": 1,
      "1346837401": 2,
      "1346837402": 3,
      "1346837403": 4,
      "1346837404": 5,
      "1346837405": 6,
      "1346837406": 7,
      "1346837407": 8,
      "1346837408": 9,
      "1346837409": 10,
      "1346837410": 11,
      "1346837411": 12
    }
  }
]

Consulta:

{
  "start": 1346837400,
  "end": 1346847400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "forecasting": "arima-1"
    }
  ]
}

Resultado da previsão (um ponto de dado adicional é anexado):

[
  {
    "metric": "sys.cpu.nice",
    "tags": {"dc": "lga", "host": "web00"},
    "aggregateTags": [],
    "dps": {
      "1346837400": 1,
      "1346837401": 2,
      "1346837402": 3,
      "1346837403": 4,
      "1346837404": 5,
      "1346837405": 6,
      "1346837406": 7,
      "1346837407": 8,
      "1346837408": 9,
      "1346837409": 10,
      "1346837410": 11,
      "1346837411": 12,
      "1346837412": 13
    }
  }
]

Parâmetro: abnormaldetect

Utiliza o algoritmo STL (Decomposição Sazonal-Tendência usando Loess) para detectar anomalias em uma série temporal. O TSDB treina com os dados existentes para identificar padrões e sinaliza pontos de dados que se desviam significativamente do intervalo esperado.

Formato

<AlgorithmName>[-<Sigma>-<NP>-<NS>-<NT>-<NL>]

Apenas o algoritmo STL é suportado. Se você não estiver familiarizado com o ajuste de parâmetros STL, use os valores padrão omitindo os campos de parâmetros.

Parâmetros

Parâmetro

Descrição

AlgorithmName

Nome do algoritmo. Use stl.

Sigma

Limiar de anomalia. Um ponto de dado é sinalizado como anormal se a diferença absoluta entre seu valor e a média da série exceder Sigma × desvio padrão. Valor típico: 3.0.

NP

Número de pontos de dados por ciclo.

NS

Parâmetro de suavização sazonal.

NT

Parâmetro de suavização de tendência.

NL

Parâmetro de suavização do filtro passa-baixa.

Exemplos

"abnormaldetect": "stl"
"abnormaldetect": "stl-5-5-7-0-0"

Exemplo de consulta

{
  "start": 1346836400,
  "end": 1346946400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "abnormaldetect": "stl-5-5-7-0-0",
      "filters": [
        {
          "type": "literal_or",
          "tagk": "dc",
          "filter": "lga",
          "groupBy": false
        },
        {
          "type": "literal_or",
          "tagk": "host",
          "filter": "web00",
          "groupBy": false
        }
      ]
    }
  ]
}

Saída da detecção de anomalias

Cada valor em dps é um array no formato:

[srcValue, upperValue, lowerValue, predictValue, isAbnormal]

Campo

Descrição

srcValue

Valor original do ponto de dado.

upperValue

Limite superior do intervalo esperado.

lowerValue

Limite inferior do intervalo esperado.

predictValue

Valor previsto pelo algoritmo STL.

isAbnormal

0 — normal. 1 — anormal.

Exemplo de saída

[
  {
    "metric": "sys.cpu.nice",
    "tags": {"dc": "lga", "host": "web00"},
    "aggregateTags": [],
    "dps": {
      "1346837400": [1, 1.0000000000000049, 0.9999999999999973, 1.0000000000000013, 0],
      "1346837401": [2, 2.0000000000000036, 1.9999999999999958, 1.9999999999999998, 0],
      "1346837402": [3, 3.0000000000000036, 2.9999999999999956, 3, 0],
      "1346837403": [4, 4.0000000000000036, 3.9999999999999956, 4, 1],
      "1346837404": [5, 5.0000000000000036, 4.9999999999999964, 5, 0],
      "1346837405": [6, 6.000000000000002, 5.999999999999995, 5.999999999999998, 0],
      "1346837406": [7, 7.0000000000000036, 6.9999999999999964, 7, 1],
      "1346837407": [8, 8.000000000000004, 7.9999999999999964, 8, 0],
      "1346837408": [9, 9.000000000000004, 8.999999999999996, 9, 0],
      "1346837409": [10, 10.000000000000004, 9.999999999999996, 10, 0],
      "1346837410": [11, 11.000000000000005, 10.999999999999998, 11.000000000000002, 0],
      "1346837411": [12, 12.000000000000004, 11.999999999999996, 12, 0]
    }
  }
]