Consulta de dados com múltiplos valores - : Central de Documentação do Alibaba Cloud

Requisição

Endpoint

Caminho	Método
`/api/mquery`	POST

Parâmetros do corpo da requisição

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`start`	Long	Sim	—	Hora de início. Aceita timestamps Unix em segundos ou milissegundos. Consulte Unidades de timestamp.
`end`	Long	Não	Hora atual do servidor	Hora de término. Aceita timestamps Unix em segundos ou milissegundos. Consulte Unidades de timestamp.
`queries`	Array	Sim	—	Array de objetos de subconsulta. Consulte Parâmetros de subconsulta.
`msResolution`	Boolean	Não	`false`	Quando definido como `true`, retorna timestamps em milissegundos para pontos de dados armazenados em segundos. Não afeta dados armazenados em milissegundos, que sempre retornam timestamps nessa unidade.
`hint`	Object	Não	—	Dica de consulta para limitar o uso de índices. Requer TSDB V2.6.1 ou posterior. Consulte Dicas de consulta.

Parâmetros de subconsulta

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

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`metric`	String	Sim	—	Nome da métrica.
`fields`	Array	Sim	—	Array de objetos de consulta de campo. Consulte Parâmetros de consulta de campo.
`rate`	Boolean	Não	`false`	Calcula a taxa de crescimento entre valores consecutivos: `(Vt − Vt-1) / (t − t-1)`.
`delta`	Boolean	Não	`false`	Calcula a diferença entre valores consecutivos: `Vt − Vt-1`. Consulte Operador delta.
`limit`	Integer	Não	`0`	Número máximo de pontos de dados a retornar por linha do tempo. `0` indica ausência de limite. Aplica-se apenas a consultas multivariadas paginadas, não a consultas de campos individuais.
`offset`	Integer	Não	`0`	Quantidade de pontos de dados a ignorar por linha do tempo. Use em conjunto com `limit` para paginação.
`dpValue`	String	Não	—	Filtra os pontos de dados retornados por valor. Operadores suportados: `>`, `<`, `=`, `<=`, `>=`, `!=`. Se definido como string, apenas `=` e `!=` são suportados.
`preDpValue`	String	Não	—	Filtra pontos de dados durante a varredura, antes da agregação. Diferente de `dpValue` (que filtra resultados pós-agregação), `preDpValue` exclui os pontos correspondentes de todas as consultas e cálculos.
`downsample`	String	Não	—	Expressão de downsampling. Consulte Downsampling.
`tags`	Object	Não	—	Pares chave-valor de tags para filtrar dados. Entra em conflito com `filters`; se ambos forem especificados, prevalece aquele que aparecer posteriormente no JSON.
`filters`	Array	Não	—	Objetos de filtro para filtragem baseada em tags. Entra em conflito com `tags`. Consulte Filtros.
`hint`	Object	Não	—	Dica de consulta no nível da subconsulta. Substitui a dica de nível superior para esta subconsulta específica.

Parâmetros de consulta de campo

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

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`aggregator`	String	Sim	—	Função de agregação a aplicar. Defina como `none` para ignorar a agregação. Se especificado em qualquer consulta de campo, deve ser especificado em todas as consultas de campo dentro da mesma subconsulta.
`field`	String	Sim	—	Nome do campo. Use `*` para consultar todos os campos da métrica.
`alias`	String	Não	—	Alias para o nome do campo retornado.
`downsample`	String	Não	—	Expressão de downsampling. Todas as consultas de campo na mesma subconsulta devem usar o mesmo intervalo.
`rate`	Boolean	Não	`false`	Calcula a taxa de crescimento para este campo.
`dpValue`	String	Não	—	Filtra os valores retornados para este campo. Operadores suportados: `>`, `<`, `=`, `<=`, `>=`, `!=`. Aplicado independentemente por campo, sem efeito cruzado entre campos.
`where`	String	Não	—	Usado apenas quando `field` for `*`. Filtra campos antes de retornar resultados, seguindo a mesma lógica de `dpValue`. Exemplo: `speed>10`.

Uma única consulta pode incluir no máximo 200 valores de campo em todas as subconsultas. Para contar: some a quantidade de valores field em todos os arrays fields de todas as subconsultas.

Unidades de timestamp

O TSDB determina a unidade do timestamp com base no valor numérico:

Intervalo	Unidade	Período correspondente
`[4284768, 9999999999]`	Segundos	1970-02-20 a 2286-11-21
`[10000000000, 9999999999999]`	Milissegundos	1970-04-27 a 2286-11-21
Fora de ambos os intervalos	Inválido	—

Essas regras aplicam-se a /api/put, /api/mput, /api/query e /api/mquery.

Para consultar dados em um único ponto no tempo, defina start e end com o mesmo valor. Por exemplo: "start": 1356998400, "end": 1356998400.

Exemplo de requisição

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

Downsampling

O downsampling agrega dados em intervalos de tempo fixos, reduzindo o número de pontos de dados retornados. Utilize esse recurso ao consultar longos períodos em que a granularidade por segundo é desnecessária.

Formato da expressão

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

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

units:

Unidade	Significado
`s`	Segundos
`m`	Minutos
`h`	Horas
`d`	Dias
`n`	Meses
`y`	Anos

Adicione c para usar alinhamento de calendário (por exemplo, 1dc representa o período de 24 horas a partir das 00:00 do dia atual). Sem o sufixo c, os timestamps são alinhados pela fórmula: aligned timestamp = data timestamp − (data timestamp % interval).

Opções de aggregator:

Operador	Descrição
`avg`	Valor médio
`count`	Quantidade de pontos de dados
`first`	Primeiro valor (timestamp alinhado)
`last`	Último valor (timestamp alinhado)
`min`	Valor mínimo (timestamp alinhado)
`max`	Valor máximo (timestamp alinhado)
`sum`	Soma dos valores
`zimsum`	Soma dos valores
`rfirst`	Primeiro valor com timestamp original (não alinhado)
`rlast`	Último valor com timestamp original (não alinhado)
`rmin`	Valor mínimo com timestamp original (não alinhado)
`rmax`	Valor máximo com timestamp original (não alinhado)

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

Expansão da janela de tempo

Ao especificar downsample, o TSDB estende automaticamente o intervalo da consulta em um período para cada lado. Por exemplo, se o intervalo for [1346846401, 1346846499] e o período for 5m, o intervalo real da consulta torna-se [1346846101, 1346846799].

Política de preenchimento

Quando um intervalo de tempo não contém pontos de dados, a política de preenchimento determina qual valor reportar para esse intervalo.

Política de preenchimento	Valor
`none`	Nenhum valor é preenchido. Este é o valor padrão.
`nan`	NaN
`null`	null
`zero`	0
`linear`	Valor calculado com base em interpolação linear.
`previous`	Valor anterior.
`near`	Valor adjacente.
`after`	Próximo valor.
`fixed`	Valor fixo especificado pelo usuário. Consulte Política de preenchimento fixo.

Política de preenchimento fixo

Anexe um valor fixo ao formato usando #:

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

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

Exemplos de downsampling

Três expressões válidas de downsampling: 1m-avg, 1h-sum-zero, 1h-sum-near.

Importante

O parâmetro downsample é opcional nas consultas de campo. Para desativar explicitamente o downsampling, defina-o como null ou string vazia: {"downsample": null} ou {"downsample": ""}. Se uma consulta de campo em uma subconsulta especificar downsample, todas as consultas de campo dessa subconsulta deverão especificar o mesmo intervalo.

Agregador

Após o downsampling, várias linhas do tempo podem compartilhar timestamps alinhados. O aggregator mescla essas linhas do tempo em uma só, agregando os valores em cada timestamp. Se existir apenas uma linha do tempo, nenhuma agregação é realizada.

Importante

O aggregator é obrigatório em todas as consultas de campo. Defina-o como none para ignorar a agregação. Se qualquer consulta de campo em uma subconsulta especificar aggregator, todas as consultas de campo dessa subconsulta deverão especificá-lo. Não há suporte para agregação parcial dentro de uma subconsulta.

Interpolação

Ao agregar várias linhas do tempo, se uma linha não tiver valor em um timestamp alinhado enquanto outra possuir, o TSDB interpola um valor para a linha ausente. Isso se aplica apenas quando nenhuma política de preenchimento estiver definida.

O método de interpolação depende do agregador:

Agregador	Método de interpolação
`avg`	Interpolação linear
`count`	Interpola zero
`min`	Interpolação linear
`max`	Interpolação linear
`mimmin`	Interpola o valor máximo
`mimmax`	Interpola o valor mínimo
`none`	Interpola zero
`sum`	Interpolação linear
`zimsum`	Interpola zero

Operador delta

Quando delta é definido como true, o value em cada par chave-valor de dps é substituído pelo delta calculado (Vt − Vt-1).

Importante

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 o cálculo. O operador delta também se aplica após o downsampling.

Parâmetros de deltaOptions

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`counter`	Boolean	Não	`false`	Trata os valores da métrica como contadores monotonicamente crescentes ou decrescentes. O servidor não valida a monotonicidade.
`counterMax`	Integer	Não	—	Delta absoluto máximo permitido. Deltas que excedem esse limiar são considerados anormais e são descartados ou redefinidos para `0`. Aplica-se apenas quando `counter` é `true`.
`dropReset`	Boolean	Não	`false`	Requer `counterMax`. Ao detectar um delta anormal, `true` o descarta; `false` (ou omitido) o redefine para `0`.

Exemplo

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

Paginação com limit e offset

Use limit e offset para paginar resultados em várias linhas do tempo.

limit: Máximo de pontos de dados por linha do tempo por página. 0 significa sem limite (padrão).
offset: Quantidade de pontos de dados a ignorar por linha do tempo.

Importante

Nem limit nem offset podem ser negativos. Esses parâmetros aplicam-se a consultas multivariadas paginadas e não podem ser usados em consultas de campo único.

Exemplo: Para retornar pontos de dados classificados de 1001 a 1500, defina limit como 500 e offset como 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

Os filtros selecionam quais linhas do tempo incluir em uma consulta com base nos valores das tags. O parâmetro filters entra em conflito com tags; se ambos aparecerem no JSON, prevalece aquele que estiver na posição posterior.

Parâmetros do objeto de filtro

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`type`	String	Sim	—	Tipo de filtro. Consulte os tipos de filtro abaixo.
`tagk`	String	Sim	—	Chave da tag para filtragem.
`filter`	String	Sim	—	Expressão de filtro.
`groupBy`	Boolean	Não	`false`	Agrupa resultados pelos valores das tags.

Tipos de filtro

Tipo	Exemplo	Descrição
`literal_or`	`web01	web02`	Agrega os valores de cada tagv. Este filtro diferencia maiúsculas de minúsculas.
`wildcard`	`*.example.com`	Agrega os valores de tag que contêm o curinga especificado para cada tagv. Este filtro diferencia maiúsculas de minúsculas.

Também é possível especificar filtros usando a notação abreviada de tag:

tagk = *: Agrupa todos os valores de tag para essa chave e agrega por valor distinto.
tagk = tagv1|tagv2: Agrupa os valores de tagv1 juntos e os valores de tagv2 juntos.

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

Resposta

Uma consulta bem-sucedida retorna HTTP 200 com um array JSON.

Campos da resposta

Campo	Descrição
`metric`	Nome da métrica.
`columns`	Colunas retornadas.
`tags`	Tags cujos valores não foram agregados (aplicadas como filtros exatos).
`aggregatedTags`	Tags cujos valores foram agregados entre as linhas do tempo.
`values`	Array de tuplas. Cada tupla corresponde a uma linha de dados indexada por `columns`.

Exemplo: agregador definido como none

Retorna um objeto de resultado por linha do tempo correspondente (sem agregação 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]
    ]
  }
]

Exemplo: agregador definido como avg

Retorna a velocidade média do vento e o nível agregados entre todos os sensores da cidade:

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

Dicas de consulta

Uma dica de consulta informa ao TSDB quais índices de tags usar (ou ignorar) ao resolver linhas do tempo, reduzindo o tempo de resposta quando o conjunto de linhas do tempo direcionado por um grupo de tags é um subconjunto conhecido de outro.

Importante

Requer TSDB V2.6.1 ou posterior.

Formato

Especifique nomes de chaves de tag em hint.tagk com valores 0 (ignorar índice) ou 1 (usar índice). Todos os valores em uma única dica devem ser exclusivamente 0 ou exclusivamente 1; misturá-los resulta em erro.

Dica com escopo de subconsulta

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

Dica com escopo de toda a consulta

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

Erro: mistura de 0 e 1 na mesma dica

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

Retorno:

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

Erro: valor de dica inválido

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

Retorno:

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