sintaks kueri Azure Time Series Insights Gen1

Artikel
07/19/2023

Perhatian

Ini adalah artikel Gen1.

Artikel ini menguraikan format dan sintaks permintaan kueri untuk AZURE TIME SERIES INSIGHTS Gen1 Query API.

Ringkasan

Penting

Permintaan kueri harus dalam format JSON.
Payload permintaan HTTP yang dibuat ke API Kueri harus sesuai dengan format yang ditentukan dalam artikel ini.

Bahasa dibagi menjadi elemen berikut:

Ekspresi skalar, yang menghasilkan nilai skalar. Ekspresi skalar mencakup ekspresi string predikat, ekspresi perbandingan, dan ekspresi aritmatika.
Fungsi skalar, yang mengembalikan nilai skalar.
Ekspresi agregat, yang digunakan untuk mempartisi koleksi peristiwa dan pengukuran komputasi atas partisi.
Klausa, yang membentuk komponen konstituen kueri JSON atau bagian dari ekspresi.

Model data

API Kueri Azure Time Series Insights Gen1 beroperasi pada data yang disimpan sebagai peristiwa individual dalam lingkungan. Setiap peristiwa adalah sekumpulan nama properti dan pasangan nilai .

Properti peristiwa

Properti peristiwa dapat berupa salah satu jenis primitif berikut: Bool, DateTime, Double, atau String. Semua jenis primitif dapat diubah ke null.

Catatan

Format sumber peristiwa yang dikustomisasi dapat mendukung sekumpulan jenis nilai yang lebih besar. Azure Time Series Insights Gen1 menyimpulkan jenis primitif terdekat dan kemudian mentransmisikan jenis yang disesuaikan saat masuk.

Semua peristiwa memiliki properti bawaan berikut dengan nama dan jenis yang telah ditentukan sebelumnya:

Nama properti	Jenis properti	Definisi
$ts	DateTime	Tanda waktu kejadian
$esn	String	Nama sumber kejadian

Tanda waktu kejadian

Secara default, nilai tanda waktu peristiwa disediakan oleh sumber peristiwa. Misalnya, peristiwa yang berasal dari hub IoT akan memiliki waktu antrean sebagai tanda waktu.

Pelanggan dapat mengubah perilaku ini dengan mengonfigurasi properti peristiwa lain sebagai gantinya. Properti tanda waktu kustom dapat ditentukan di hub peristiwa dan hub IoT.
Nama sumber kejadian

Nama sumber kejadian adalah nama yang ditampilkan untuk sumber peristiwa tempat Azure Time Series Insights Gen1 menerima peristiwa tersebut. Nama sumber peristiwa dikaitkan dengan peristiwa tertentu pada waktu masuk.
Penting
- Nama sumber peristiwa tetap tidak berubah selama masa pakai peristiwa.
- Jika nama sumber peristiwa dimodifikasi, peristiwa yang ada membawa nama sumber peristiwa lama. Peristiwa baru akan membawa nama sumber peristiwa baru.

Jenis kejadian

Properti peristiwa kustom diidentifikasi secara unik dan direferensikan dalam ekspresi kueri menurut nama dan jenis. Peristiwa dapat memiliki lebih dari satu properti dengan nama yang sama dan jenis yang berbeda. Properti dengan nama yang sama tetapi jenis yang berbeda mungkin dihasilkan dari pemisahan jenis ingress.

Nilai properti peristiwa jenis String dapat disimpan sebagai properti dengan jenis yang berbeda dalam kasus berikut:

Jika nilai String adalah nilai Ganda yang valid, nilai tersebut disimpan sebagai Ganda dan String.
Jika nilai String adalah nilai DateTime yang valid, nilai tersebut disimpan sebagai DateTime saja.

API Kueri mengonversi literal String kosong ("") ke null dalam output.

Azure Time Series Insights Gen1 memiliki dukungan terbatas untuk nilai berikut dalam jenis Ganda: Double.NaN, Double.PositiveInfinity, dan Double.NegativeInfinity. Nilai-nilai ini dikonversi menjadi null selama ingress, tetapi jika evaluasi kueri menghasilkan salah satu nilai ini, nilai dievaluasi dan diserialisasikan sebagai String sebagai respons.

Anda dapat meneruskan nilai-nilai ini sebagai String untuk ingress, jadi dalam ekspresi kueri nilai-nilai ini juga harus diteruskan sebagai String.

Skema peristiwa menjelaskan properti peristiwa. Skema peristiwa berisi nama sumber peristiwa dan sekumpulan properti yang diurutkan untuk peristiwa tersebut. Peristiwa yang berbeda dapat memiliki skema yang berbeda atau berbagi skema yang sama.

Ekspresi skalar

Ekspresi skalar menghasilkan nilai skalar. Ekspresi skalar dibagi menjadi jenis berikut:

Ekspresi konstanta
Ekspresi referensi properti
Ekspresi perbandingan
Ekspresi aritmetika
Ekspresi string predikat

Ekspresi konstanta

Anda mewakili ekspresi konstanta dengan menggunakan harfiah berikut untuk setiap jenis primitif:

Jenis primitif	Representasi JSON	Contoh JSON	Catatan
Bool	Sebagai jenis JSON Boolean	`true`, `false`
DateTime	Sebagai objek berlapis dengan properti dateTime tunggal dalam format `yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFK`ISO 8601 .	`{"dateTime":"2016-08-01T00:00:00.000Z"}`
Double	Nomor JSON dilemparkan ke rentang Ganda.	`1.23e45`, `123`	Luapan ganda akan menghasilkan kesalahan.
String	Jenis string JSON	`"abc"`
TimeSpan	Sebagai objek berlapis dengan properti timeSpan tunggal dalam format ISO 8601 : `P[n]Y[n]M[n]DT[n]H[n]M[n]S`.	`{"timeSpan":"P1Y2M3DT4M5.67S"}`

Jenis primitif yang dapat diubah ke null

Jenis data primitif dapat diubah ke null. null nilai untuk jenis primitif dinyatakan dalam JSON sebagai berikut:

{ "string": null }

{ "double": null }

{ "bool": null }

{ "dateTime": null }

{ "timeSpan": null }

Ekspresi referensi properti

Anda menggunakan ekspresi referensi properti untuk mengakses nilai properti non-bawaan dari suatu peristiwa. Properti non-bawaan mencakup properti yang disesuaikan di luar properti default yang secara otomatis terkandung dalam skema peristiwa.

Jenis hasil ekspresi referensi properti adalah jenis primitif properti. Properti dalam skema peristiwa diidentifikasi secara unik berdasarkan nama dan jenis, dan ekspresi referensi mengharuskan keduanya ditentukan.

Contoh JSON:

{
   "property": "p1",
   "type": "Bool"
}

{
   "property": "p1",
   "type": "DateTime"
}

{
   "property": "p1",
   "type": "Double"
}

{
   "property": "p1",
   "type": "String"
}

{
   "property": "p1",
   "type": "TimeSpan"
}

Ekspresi referensi properti bawaan digunakan untuk mengakses properti bawaan suatu peristiwa. Properti bawaan hanya properti yang secara otomatis ditentukan dalam skema peristiwa.

Jenis hasil ekspresi referensi properti bawaan adalah jenis primitif properti. Properti bawaan dirujuk berdasarkan nama saja; oleh karena itu, tidak ada jenis yang diperlukan dalam ekspresi referensi:

{ "builtInProperty": "$esn" }

Ekspresi perbandingan

Ekspresi perbandingan Boolean berikut didukung:

Nama properti di JSON	Deskripsi
eq	Equal
in	Dalam (sama dengan apa pun)
Frase	Berisi frasa
startsWith	Dimulai dengan
endsWith	Diakhir dengan frasa
Regex	Cocok dengan ekspresi reguler
lt	Kurang dari
Lte	Kurang dari atau sama dengan
gt	Lebih besar dari
Gte	Lebih besar dari atau sama dengan

Penting

Semua ekspresi perbandingan mengambil jenis primitif argumen tangan kiri dan kanan dan mengembalikan nilai Boolean yang mewakili hasil perbandingan.
Kedua jenis argumen sebelah kiri dan kanan dalam perbandingan harus cocok.
Semua jenis secara implisit hanya dilemparkan ke diri mereka sendiri, dan cast eksplisit tidak didukung.

{
  "eq": {
    "left": {
      "property": "p1",
      "type": "String"
     },
     "right": "abc"
  }
}

Contoh JSON:

{
   "startsWith": {
     "left": {
       "property": "p1",
       "type": "String"
      },
      "right": "abc"
   }
}

{
   "startsWith": {
     "left": {
       "property": "p1",
       "type": "String"
     },
     "right": "",
     "stringComparison": "Ordinal"
   }
}

{
   "endsWith": {
     "left": {
       "property": "p1",
       "type": "String"
     },
     "right": {
       "property": "p2",
       "type": "String"
     },
     "stringComparison": "Ordinal"
   }
}

Tabel berikut ini memperlihatkan jenis argumen yang didukung untuk setiap ekspresi perbandingan:

Jenis Argumen	Operasi perbandingan yang didukung
Bool	eq, dalam
DateTime	eq, in, lt, lte, gt, gte
Double	eq, in, lt, lte, gt, gte
String	eq, dalam, frasa, startsWith, endsWith, regex
TimeSpan	eq, in, lt, lte, gt, gte

Harfiah NULL hanya dapat digunakan dengan operator perbandingan berikut: eq atau in.

Operator eq menghasilkan true jika kedua sisi adalah null nilai. Jika tidak, operator menghasilkan false.
Untuk operasi lain, kesalahan dimunculkan untuk harfiah NULL , dan perilaku tidak terdefinisi untuk properti nilai null (operasi perbandingan apa pun yang menghasilkan false).
Nilai null mendahului nilai non-null dalam urutan pengurutan (misalnya, jika pengurutan menurut properti diterapkan untuk mengembalikan daftar peristiwa).

Azure Time Series Insights Gen1 mendukung ekspresi logika Boolean berikut:

Nama properti di JSON	Deskripsi
dan	Mengambil sekumpulan argumen Boolean yang tidak kosong dan mengembalikan `true` jika semuanya dievaluasi ke `true`.
atau	Mengambil sekumpulan argumen Boolean yang tidak kosong dan mengembalikan `true` jika salah satu dari mereka mengevaluasi ke `true`.
not	Mengambil satu argumen Boolean dan mengembalikan nilai yang dinegasikan.

{
  "and": [
    {
      "eq": {
        "left": {
          "property": "p1",
          "type": "String"
        },
        "right": "abc"
      }
    },
    {
      "not": {
        "lt": {
          "left": {
            "property": "p1",
            "type": "Double"
          },
          "right": 1
        }
      }
    }
  ]
}

Properti stringComparison bersifat opsional. Secara default, nilainya adalah OrdinalIgnoreCase, yang menyebabkan casing kalimat diabaikan dalam perbandingan.

{
  "regex": {
    "left": {
      "property": "p1",
      "type": "String"
    },
    "right": "^abc*"
  }
}

{
  "regex": {
      "left": "abc",
      "right": "^a*$"
  }
}

Ekspresi aritmetika

Azure Time Series Insights Gen1 mendukung ekspresi aritmatika berikut:

Nama properti di JSON	Deskripsi
add	Tambahan
sub	Pengurangan
Mult	Perkalian
div	Divisi

Semua ekspresi aritmatika mengambil argumen kiri dan kanan dari jenis primitif dan mengembalikan nilai yang mewakili hasil operasi.

Semua jenis secara implisit hanya dilemparkan ke diri mereka sendiri, dan cast eksplisit tidak didukung.

{
  "add": {
    "left": {
      "property": "p1",
      "type": "Double"
     },
     "right": 1
  }
}

Tabel berikut ini memperlihatkan jenis argumen yang didukung untuk setiap ekspresi aritmatika:

Operasi	Jenis kiri	Jenis yang tepat	Jenis Hasil
add	Double	Double	Double
add	TimeSpan	TimeSpan	TimeSpan
add	DateTime	TimeSpan	DateTime
add	TimeSpan	DateTime	DateTime
sub	Double	Double	Double
sub	TimeSpan	TimeSpan	TimeSpan
sub	DateTime	DateTime	TimeSpan
sub	DateTime	TimeSpan	DateTime
mul	Double	Double	Double
div	Double	Double	Double

Ekspresi string predikat

Ekspresi string predikat Boolean berisi predikat Boolean yang direpresentasikan sebagai ekspresi yang dapat dibaca manusia yang disebut string predikat.

Contoh string predikat:

Untai (karakter) predikat	Deskripsi
`Description HAS 'hello world'`	`true` untuk peristiwa yang berisi frasa `hello world` di properti Deskripsi di semua sumber peristiwa
`'hello world'`	`true` untuk peristiwa yang berisi frasa `hello world`
`startsWith(Status, 'go')`	`true` untuk peristiwa dengan Status dimulai dengan `go`
`endsWith(Status, 'oD')`	`true` untuk peristiwa dengan Status diakhir dengan `od`
`startsWith_cs(Status, 'Go')`	`true` untuk peristiwa dengan Status dimulai dengan `Go`
`endsWith_cs(Status, 'od')`	`true` untuk peristiwa dengan Status dimulai dengan `od`
`matchesRegex(s, '^G*')`	`true` untuk peristiwa dengan Status yang cocok dengan ekspresi reguler `^G*`
`PointValue.Double = 3.14`	`true` untuk peristiwa dengan PointValue ganda sama dengan `3.14`
`Status IN ('Good','Bad')`	`true` untuk peristiwa dengan Status yang berisi `Good` atau `Bad`
`PointValue > 3.14 AND Status.String = 'Good'`	`true` untuk peristiwa dengan PointValue lebih besar dari `3.14` dan status string dari `Good`
`[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world'`	`true` untuk peristiwa dengan PointValue lebih besar dari `3.14` dan Status`Good` atau `Bad` dan Deskripsi yang tidak berisi frasa `hello world`

{ "predicateString": "PointValue.Double = 3.14" }

Ekspresi dalam string predikat dievaluasi ke dalam ekspresi JSON Boolean. Ini harus mematuhi tata bahasa berikut (disederhanakan):

Ekspresi JSON Boolean	Bentuk Backus–Naur
`parse`	`orPredicate EOF \| EOF;`
`orPredicate`	`andPredicate (Or andPredicate)*;`
`andPredicate`	`notPredicate (And notPredicate)*;`
`notPredicate`	`(Not)* predicate;`
`predicate`	`parenPredicate \| comparisonPredicateExtended \| hasPredicate \| inPredicate;`
`parenPredicate`	`OpenParen orPredicate CloseParen;`
`parenExpression`	`OpenParen additiveExpression CloseParen;`
`comparisonPredicateExtended`	`(ComparisonOp literal) \| comparisonPredicate;`
`comparisonPredicate`	`additiveExpression ComparisonOp additiveExpression;`
`additiveExpression`	`multiplicativeExpression ((Plus \| Minus) multiplicativeExpression)*;`
`multiplicativeExpression`	`unaryExpression (MultiplicativeOp unaryExpression)*;`
`functionCallExpression`	`identifier OpenParen CloseParen;`
`unaryExpression`	`identifier \| literal \| functionCallExpression \| parenPredicate \| parenExpression;`
`hasPredicate`	`(identifier? Has)? StringLiteral;`
`inPredicate`	`identifier? In OpenParen literal (Comma literal)* CloseParen;`
`literal`	`StringLiteral \| ((Minus)? NumericLiteral) \| BooleanLiteral \| DateTimeLiteral \| TimeSpanLiteral \| NullLiteral;`
`identifier`	`BuiltinIdentifier \| (QuotedOrUnquotedIdentifier (Sep QuotedOrUnquotedIdentifier)?);`

Azure Time Series Insights jenis data primitif Gen1 didukung dalam ekspresi string predikat.

Tidak seperti ekspresi referensi properti JSON, jenis untuk properti dapat dihilangkan, dalam hal ini jenis secara otomatis disimpulkan.

Literal yang didukung

Jenis primitif	Harfiah
Bool	`TRUE`, `FALSE`
DateTime	`dt'2016-10-08T03:22:55.3031599Z'`
Double	`1.23`, `1.0`
String	`'abc'`
TimeSpan	`ts'P1Y2M3DT4M5.67S'`
	`NULL`

Jenis operand yang didukung

Operasi	Jenis yang didukung	Catatan
<, >, <=, >=	Double, DateTime, TimeSpan
=, !=, <>	String, Bool, Double, DateTime, TimeSpan, NULL	<> setara untuk !=
+, -, *, /	Double, DateTime, TimeSpan
IN	String, Bool, Double, DateTime, TimeSpan, NULL	Semua operand harus memiliki tipe yang sama atau konstanta NULL. Beberapa NULLs setara dengan satu NULL.
HAS	Untai	Hanya literal string konstan yang diizinkan di sisi kanan. String kosong dan NULL tidak diperbolehkan.

Untuk predikat perbandingan (<, >, <=, =,>= , !=) dan operand predikat IN bisa NULL atau memiliki satu jenis.

Untuk ekspresi dengan predikat HAS , literal konstanta di sisi kanan operand HAS dapat diperluas menjadi beberapa jenis. Selain itu, literal konstanta ke sisi kanan operand HAS diurai ke dalam nilai Bool, Double, DateTime, atau TimeSpan . Untuk setiap nilai yang berhasil diurai, predikat dengan = operator dibuat. Predikat ini dan predikat HAS asli digabungkan ke dalam predikat OR . Misalnya, string p1 HAS '1.0' predikat setara dengan p1.String HAS '1.0' OR p1.Double = 1.0, jika properti p1 dengan jenis String dan Double ada.

Pemeriksaan jenis

Ekspresi predikat dicentang dan divalidasi untuk memastikan bahwa jenis tangan kanan dan kiri di dalamnya cocok.

Penting

Ketika konstanta ke kiri dan kanan operand tidak cocok, kesalahan dilemparkan.
Kesalahan juga muncul jika operasi tidak diizinkan pada atau di antara jenis tertentu.

Jika jenis ditentukan untuk properti, pemeriksaan jenis diterapkan:

Jenis properti apa pun diterima terhadap harfiah NULL .

Jika tidak, jenis sisi kiri dan sisi kanan harus cocok.

Contoh properti p1 dan p2 dari jenis String , dan properti p3 dari jenis Ganda ditampilkan dalam tabel berikut:

Untai (karakter) predikat	Apakah valid?	Catatan
`p1.String = 'abc'`	Ya
`p1.String = p2.String`	Ya
`p1.String = NULL`	Ya	`NULL` cocok dengan jenis sisi kiri apa pun.
`p3.Double = 'abc'`	Tidak	Tipe tidak cocok.
`p3.Double = p1.String`	Tidak	Tipe tidak cocok.
`p1.String HAS 'abc'`	Ya
`p3.Double HAS '1.0'`	Ya	Literal string berhasil diurai ke nilai Ganda .

Jika jenis dihilangkan untuk properti tetapi nama ditentukan, langkah-langkah berikut dilakukan:

Semua properti dengan nama dan jenis tertentu diambil.
Operan sisi kiri dan sisi kanan dikelompokkan berpasangan menurut jenis.
Pasangan digabungkan dengan menggunakan operasi AND .

Contoh properti p1 dan p2 dari jenis String dan Double dan beberapa yang setara ditampilkan dalam tabel berikut:

Untai (karakter) predikat	String predikat bertipe kuat yang setara	Catatan
`p1 = 'abc'`	`p1.String = 'abc'`
`p1 = true`		Tidak ada properti p1 jenis Bool, sehingga kesalahan properti yang hilang dipancarkan.
`p1 = NULL`	`p1.String = NULL AND p1.Double = NULL`	Untuk `NULL` sisi kanan diasumsikan bahwa semua properti yang cocok harus `NULL`.
`p1 != NULL`	`p1.String != NULL OR p1.Double != NULL`	Ini adalah inversi dari ekspresi sebelumnya.
`p1 = '1.0'`	`p1.String = '1.0'`
`p1 IN (1.0, NULL)`	`p1.Double = 1.0 OR p1.Double = NULL`
`p1 IN (NULL)`	`p1.String = NULL AND p1.Double = NULL`	Ini setara dengan `p1 = NULL`.
`p1 HAS '1.0'`	`p1.String HAS '1.0' OR p1.Double = 1.0`	Literal string berhasil diurai ke nilai Ganda yang valid.
`p1 HAS 'true'`	`p1.String HAS 'true'`	String literal berhasil diurai ke Bool, tetapi tidak ada p1. Properti Bool ada.
`p1 = p2`	`p1.String = p2.String AND p1.Double = p2.Double`
`p1 != p2`	`p1.String != p2.String OR p1.Double != p2.Double`	Ini adalah inversi dari ekspresi sebelumnya.

Nama dan jenis properti dapat dihilangkan untuk properti sisi kiri jika jenis properti sisi kanan didefinisikan dengan baik. Ini berlaku setiap kali sisi kanan memiliki harfiah konstan dan tidak hanya NULL mengandung harfiah.

Skenario ini adalah generalisasi pencarian teks lengkap yang menggunakan operand HAS .
Semua properti yang cocok dengan jenis sisi kanan diambil, dan ekspresi yang dihasilkan digabungkan melalui operasi OR .

Contoh properti p1 dari jenis String dan Double dan properti p2 dari jenis String dan DateTime ditampilkan dalam tabel berikut:

Untai (karakter) predikat	String predikat bertipe kuat yang setara	Catatan
`= 'abc'`	`p1.String = 'abc' OR p2.String = 'abc'`
`!= 'abc'`	`p1.String != 'abc' AND p2.String != 'abc'`	Inversi ekspresi sebelumnya
`= 1.0`	`p1.Double = 1.0`
`= dt'2000-01-02T03:04:05'`	`p2.DateTime = dt'2000-01-02T03:04:05'`
`= true`		Kesalahan. Tidak ada properti Bool , sehingga kesalahan properti yang hilang dipancarkan.
`= NULL`		Kesalahan. Menghilangkan nama properti untuk `NULL` sisi kanan tidak diperbolehkan.
`IN (NULL)`		Sama seperti kesalahan sebelumnya.
`IN (1.0, NULL)`	`p1.Double = 1.0 OR p1.Double = NULL`
`HAS '1.0'`	`p1.String HAS '1.0' OR p1.Double = 1.0 OR p2.String HAS '1.0'`
`HAS 'true'`	`p1.String HAS 'true' OR p2.String HAS 'true'`	Tidak ada properti dengan jenis Bool.

Jika operator dihilangkan bersama dengan nama properti, HAS operasi diasumsikan.

Fungsi bernilai skalar

Fungsi skalar mengembalikan nilai skalar.

Fungsi asli

Fungsi skalar yang didukung secara out-of-box oleh Azure Time Series Insights Gen1 meliputi:

Nama fungsi	Mengembalikan nilai	Argumen	Contoh	Catatan
utcNow	DateTime	Tidak ada	utcNow()	Mengembalikan waktu saat ini dalam format UTC. Nama fungsi peka huruf besar/kecil.

Fungsi UTC sekarang mengembalikan nilai DateTime , yang berisi waktu saat ini dalam format UTC. Ini tidak menerima argumen apa pun.

Ekspresi agregat

Ekspresi agregat digunakan untuk mempartisi koleksi peristiwa dan pengukuran komputasi atas partisi. Ekspresi agregat dibagi menjadi jenis berikut:

Ekspresi dimensi
Ekspresi nilai unik
Ekspresi histogram tanggal
Mengukur ekspresi

Ekspresi dimensi

Anda menggunakan ekspresi dimensi di dalam klausul agregat untuk mempartisi serangkaian peristiwa dan menetapkan kunci skalar ke setiap partisi.

Jenis ekspresi dimensi:

Nama properti di JSON	Deskripsi	Contoh
uniqueValues	Nilai dimensi dalam hasil adalah nilai yang tepat dari properti tertentu.
dateHistogram	Nilai dimensi dalam hasil adalah rentang waktu properti tertentu.	Histogram tanggal tanda waktu dapat menghasilkan rentang 10 jam untuk rentang pencarian 10 jam.
numericHistogram	Nilai dimensi dalam hasil adalah rentang nilai dalam properti tertentu.	Histogram numerik suhu dapat mengakibatkan pengembalian 10 rentang derajat.

Azure Time Series Insights Gen1 membatasi kardinalitas maksimum, atau ukuran kisi maksimum, dari kueri agregat input menjadi 150.000 sel. Untuk menghitung kardinalitas kueri agregat, Anda mengalikan ukuran semua dimensi dalam kueri. Selama produk kurang dari 150.000, kueri diterima untuk dieksekusi. Jika produk sama dengan atau kurang dari 150.000, kueri akan ditolak.

Anda menentukan ukuran maksimum dimensi yang dihasilkan oleh uniqueValues dan numericHistogram dengan menggunakan klausa ambil . Dalam dateHistogram, ukuran dihitung dengan membagi rentang pencarian dengan ukuran interval dateHistogram , yang Anda tentukan dengan menggunakan klausul jeda .

Misalnya, kueri agregat memiliki rentang pencarian yang ditetapkan dari "2017-11-15T16:00:00.000Z" ke "2017-11-15T19:00:00.000Z" = 3 jam. Jika kueri menyertakan dateHistogram dengan klausa pemisah , atur ke 1 menit (dimensi 1) dan uniqueValues di atas properti XYZ, ukuran dimensi dateHistogram adalah 3x60=180. Hasil ini berarti bahwa uniqueValues dapat memakan waktu hingga 150.000/180 = total 833 item.

Ekspresi nilai unik

Anda menggunakan ekspresi nilai unik untuk mengelompokkan sekumpulan peristiwa menurut nilai properti peristiwa tertentu.

Evaluasi ekspresi JSON ini menghasilkan hingga 100 rekaman, yang dikelompokkan menurut sensorId properti String.

{
  "uniqueValues": {
    "input": {
      "property": "sensorId",
      "type": "String"
    },
    "take": 100
  }
}

Ekspresi histogram tanggal

Anda menggunakan ekspresi histogram tanggal untuk mengelompokkan nilai properti DateTime ke dalam wadah dengan ukuran tertentu.

Evaluasi ekspresi JSON ini menghasilkan sekumpulan catatan Tanda Waktu yang dibulatkan ke lantai sehingga setiap nilai memiliki detik yang di-nol.

{
  "dateHistogram": {
    "input": {
      "builtInProperty": "$ts"
    },
    "breaks": {
      "size": "1m"
    }
  }
}

Ekspresi histogram numerik

Anda menggunakan ekspresi histogram numerik untuk mengelompokkan nilai properti Ganda ke dalam jumlah wadah tertentu.

Evaluasi ekspresi JSON ini menghasilkan 10 rekaman, sehingga rentang antara nilai minimum dan maksimum properti p1 dibagi menjadi 10 wadah.

{
  "numericHistogram": {
    "input": {
      "property": "p1",
      "type": "Double"
    },
    "breaks": {
      "count": 10
    }
  }
}

Mengukur ekspresi

Anda menggunakan ekspresi pengukuran di dalam klausa agregat untuk menghitung nilai skalar pada serangkaian peristiwa. Misalnya, ekspresi pengukuran adalah perhitungan nilai maksimum yang diukur oleh sensor suhu selama 24 jam terakhir.

Anda menggunakan ekspresi hitungan untuk menghitung jumlah peristiwa dalam wadah yang sesuai.

{ "count": {} }

Anda menggunakan ekspresi min, max, avg, dan sum untuk menghitung minimum, maksimum, rata-rata, dan jumlah nilai untuk properti tertentu dalam wadah yang sesuai.

{
  "min": {
    "input": {
      "property": "temperature",
      "type": "Double"
    }
  }
}

Dengan ekspresi pengukuran pertama dan terakhir , Anda bisa mendapatkan nilai properti A tertentu yang sesuai dengan nilai properti B minimum atau maksimum.

{
  "first": {
    "input": {
      "property": "propertyA",
      "type": "String"
    },
    "orderBy": {
      "property": "propertyB",
      "type": "Double"
    }
  }
}

{
  "last": {
    "input": {
      "property": "propertyA",
      "type": "Double"
    },
    "orderBy": {
      "property": "propertyB",
      "type": "DateTime"
    }
  }
}

Klausa orderBy bersifat opsional dan default ke properti Tanda Waktu$ts. Input dapat berjenis apa pun. Klausa orderBy hanya mendukung jenis Double dan DateTime .

Jika properti B adalah jenis DateTime , Anda mendapatkan nilai properti A terbaru atau paling awal.

Anda dapat menggunakan ekspresi pertama dan terakhir untuk membantu memahami nilai paling awal atau terbaru dari properti tertentu. Misalnya, jika Anda memiliki properti yang disebut deviceID dan Ingin memahami yang terbaru deviceID yang mengirim peristiwa, terakhir adalah operator ekspresi yang paling efisien untuk digunakan untuk mengidentifikasi informasi tersebut.

{
  "last": {
    "input": {
      "property": "deviceID",
      "type": "String"
    }
  }
}

Contoh lain adalah menggunakan yang terakhir untuk menemukan lokasi terakhir yang dilaporkan dari objek tertentu, seperti kapal, kendaraan, atau objek bergerak lainnya.

Untuk mengilustrasikan kueri yang menghasilkan lokasi terakhir yang diketahui dari kapal dalam armada, Anda dapat menulis kueri yang mirip dengan yang berikut ini:

{
  "searchSpan": {
    "from": "2018-05-05T12:00:00.000Z",
    "to": "2018-05-15T12:01:00.000Z"
  },
  "aggregates": [
     {
       "dimension": {
         "uniqueValues": {
           "input": {
             "property": "shipId",
             "type": "string"
            },
            "take": 150000
          }
        },
        "measures": [
          {
            "last": {
              "input": {
                "property": "Latitude",
                "type": "Double"
              }
           }
        },
        {
          "last": {
            "input": {
              "property": "Longitude",
              "type": "Double"
            }
          }
        }
      ]
    }
  ]
}

Contoh lain adalah menggunakan terlebih dahulu untuk menemukan perangkat yang melaporkan tekanan terendah untuk setiap pabrik:

{
  "searchSpan": {
    "from": "2018-05-05T12:00:00.000Z",
    "to": "2018-05-15T12:01:00.000Z"
  },
  "aggregates": [
    {
      "dimension": {
        "uniqueValues": {
          "input": {
            "property": "plantId",
            "type": "String"
          },
          "take": 150000
        }
     },
     "measures": [
       {
         "first": {
           "input": {
             "property": "deviceId",
             "type": "String"
           },
           "orderBy": {
             "property": "pressure",
              "type": "Double"
            }
          }
        }
      ]
    }
  ]
}

Dukungan jenis dimensi dan ukuran

Berikut adalah dimensi dan ekspresi pengukuran yang didukung, berdasarkan jenis properti:

Jenis properti	Ekspresi dimensi yang didukung	Ekspresi pengukuran yang didukung
Bool	`"uniqueValues"`	`"first"` (input), `"last"` (input)
DateTime	`"uniqueValues"`, `"dateHistogram"`	`"min"`, , `"max""first"` (orderBy, input), `"last”` (orderBy, input)
Double	`"uniqueValues"`, `"numericHistogram"`	`"sum"`, , `"min""avg"`, `"max"`, `"first"` (orderBy, input), `"last”` (orderBy, input)
String	`"uniqueValues"`	`"first"` (input), `"last"` (input)

Klausul

Klausul membentuk komponen konstituen dari kueri JSON atau bagian dari ekspresi. Klausul dibagi menjadi jenis berikut:

Klausa rentang pencarian
Klausa predikat
Batasi klausa teratas
Batas mengambil klausa
Membatasi klausa sampel
Memutus klausa
Klausa agregat

Klausa rentang pencarian

Anda menggunakan klausul rentang pencarian untuk memfilter properti Tanda Waktu bawaan peristiwa ke interval tertentu. Awal interval bersifat inklusif. Akhir interval bersifat eksklusif.

{
  "searchSpan": {
    "from": {
      "dateTime": "2016-08-01T00:00:00.000Z"
    },
    "to": {
      "dateTime": "2016-08-31T00:00:00.000Z"
    }
  }
}

Properti dari dan ke dalam klausa rentang pencarian (searchSpan) harus merupakan ekspresi yang valid dari jenis hasil DateTime . Ekspresi ini dievaluasi sebelum eksekusi kueri, yang berarti bahwa ekspresi tersebut tidak boleh berisi referensi properti apa pun.

Klausa predikat

Anda menggunakan klausa predikat untuk memfilter peristiwa yang memenuhi predikat. Ini harus diselesaikan menjadi ekspresi Boolean .

{
  "predicate": {
    "eq": {
      "left": {
        "property": "p1",
        "type": "String"
       },
       "right": "abc"
     }
  }
}

Untuk memfilter peristiwa berarti menjalankan predikat yang diwakili oleh ekspresi Boolean pada setiap peristiwa di lingkungan. Eksekusi ekspresi pada peristiwa mengembalikan true jika peristiwa harus disertakan dalam operasi lebih lanjut. Ini mengembalikan false jika peristiwa harus dihilangkan dari pemrosesan lebih lanjut.

Catatan

Peristiwa selalu difilter berdasarkan rentang pencarian selain pemfilteran apa pun yang ditentukan dalam ekspresi predikat.

Batasi klausa teratas

Anda menggunakan klausa atas *batas untuk mendapatkan jumlah nilai tertentu dalam urutan naik atau turun. Jumlah nilai dibatasi sesuai jumlah yang ditentukan.

{
  "sort": [
    {
      "input": {
        "builtInProperty": "$ts"
      },
      "order": "Asc"
    }
  ],
  "count": 10
}

Batas mengambil klausa

Anda dapat menggunakan klausa ambil batas sebagai cara cepat untuk mendapatkan sekumpulan nilai tanpa urutan tertentu. Jumlah nilai yang dikembalikan dibatasi oleh input yang ditentukan.

{ "take": 10 }

Membatasi klausa sampel

Anda menggunakan klausul sampel *batas untuk mendapatkan sampel representatif statistik dari serangkaian nilai. Jumlah nilai yang dikembalikan dibatasi oleh input yang ditentukan.

{ "sample": 10 }

Memutus klausa

Anda menggunakan klausa *jeda dalam ekspresi histogram untuk menentukan bagaimana rentang harus dibagi.

Untuk histogram tanggal, Anda harus menentukan ukuran interval tanggalwaktu dan batas interval. Anda melakukannya kecuali histogram didasarkan pada properti Tanda Waktu bawaan tempat batas ditentukan berdasarkan rentang pencarian:

Batas interval bersifat opsional dan dapat digunakan. Misalnya, Anda dapat menggunakannya saat ditentukan berdasarkan rentang pencarian jika batas interval dihilangkan.
Untuk histogram numerik, Anda harus menentukan jumlah jeda. Anda menentukan batas interval berdasarkan nilai minimum dan maksimum properti.

{
  "breaks": {
    "size": "1d",
    "from": "2000-01-02T03:04:05.0000000",
    "to": "2000-01-02T03:04:05.0000000"
  }
}

{
  "breaks": {
    "count": 10
  }
}

Klausa agregat

Anda menggunakan klausul agregat untuk mempartisi serangkaian peristiwa oleh properti tertentu saat Anda mengukur nilai properti peristiwa lainnya.

Pengukuran dievaluasi pada setiap partisi yang dihasilkan oleh ekspresi dimensi.

Contoh JSON berikut menghitung suhu rata-rata, minimum, dan maksimum per ID sensor.

{
  "aggregates": [
    {
      "dimension": {
        "uniqueValues": {
          "input": {
            "property": "sensorId",
            "type": "String"
          },
          "take": 100
        }
      },
      "measures": [
        {
          "avg": {
            "input": {
              "property": "temperature",
              "type": "Double"
            }
          }
        },
        {
          "min": {
            "input": {
              "property": "temperature",
              "type": "Double"
            }
          }
        },
        {
          "max": {
            "input": {
              "property": "temperature",
              "type": "Double"
            }
          }
        }
      ]
    }
  ]
}

Catatan

Klausa agregat adalah array yang memungkinkan Anda menentukan lebih dari satu agregasi di tingkat paling atas.

Contoh JSON berikut menghitung suhu rata-rata per kota dan per produsen secara independen:

{
  "aggregates": [
    {
      "dimension": {
        "uniqueValues": {
          "input": {
            "property": "city",
            "type": "String"
          },
          "take": 100
        }
      },
      "measures": [
        {
          "avg": {
            "input": {
              "property": "temperature",
              "type": "Double"
            }
          }
        }
      ]
    },
    {
      "dimension": {
        "uniqueValues": {
          "input": {
            "property": "manufacturer",
            "type": "String"
          },
          "take": 100
        }
      },
      "measures": [
        {
          "avg": {
            "input": {
              "property": "temperature",
              "type": "Double"
            }
          }
        }
      ]
    }
  ]
}

Catatan

Memiliki lebih dari satu elemen dalam array agregat saat ini tidak didukung.
Namun, definisi agregasi dapat mencakup array berlapis yang menentukan kisi multidimensi yang lebih fleksibel.

Contoh JSON berikut menghitung suhu rata-rata per ID sensor, per menit.

{
  "aggregates": [
    {
      "dimension": {
        "uniqueValues": {
          "input": {
            "property": "sensorId",
            "type": "String"
          },
          "take": 100
        }
      },
      "aggregate": {
        "dimension": {
          "dateHistogram": {
            "input": {
              "builtInProperty": "$ts"
            },
            "breaks": {
              "size": "1m"
            }
          }
        },
        "measures": [
          {
            "avg": {
              "input": {
                "property": "temperature",
                "type": "Double"
              }
            }
          }
        ]
      }
    }
  ]
}

Lihat juga

Untuk informasi selengkapnya tentang API Azure Time Series Insights Gen1, lihat API Gen1.
Untuk mempelajari tentang parameter permintaan dan autentikasi, lihat Autentikasi dan otorisasi.
Pelajari selengkapnya tentang Azure Time Series Insights Gen1 dengan meninjau dokumentasi Gen1.

Bagikan melalui

sintaks kueri Azure Time Series Insights Gen1

Ringkasan

Model data

Properti peristiwa

Jenis kejadian

Ekspresi skalar

Ekspresi konstanta

Jenis primitif yang dapat diubah ke null

Ekspresi referensi properti

Ekspresi perbandingan

Ekspresi aritmetika

Ekspresi string predikat

Literal yang didukung

Jenis operand yang didukung

Pemeriksaan jenis

Fungsi bernilai skalar

Fungsi asli

Ekspresi agregat

Ekspresi dimensi

Ekspresi nilai unik

Ekspresi histogram tanggal

Ekspresi histogram numerik

Mengukur ekspresi

Dukungan jenis dimensi dan ukuran

Klausul

Klausa rentang pencarian

Klausa predikat

Batasi klausa teratas

Batas mengambil klausa

Membatasi klausa sampel

Memutus klausa

Klausa agregat

Lihat juga

Sumber Daya Tambahan: