Azure Time Series Insights Gen1 クエリ構文
注意事項
これは Gen1 の記事です。
この記事では、Azure Time Series Insights Gen1 クエリ API のクエリ要求の形式と構文について説明します。
まとめ
重要
- クエリ要求は JSON 形式である必要があります。
- Query API に対して行われる HTTP 要求ペイロードは、この記事で指定されている形式に準拠している必要があります。
言語は次の要素に分割されます。
- スカラー 値を生成するスカラー式。 スカラー式には、 述語文字列式、 比較式、 および算術式が含まれます。
- スカラー 値を返すスカラー関数。
- 集計 式。これは、イベントのコレクションをパーティション分割し、パーティションに対するメジャーを計算するために使用されます。
- 句。JSON クエリの構成要素または式の一部を形成します。
データ モデル
Azure Time Series Insights Gen1 クエリ API は、環境内の個々のイベントとして格納されるデータに対して動作します。 各イベントは、 プロパティ名 と 値 のペアのセットです。
イベントのプロパティ
イベント プロパティには、 Bool、 DateTime、 Double、 または String のいずれかのプリミティブ型を指定できます。 すべてのプリミティブ型は null 許容です。
注意
カスタマイズされたイベント ソース形式では、より大きな値型のセットがサポートされる場合があります。 Azure Time Series Insights Gen1 は、最も近いプリミティブ型を推論し、カスタマイズされた型をイングレス時にそれらにキャストします。
すべてのイベントには、定義済みの名前と種類を持つ次の組み込みプロパティがあります。
| プロパティ名 | プロパティの種類 | 定義 |
|---|---|---|
| $ts | DateTime | イベントのタイムスタンプ |
| $esn | String | イベント ソース名 |
イベントのタイムスタンプ
既定では、イベント タイムスタンプ値はイベント ソースによって提供されます。 たとえば、IoT ハブから送信されるイベントには、タイムスタンプとしてエンキューされた時刻が含まれます。
お客様は、代わりに別のイベント プロパティを構成することで、この動作を変更できます。 カスタム タイムスタンプ プロパティは、 イベント ハブ と IoT ハブで指定できます。
イベント ソース名
イベント ソース名は、Azure Time Series Insights Gen1 がイベントを受信したイベント ソースに対して表示される名前です。 イベント ソース名は、イングレス時に特定のイベントに関連付けられます。
重要
- イベント ソース名は、イベントの有効期間中は変更されません。
- イベント ソースの名前が変更された場合、既存のイベントには古いイベント ソース名が付けられます。 新しいイベントには、新しいイベント ソース名が含まれます。
イベントの種類
カスタム イベント プロパティは、名前と種類によってクエリ式で一意に識別され、参照されます。 イベントには、同じ名前と異なる型を持つ複数のプロパティを含めることができます。 同じ名前で型が異なるプロパティは、イングレス型の分割によって発生する可能性があります。
String 型のイベント プロパティ値は、次の場合に別の型のプロパティとして格納できます。
- String 値が有効な Double 値の場合は、Double と String の両方として格納されます。
- String 値が有効な DateTime 値の場合は、DateTime としてのみ格納されます。
Query API は、出力で空の 文字列 リテラル ("") を に null 変換します。
Azure Time Series Insights Gen1 では、Double 型Double.NaN内の値 (、Double.PositiveInfinity、、 ) のサポートが制限されていますDouble.NegativeInfinity。
これらの値はイングレス時に に null 変換されますが、クエリ評価でこれらの値のいずれかが生成された場合、値は評価され、応答として String としてシリアル化されます。
これらの値はイングレス用の 文字列 として渡すことができます。そのため、クエリ式では、これらの値も 文字列として渡す必要があります。
イベント スキーマは、イベント のプロパティを記述します。 イベント スキーマには、イベント ソースの名前と、イベントの順序付けられたプロパティ のセットが含まれます。 イベントによってスキーマが異なる場合や、同じスキーマを共有する場合があります。
スカラー式
スカラー 式はスカラー値を生成します。 スカラー式は、次の種類に分かれています。
定数式
定数式は、各プリミティブ型に対して次のリテラルを使用して表します。
| プリミティブ型 | JSON 表現 | JSON の例 | Notes |
|---|---|---|---|
| Bool | JSON ブール型として | true, false |
|
| DateTime | ISO 8601 形式yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFKの単一の dateTime プロパティを持つ入れ子になったオブジェクトとして。 |
{"dateTime":"2016-08-01T00:00:00.000Z"} |
|
| Double | Double 範囲にキャストされた JSON 数値。 | 1.23e45, 123 |
二重 オーバーフローではエラーが発生します。 |
| String | JSON 文字列型 | "abc" |
|
| TimeSpan | ISO 8601 形式の単一の timeSpan プロパティを持つ入れ子になったオブジェクトとして: P[n]Y[n]M[n]DT[n]H[n]M[n]S。 |
{"timeSpan":"P1Y2M3DT4M5.67S"} |
Null 許容プリミティブ型
プリミティブ データ型は null 許容です。 null プリミティブ型の値は、JSON で次のように表されます。
{ "string": null }
{ "double": null }
{ "bool": null }
{ "dateTime": null }
{ "timeSpan": null }
プロパティ参照式
イベントの組み込みプロパティ以外の値にアクセスするには、プロパティ参照式を使用します。 組み込み以外のプロパティには、イベント スキーマに自動的に含まれる既定のプロパティ以外のカスタマイズされたプロパティが含まれます。
プロパティ参照式の結果の型は、プロパティのプリミティブ型です。 イベント スキーマのプロパティは名前と型によって一意に識別され、参照式では両方を指定する必要があります。
JSON の例:
{ "property": "p1", "type": "Bool" }{ "property": "p1", "type": "DateTime" }{ "property": "p1", "type": "Double" }{ "property": "p1", "type": "String" }{ "property": "p1", "type": "TimeSpan" }
組み込みのプロパティ参照式は、イベントの組み込みプロパティにアクセスするために使用されます。 組み込みプロパティは、イベント スキーマで自動的に定義されるプロパティのみです。
組み込みのプロパティ参照式の結果の型は、 プロパティのプリミティブ型です。 組み込みプロパティは名前でのみ参照されます。したがって、参照式には型は必要ありません。
{ "builtInProperty": "$esn" }
比較式
次の ブール値比較 式がサポートされています。
| JSON のプロパティ名 | Description |
|---|---|
| eq | 等しい |
| in | (等しい任意) |
| phrase | 語句を含む |
| startsWith | 次で始まる |
| endsWith | 語句で終わる |
| regex | 次の正規表現と一致する |
| lt | より小さい |
| lte | 以下 |
| gt | より大きい |
| Gte | 以上 |
重要
- すべての比較式は、左引数と右辺引数の両方のプリミティブ型を受け取り、比較の結果を表す ブール 値を返します。
- 比較の左辺引数と右辺引数の両方の型が一致している必要があります。
- すべての型は暗黙的にそれ自体にのみキャストされ、明示的なキャストはサポートされていません。
{
"eq": {
"left": {
"property": "p1",
"type": "String"
},
"right": "abc"
}
}
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" } }
次の表は、各比較式でサポートされている引数の種類を示しています。
| 引数の型 | サポートされている比較操作 |
|---|---|
| Bool | eq、 in |
| DateTime | eq、 in、 lt、 lte、 gt、 gte |
| Double | eq、 in、 lt、 lte、 gt、 gte |
| String | eq、 in、 phrase、 startsWith、 endsWith、 regex |
| TimeSpan | eq、 in、 lt、 lte、 gt、 gte |
NULL リテラルは、次の比較演算子 (eq または in) でのみ使用できます。
- eq 演算子は、両側が値の場合に
truenullになります。 それ以外の場合、演算子の結果は になりますfalse。 - その他の操作の場合は、NULL リテラルに対してエラーが発生し、 null 値プロパティの動作は未定義です (結果
falseとして の比較操作)。 - 値は
null、並べ替え順序で null 以外の値の前に置きます (たとえば、イベントの一覧を返すためにプロパティによる並べ替えが適用されている場合)。
Azure Time Series Insights Gen1 では、次のブール論理式がサポートされています。
| JSON のプロパティ名 | 説明 |
|---|---|
| and | 空でないブール型引数のセットを受け取り、それらすべてが に評価された場合は をtrue返trueします。 |
| or | 空でないブール型引数のセットを受け取り、いずれかの引数が に評価された場合は をtrue返trueします。 |
| not | 1 つの ブール値 引数を受け取り、その否定値を返します。 |
{
"and": [
{
"eq": {
"left": {
"property": "p1",
"type": "String"
},
"right": "abc"
}
},
{
"not": {
"lt": {
"left": {
"property": "p1",
"type": "Double"
},
"right": 1
}
}
}
]
}
stringComparison プロパティは省略可能です。 既定では、その値は です OrdinalIgnoreCase。これにより、比較で文の大文字と小文字が無視されます。
{
"regex": {
"left": {
"property": "p1",
"type": "String"
},
"right": "^abc*"
}
}
{
"regex": {
"left": "abc",
"right": "^a*$"
}
}
算術式
Azure Time Series Insights Gen1 では、次の算術式がサポートされています。
| JSON のプロパティ名 | 説明 |
|---|---|
| add | 加算 |
| sub | 減算 |
| Mult | 乗算 |
| div | 除算 |
すべての算術式は、プリミティブ型の左右の引数を受け取り、演算の結果を表す値を返します。
すべての型は暗黙的にそれ自体にのみキャストされ、明示的なキャストはサポートされていません。
{
"add": {
"left": {
"property": "p1",
"type": "Double"
},
"right": 1
}
}
次の表は、各算術式でサポートされている引数の型を示しています。
| 操作 | 左の型 | 右の型 | 結果の種類 |
|---|---|---|---|
| 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 |
述語文字列式
ブール述語文字列 式には、述語文字列と呼ばれる人間が判読できる式として表されるブール 述語が含まれています。
述語文字列の例:
| 述語文字列 | Description |
|---|---|
Description HAS 'hello world' |
trueすべてのイベント ソースの Description プロパティの語句hello worldを含むイベントの場合 |
'hello world' |
true フレーズを含むイベントの場合 hello world |
startsWith(Status, 'go') |
true状態が で始まるイベントの場合go |
endsWith(Status, 'oD') |
trueStatus がで終わるイベントの場合od |
startsWith_cs(Status, 'Go') |
true状態が で始まるイベントの場合Go |
endsWith_cs(Status, 'od') |
true状態が で始まるイベントの場合od |
matchesRegex(s, '^G*') |
true 正規表現に一致する Status を持つイベントの場合 ^G* |
PointValue.Double = 3.14 |
true double PointValue が と等しいイベントの場合 3.14 |
Status IN ('Good','Bad') |
true または を含む Status を持つイベントの Good 場合 Bad |
PointValue > 3.14 AND Status.String = 'Good' |
truePointValue が より3.14大きく、文字列 Status が のイベントの場合Good |
[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world' |
truePointValue が より3.14大きいイベントの場合、または のGoodBad状態と、語句が含まれていない説明hello world |
{ "predicateString": "PointValue.Double = 3.14" }
述語文字列内の式は、JSON ブール式に評価されます。 次の (簡略化された) 文法に準拠している必要があります。
| JSON ブール式 | 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 Gen1 プリミティブ データ型は、述語文字列式でサポートされています。
JSON プロパティ参照式とは異なり、プロパティの型は省略できます。その場合、型は自動的に推論されます。
サポートされているリテラル
| プリミティブ型 | リテラル |
|---|---|
| Bool | TRUE, FALSE |
| DateTime | dt'2016-10-08T03:22:55.3031599Z' |
| Double | 1.23, 1.0 |
| String | 'abc' |
| TimeSpan | ts'P1Y2M3DT4M5.67S' |
NULL |
サポートされているオペランド型
| 操作 | サポートされている型 | Notes |
|---|---|---|
| <、>、<、> | Double、DateTime、TimeSpan | |
| =、=、<> | String、Bool、Double、DateTime、TimeSpan、NULL | <>は!= に相当します |
| +, -, *, / | Double、DateTime、TimeSpan | |
| IN | String、Bool、Double、DateTime、TimeSpan、NULL | すべてのオペランドは同じ型か NULL 定数である必要があります。 複数の NULLは、1 つの NULL に相当 します。 |
| HAS | String | 右側で使用できるのは定数文字列リテラルのみです。 空の文字列と NULL は使用できません。 |
比較述語 (<、=、><=、>!==) の場合、IN 述語オペランドは NULL または単一の型にすることができます。
HAS 述語を持つ式の場合、HAS オペランドの右側にある定数リテラルを複数の型に展開できます。 さらに、 HAS オペランドの右側にある定数リテラルは 、Bool、 Double、 DateTime、または TimeSpan 値に解析されます。 正常に解析された値ごとに、 演算子を含む = 述語が作成されます。 これらの述語と元の HAS 述語は 、OR 述語に結合されます。 たとえば、String 型と Double 型の p1 プロパティが存在するp1.String HAS '1.0' OR p1.Double = 1.0場合、述語文字列p1 HAS '1.0'は と同じです。
型チェック
述語式は型チェックされ、その中の右側の型と左側の型が一致することを確認するために検証されます。
重要
- オペランドの左右の定数が一致しない場合は、エラーがスローされます。
- また、特定の型に対して、または特定の型間で操作が許可されていない場合にも、エラーがスローされます。
プロパティに型が指定されている場合は、チェック型が適用されます。
すべてのプロパティ型は NULL リテラルに対して受け入れられます。
それ以外の場合は、左側と右側の型が一致する必要があります。
文字列型のプロパティ p1 と p2、Double 型のプロパティ p3 の例を次の表に示します。
述語文字列 有効ですか? メモ p1.String = 'abc'はい p1.String = p2.Stringはい p1.String = NULLはい NULLは、任意の左側の型と一致します。p3.Double = 'abc'いいえ 型が一致しません。 p3.Double = p1.Stringいいえ 型が一致しません。 p1.String HAS 'abc'はい p3.Double HAS '1.0'はい 文字列リテラルが Double 値に正常に解析されました。
プロパティの型を省略しても名前が指定されている場合は、次の手順が実行されます。
- 指定した名前と型を持つすべてのプロパティが取得されます。
- 左側と右側のオペランドは、型ごとにペアでグループ化されます。
- ペアは AND 演算を使用して連結されます。
String 型と Double 型のプロパティ p1 と p2 の例と、それに相当するものの一部を次の表に示します。
述語文字列 同等の厳密型述語文字列 Notes p1 = 'abc'p1.String = 'abc'p1 = trueBool 型の p1 プロパティがないため、不足しているプロパティ エラーが生成されます。 p1 = NULLp1.String = NULL AND p1.Double = NULL右側では NULL、一致するすべてのプロパティが である必要があると見なされますNULL。p1 != NULLp1.String != NULL OR p1.Double != NULLこれは、前の式の反転です。 p1 = '1.0'p1.String = '1.0'p1 IN (1.0, NULL)p1.Double = 1.0 OR p1.Double = NULLp1 IN (NULL)p1.String = NULL AND p1.Double = NULLこれは と同等です p1 = NULL。p1 HAS '1.0'p1.String HAS '1.0' OR p1.Double = 1.0文字列リテラルは、有効な Double 値に正常に解析されました。 p1 HAS 'true'p1.String HAS 'true'文字列リテラルは Bool に正常に解析されましたが、p1 は解析されませんでした 。Bool プロパティが存在します。 p1 = p2p1.String = p2.String AND p1.Double = p2.Doublep1 != p2p1.String != p2.String OR p1.Double != p2.Doubleこれは、前の式の反転です。
右側のプロパティ型が適切に定義されている場合は、左側のプロパティのプロパティ名と型の両方を省略できます。 これは、右側に定数リテラルがあり、リテラルのみが含まれていない場合に
NULL当てはまります。このシナリオは、 HAS オペランドを使用するフルテキスト検索の一般化です。
右側の型に一致するすべてのプロパティが取得され、結果の式は OR 演算を介して連結されます。
String 型と Double 型のプロパティ p1 と、String 型と DateTime 型のプロパティ p2 の例を次の表に示します。
述語文字列 同等の厳密型述語文字列 Notes = 'abc'p1.String = 'abc' OR p2.String = 'abc'!= 'abc'p1.String != 'abc' AND p2.String != 'abc'前の式の反転 = 1.0p1.Double = 1.0= dt'2000-01-02T03:04:05'p2.DateTime = dt'2000-01-02T03:04:05'= trueエラー。 Bool プロパティが存在しないため、不足しているプロパティ エラーが生成されます。 = NULLエラー。 右側のプロパティ名を NULL省略することはできません。IN (NULL)上記のエラーと同じです。 IN (1.0, NULL)p1.Double = 1.0 OR p1.Double = NULLHAS '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'Bool 型のプロパティはありません。
演算子をプロパティ名と共に省略すると、操作が
HAS想定されます。
スカラー関数
スカラー関数は スカラー値を返します。
ネイティブ関数
Azure Time Series Insights Gen1 ですぐにサポートされるスカラー関数には、次のようなものがあります。
| 関数名 | 戻り値 | 引数 | 例 | Notes |
|---|---|---|---|---|
| utcNow | DateTime | なし | utcNow() | 現在の時刻を UTC 形式で返します。 関数名では大文字と小文字が区別されます。 |
UTC 関数は、現在の時刻を UTC 形式で含む DateTime 値を返すようになりました。 引数は受け付けません。
集計式
集計式は、パーティションに対するイベントとコンピューティング メジャーのコレクションをパーティション分割するために使用されます。 集計式は、次の種類に分かれています。
ディメンション式
aggregates 句内のディメンション式を使用して、一連のイベントをパーティション分割し、各パーティションにスカラー キーを割り当てます。
ディメンション式の型:
| JSON のプロパティ名 | Description | 例 |
|---|---|---|
| uniqueValues | 結果のディメンション値は、特定のプロパティの正確な値です。 | |
| dateHistogram | 結果のディメンション値は、特定のプロパティの時間の範囲です。 | タイムスタンプの日付ヒストグラムは、10 時間の検索範囲に対して 10 1 時間の範囲になる可能性があります。 |
| numericHistogram | 結果のディメンション値は、特定のプロパティの値の範囲です。 | 温度の数値ヒストグラムでは、10 度の範囲が返される場合があります。 |
Azure Time Series Insights Gen1 では、入力集計クエリの最大カーディナリティ (最大格子サイズ) が 150,000 セルに制限されます。 集計クエリのカーディナリティを計算するには、クエリ内のすべてのディメンションのサイズを乗算します。 製品が 150,000 未満である限り、クエリは実行に対して受け入れられます。 製品が 150,000 以下の場合、クエリは拒否されます。
take 句を使用して、uniqueValues と numericHistogram によって生成されるディメンションの最大サイズを指定します。 dateHistogram では、サイズは、検索範囲を dateHistogram 間隔のサイズで割ることによって計算されます。この間隔は、breaks 句を使用して指定します。
たとえば、集計クエリの検索範囲が "2017-11-15T16:00:00.000Z" から "2017-11-15T19:00:00.000Z" = 3 時間に設定されています。 クエリに、breaks 句を含む dateHistogram が含まれており、プロパティ XYZ に対して 1 分 (ディメンション 1) と uniqueValues に設定されている場合、dateHistogram ディメンション サイズは 3x60=180 です。 この結果は、 uniqueValues が最大 150,000/180 = 833 項目の合計を要する可能性があることを意味します。
一意の値の式
一意の値式を使用して、指定したイベント プロパティの値によってイベントのセットをグループ化します。
この JSON 式を評価すると、最大 100 個のレコードが作成され、String プロパティによってsensorIdグループ化されます。
{
"uniqueValues": {
"input": {
"property": "sensorId",
"type": "String"
},
"take": 100
}
}
日付ヒストグラム式
日付ヒストグラム式を使用して、DateTime プロパティ値を指定したサイズのバケットにグループ化します。
この JSON 式を評価すると、各値が秒ゼロになるように、フロア丸めされた タイムスタンプ レコードのセットが作成されます。
{
"dateHistogram": {
"input": {
"builtInProperty": "$ts"
},
"breaks": {
"size": "1m"
}
}
}
数値ヒストグラム式
数値ヒストグラム式を使用して、Double プロパティ値を指定された数のバケットにグループ化します。
この JSON 式を評価すると、10 個のレコードが返されるため、p1 プロパティの最小値と最大値の範囲は 10 バケットに分割されます。
{
"numericHistogram": {
"input": {
"property": "p1",
"type": "Double"
},
"breaks": {
"count": 10
}
}
}
メジャー式
一連のイベントに対してスカラー値を計算するには、aggregates 句内でメジャー式を使用します。 たとえば、メジャー式は、過去 24 時間に温度センサーによって測定された最大値の計算です。
count 式を使用して、対応するバケット内のイベントの数を計算します。
{ "count": {} }
min、max、avg、sum の各式を使用して、対応するバケット内の指定されたプロパティの値の最小値、最大値、平均、合計を計算します。
{
"min": {
"input": {
"property": "temperature",
"type": "Double"
}
}
}
最初と最後のメジャー式では、プロパティ B の最小値または最大値に対応する指定されたプロパティ A の値を取得できます。
{
"first": {
"input": {
"property": "propertyA",
"type": "String"
},
"orderBy": {
"property": "propertyB",
"type": "Double"
}
}
}
{
"last": {
"input": {
"property": "propertyA",
"type": "Double"
},
"orderBy": {
"property": "propertyB",
"type": "DateTime"
}
}
}
orderBy 句は省略可能であり、既定では Timestamp プロパティ$ts。 入力には任意の型を指定できます。 orderBy 句では、Double 型と DateTime 型のみがサポートされます。
プロパティ B が DateTime 型の場合は、プロパティ A の最新または最も古い値を取得します。
最初と最後の式を使用すると、特定のプロパティの最も古い値または最新の値を理解するのに役立ちます。 たとえば、 という deviceID プロパティがあり、イベントを送信した最新 deviceID のを理解したい場合、 last は、その情報を識別するために使用する最も効率的な式演算子です。
{
"last": {
"input": {
"property": "deviceID",
"type": "String"
}
}
}
もう 1 つの例は、 last を使用して、船舶、車両、その他の移動オブジェクトなど、特定のオブジェクトの最後に報告された場所を検索することです。
フリート内の船舶の最後の既知の場所を生成するクエリを示すために、次のようなクエリを作成できます。
{
"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"
}
}
}
]
}
]
}
もう 1 つの例は、 最初 に を使用して、すべてのプラントの最低圧力を報告するデバイスを見つけることです。
{
"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"
}
}
}
]
}
]
}
ディメンションとメジャーの種類のサポート
プロパティの種類に基づいて、サポートされているディメンション式とメジャー式を次に示します。
| プロパティの種類 | サポートされているディメンション式 | サポートされているメジャー式 |
|---|---|---|
| Bool | "uniqueValues" |
"first" (入力)、 "last" (入力) |
| DateTime | "uniqueValues", "dateHistogram" |
"min"、 "max"、 "first" (orderBy、input) "last” 、(orderBy、input) |
| Double | "uniqueValues", "numericHistogram" |
"sum"、 "avg"、 "min"、、 "max"、 "first" (orderBy、input) "last” 、(orderBy、input) |
| String | "uniqueValues" |
"first" (入力)、 "last" (入力) |
句
句は、 JSON クエリの構成要素または式の一部を形成します。 句は次の種類に分かれています。
検索スパン句
検索スパン句を使用して、イベントの組み込みの Timestamp プロパティを特定の間隔でフィルター処理します。 間隔の開始は包括的です。 間隔の末尾は排他的です。
{
"searchSpan": {
"from": {
"dateTime": "2016-08-01T00:00:00.000Z"
},
"to": {
"dateTime": "2016-08-31T00:00:00.000Z"
}
}
}
検索スパン句 (searchSpan) の from プロパティと to プロパティは、DateTime 結果型の有効な式である必要があります。 これらの式は、クエリの実行前に評価されます。つまり、プロパティ参照を含めてはなりません。
述語句
述語句を使用して、 述語 を満たすイベントをフィルター処理します。 これはブール式に解決する必要があります。
{
"predicate": {
"eq": {
"left": {
"property": "p1",
"type": "String"
},
"right": "abc"
}
}
}
イベントをフィルター処理するには、環境内の各イベントでブール式で表される述語を実行することを意味します。 イベントに対する式の実行は、イベントをそれ以上の true 操作に含める必要がある場合に返されます。 イベントをそれ以降の false 処理から省略する必要がある場合は を返します。
注意
イベントは、述語式内で指定されたフィルター処理に加えて、常に検索範囲でフィルター処理されます。
上位の句を制限する
指定した数の値を昇順または降順で取得するには、*limit top 句を使用します。 値の数は、指定された数に従って制限されます。
{
"sort": [
{
"input": {
"builtInProperty": "$ts"
},
"order": "Asc"
}
],
"count": 10
}
take 句を制限する
特定の順序で値のセットを取得する簡単な方法として 、limit take 句を使用できます。 返される値の数は、指定された入力によって制限されます。
{ "take": 10 }
サンプル句を制限する
*limit sample 句を使用して、一連の値から統計的に代表的なサンプルを取得します。 返される値の数は、指定された入力によって制限されます。
{ "sample": 10 }
Breaks 句
ヒストグラム式で *breaks 句を使用して、範囲を分割する方法を指定します。
日付ヒストグラムの場合は、datetime 間隔と間隔の境界のサイズを指定する必要があります。 ヒストグラムが組み込みの Timestamp プロパティに基づいており、境界が検索範囲に基づいて決定される場合を除き、これを行います。
- 間隔の境界は省略可能であり、使用できます。 たとえば、間隔の境界を省略した場合に、検索範囲に基づいて決定されたときに使用できます。
- 数値ヒストグラムの場合は、区切りの数を指定する必要があります。 間隔の境界は、プロパティの最小値と最大値に基づいて決定します。
{
"breaks": {
"size": "1d",
"from": "2000-01-02T03:04:05.0000000",
"to": "2000-01-02T03:04:05.0000000"
}
}
{
"breaks": {
"count": 10
}
}
集計句
aggregates 句を使用して、他のイベント プロパティの値を測定している間に、特定のプロパティによってイベントのセットをパーティション分割します。
メジャーは、ディメンション式によって生成される各パーティションで評価されます。
次の JSON の例では、センサー ID ごとの平均、最小、および最大温度を計算します。
{ "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" } } } ] } ] }注意
aggregates 句は、最上位レベルで複数の集計を指定できる配列です。
次の JSON の例では、市区町村あたりの平均気温と製造元ごとの平均温度を個別に計算します。
{ "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" } } } ] } ] }注意
- 集計配列に複数の要素を含めるのは、現在サポートされていません。
- ただし、集計定義には、より柔軟な多次元格子を指定する入れ子になった配列を含めることができます。
次の JSON の例では、センサー ID あたりの 1 分あたりの平均温度を計算します。
{ "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" } } } ] } } ] }
関連項目
Azure Time Series Insights Gen1 API の詳細については、「Gen1 API」を参照してください。
要求パラメーターと認証パラメーターの詳細については、「 認証と承認」を参照してください。
Gen1 Azure Time Series Insightsの詳細については、Gen1 のドキュメントを参照してください。