:Kueri data multi-nilai

Permintaan

Titik Akhir

Parameter body permintaan

Parameter subkueri

Setiap objek dalam array queries mendukung parameter berikut:

Parameter kueri bidang

Setiap objek dalam array fields mendukung parameter berikut:

Satu kueri dapat mencakup paling banyak 200 nilai bidang di seluruh subkueri. Untuk menghitungnya, jumlahkan jumlah nilai field di seluruh array fields di semua subkueri.

Satuan timestamp

TSDB menentukan satuan timestamp berdasarkan nilai numerik:

Aturan ini berlaku untuk /api/put, /api/mput, /api/query, dan /api/mquery.

Untuk mengkueri data pada satu titik waktu tertentu, atur start dan end ke nilai yang sama. Contohnya: "start": 1356998400, "end": 1356998400.

Contoh permintaan

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

Downsampling mengagregasi data dalam interval waktu tetap sehingga mengurangi jumlah titik data yang dikembalikan. Fitur ini berguna saat mengkueri rentang waktu panjang di mana granularitas per detik tidak diperlukan.

Format ekspresi

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

`interval`: Nilai numerik seperti 5 atau 60. Gunakan 0all untuk mengagregasi semua titik data dalam rentang menjadi satu nilai.

`units`:

Tambahkan c untuk menggunakan penyelarasan kalender (misalnya, 1dc merepresentasikan periode 24 jam mulai pukul 00:00 hari tersebut). Tanpa c, timestamp diselaraskan menggunakan: timestamp selaras = timestamp data − (timestamp data % interval).

Opsi `aggregator`:

Operator rfirst, rlast, rmin, dan rmax tidak dapat digunakan bersama kebijakan pengisian (fill policy).

Perluasan jendela waktu

Setelah menentukan downsample, TSDB secara otomatis memperluas rentang kueri sebesar satu interval di setiap sisi. Misalnya, jika rentangnya adalah [1346846401, 1346846499] dan intervalnya adalah 5m, maka rentang kueri aktual menjadi [1346846101, 1346846799].

Kebijakan Pengisian

Ketika bucket waktu tidak berisi titik data, kebijakan pengisian menentukan nilai apa yang dilaporkan untuk bucket tersebut.

Kebijakan pengisian tetap

Tambahkan nilai tetap ke format menggunakan #:

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

Nilai tetap dapat bernilai positif atau negatif. Contoh: 1h-sum-fixed#6, 1h-avg-fixed#-8.

Contoh pengambilan sampel turun

Tiga contoh ekspresi downsampling yang valid: 1m-avg, 1h-sum-zero, 1h-sum-near.

Agregator

Setelah downsampling, beberapa timeline mungkin memiliki timestamp yang selaras. aggregator menggabungkan timeline tersebut menjadi satu dengan mengagregasi nilai pada setiap timestamp. Jika hanya ada satu timeline, agregasi tidak dilakukan.

Interpolasi

Saat mengagregasi beberapa timeline, jika suatu timeline tidak memiliki nilai pada timestamp yang selaras sedangkan timeline lain memiliki nilai tersebut, TSDB melakukan interpolasi nilai untuk timeline yang hilang. Hal ini hanya berlaku jika tidak ada kebijakan pengisian yang ditetapkan.

Metode interpolasi bergantung pada aggregator:

Operator delta

Ketika delta diatur ke true, value dalam setiap pasangan kunci-nilai dps diganti dengan delta yang dihitung (Vt − Vt-1).

Parameter `deltaOptions`

Contoh

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

Paginasi dengan limit dan offset

Gunakan limit dan offset untuk memaginasi hasil di beberapa timeline.

• limit: Maksimum titik data per timeline per halaman. 0 berarti tanpa batas (bawaan).

• offset: Jumlah titik data yang dilewati per timeline.

Contoh: Untuk mengembalikan titik data peringkat 1001 hingga 1500, atur limit ke 500 dan offset ke 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
    }
  ]
}

Filter

Filter memilih timeline mana yang akan dimasukkan dalam kueri berdasarkan nilai tag. Parameter filters bertentangan dengan tags—jika keduanya muncul dalam JSON, yang berada di posisi belakang yang berlaku.

Menyaring parameter objek

Jenis filter

Anda juga dapat menentukan filter menggunakan singkatan tag:

• tagk = *: Mengelompokkan semua nilai tag untuk kunci tersebut dan mengagregasi per nilai unik.

• tagk = tagv1|tagv2: Mengelompokkan nilai tagv1 bersama dan nilai tagv2 bersama.

Contoh dengan filter

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

Tanggapan

Kueri yang berhasil mengembalikan HTTP 200 dengan array JSON.

Bidang tanggapan

Contoh: aggregator diatur ke `none`

Mengembalikan satu objek hasil per timeline yang cocok (tanpa agregasi lintas sensor):

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

Contoh: aggregator diatur ke `avg`

Mengembalikan kecepatan angin rata-rata dan level yang diagregasi lintas semua sensor di kota tersebut:

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

Petunjuk kueri

Petunjuk kueri memberi tahu TSDB indeks tag mana yang harus digunakan (atau dilewati) saat menyelesaikan timeline, sehingga mengurangi waktu respons ketika kumpulan timeline yang ditargetkan oleh satu set tag merupakan subset yang diketahui dari yang lain.

Format

Tentukan nama kunci tag di bawah hint.tagk dengan nilai 0 (lewati indeks) atau 1 (gunakan indeks). Semua nilai dalam satu petunjuk harus semuanya 0 atau semuanya 1—mencampurnya akan menghasilkan error.

Petunjuk cakupan subkueri

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

Petunjuk cakupan seluruh kueri

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

Error: mencampur 0 dan 1 dalam petunjuk yang sama

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

Mengembalikan:

{
  "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: nilai petunjuk tidak valid

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

Mengembalikan:

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