Azure 時間序列深入解析 Gen1 查詢語法

警告

這是 Gen1 文章。

本文說明 Azure 時間序列深入解析 Gen1查詢 API的查詢要求格式和語法。

總結

重要

• 查詢要求必須是 JSON 格式。
• 對 查詢 API 提出的 HTTP 要求承載應該符合本文中指定的格式。

語言會細分為下列元素：

• 產生純量值的純量運算式。 純量運算式包括 述詞字串運算式、 比較運算式和 算術運算式。
• 傳回純量值的純量函式。
• 匯總 運算式，用來分割事件集合，以及分割區上的計算量值。
• 子句，形成 JSON 查詢的組成元件或運算式的一部分。

資料模型

Azure 時間序列深入解析 Gen1 查詢 API 會在環境中儲存為個別事件的資料上運作。 每個事件都是一組屬性名稱和值組。

事件屬性

事件屬性可以是下列其中一種基本類型： Bool、 DateTime、 Double或 String。 所有基本類型都是可為 Null 的。

注意

自訂的事件來源格式可能支援一組較大的實數值型別。 Azure 時間序列深入解析 Gen1 推斷最接近的基本類型，然後在輸入時將自訂類型轉換成它們。

所有事件都有下列具有預先定義名稱和類型的內建屬性：

屬性名稱	屬性類型	定義
$ts	DateTime	事件時間戳記
$esn	String	事件來源名稱

• 事件時間戳記

  根據預設，事件來源會提供事件時間戳記值。 例如，來自 IoT 中樞的事件會將其排入佇列的時間作為時間戳記。

  客戶可以改為設定另一個事件屬性來修改此行為。 您可以在 事件中樞 和 IoT 中樞中指定自訂時間戳記屬性。

• 事件來源名稱

  事件來源名稱是Azure 時間序列深入解析 Gen1 收到事件的事件來源所顯示的名稱。 事件來源名稱會在輸入時間與特定事件相關聯。

  重要

  • 事件來源名稱在事件的存留期內保持不變。
  • 如果修改事件來源的名稱，現有的事件會包含舊的事件來源名稱。 新的事件會包含新的事件來源名稱。

事件類型

自訂事件屬性會依名稱和類型在查詢運算式中唯一識別和參考。 事件可以有多個具有相同名稱和不同類型的屬性。 具有相同名稱但不同型別的屬性可能會導致輸入類型分割。

在下列情況下， String 類型的事件屬性值可以儲存為具有不同類型的屬性：

• 如果 String 值是有效的 Double 值，則會同時儲存為 Double 和 String。
• 如果 String 值是有效的 DateTime 值，則只會儲存為 DateTime 。

查詢 API 會將輸出中的空 字串 常值 ("") 轉換成 null 。

Azure 時間序列深入解析 Gen1 對Double類型內的下列值有有限的支援： Double.NaN 、 Double.PositiveInfinity 和 Double.NegativeInfinity 。 這些值會在 null 輸入期間轉換成 ，但如果查詢評估產生其中一個值，則會評估該值並序列化為 字串 以回應。

您可以將這些值當做 輸入的字串 傳遞，因此在查詢運算式中，這些值也應該以 字串的形式傳遞。

事件架構描述 事件的屬性。 事件架構包含事件來源的名稱，以及事件的已排序屬性集。 不同的事件可以有不同的架構或共用相同的架構。

純量運算式

純量 運算式會產生純量值。 純量運算式分成下列類型：

• 常數運算式
• 屬性參考運算式
• 比較運算式
• 算術運算式
• 述詞字串運算式

常數運算式

您可以針對每個基本類型使用下列常值來表示 常數 運算式：

基本型別	JSON 標記法	JSON 範例	備註
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， gte， gte
Double	eq， in， lt， lte， gte， gte
String	eq， in， phrase， startsWith， endWith， RegEx
TimeSpan	eq， in， lt， lte， gte， gte

Null常值只能與下列比較運算子搭配使用：eq或in。

• 如果兩端都是 null 值，eq運算子會產生 true 。 否則，運算子會產生 false 。
• 若為其他作業，則會針對 Null 常值引發錯誤，而且行為未針對 null 值屬性定義， (任何會導致 false) 的比較作業。
• 例如 null ，如果套用屬性排序以傳回) 事件清單，則值在排序次序 (之前為非 Null 值。

Azure 時間序列深入解析 Gen1 支援下列布林邏輯運算式：

JSON 中的屬性名稱	Description
and	接受非空的布林引數集合，如果所有引數都評估為 true ，則會傳回 true 。
or	接受非空的布林引數集合，並在其中任何一個引數評估為 true 時傳回 true 。
not	接受單一 布林 引數，並傳回其負值。

{
  "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 時間序列深入解析 Gen1 支援下列算術運算式：

JSON 中的屬性名稱	描述
新增	加法
sub	減
mult	乘
div	部門

所有算術運算式都會採用基本型別的左右引數，並傳回代表作業結果的值。

所有類型都會隱含地轉換成本身，而且不支援明確轉換。

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

下表顯示每個算術運算式支援的引數類型：

作業	左側類型	右類型	結果類型
新增	Double	Double	Double
新增	TimeSpan	TimeSpan	TimeSpan
新增	DateTime	TimeSpan	DateTime
新增	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')	true 表示 狀態 結尾為 的事件 od
startsWith_cs(Status, 'Go')	true 適用于 狀態開頭 為 的事件 Go
endsWith_cs(Status, 'od')	true 適用于 狀態開頭 為 的事件 od
matchesRegex(s, '^G*')	true 代表符合正則運算式 之 Status 的事件 ^G*
PointValue.Double = 3.14	true 表示雙 PointValue 等於的事件 3.14
Status IN ('Good','Bad')	true 包含 或 之狀態Good 的事件 Bad
PointValue > 3.14 AND Status.String = 'Good'	true 表示 PointValue 大於 3.14 且字串 Status 為 的事件 Good
[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world'	true 表示 PointValue 大於 3.14 且 StatusGood 為 或 Bad 且未包含片語 之 Description 的事件 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 時間序列深入解析 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

支援的運算元類型

作業	支援的類型	備註
< > <=>=	Double、DateTimeTimeSpan
=、!=、<>	String、Bool、Double、DateTime、TimeSpanNULL	<> 相當於 ！=
+, -, *, /	Double、DateTimeTimeSpan
IN	String、Bool、Double、DateTime、TimeSpanNULL	所有的運算元都應該是相同的類型或是 NULL 常數。 多個 Null相當於單一 Null。
HAS	String	右側只允許常數字串常值。 不允許空字串和 Null 。

如需比較述詞， < (、、 > =< 、=、>=、！=) 和IN述詞運算元可以是Null或具有單一類型。

對於 具有 HAS 述詞的運算式， HAS 運算元右邊的常數常值可以展開成多個類型。 此外， HAS 運算元右側的常數常值會剖析為 Bool、 Double、 DateTime或 TimeSpan 值。 針對每個成功剖析的值，會建立具有 運算子的 = 述詞。 這些述詞和原始 HAS 述詞會聯結至 OR 述詞。 例如，如果具有String和Double類型的p1屬性存在，述詞字串 p1 HAS '1.0' 就相當於 p1.String HAS '1.0' OR p1.Double = 1.0 。

類型檢查

述詞運算式會經過類型檢查並經過驗證，以確保其內的右手和左側類型相符。

重要

• 當運算元左邊和右邊的常數不相符時，就會擲回錯誤。
• 如果特定類型上不允許或不允許作業，也會擲回錯誤。

• 如果為屬性指定類型，則會套用類型檢查：

  • 對 Null 常值接受任何屬性類型。

  • 否則，左側和右側類型應該相符。

    下表顯示String類型的屬性 p1和p2，以及Double類型的屬性p3範例：

    述詞字串	有效嗎？	附註
    p1.String = 'abc'	是
    p1.String = p2.String	Yes
    p1.String = NULL	Yes	NULL 會比對任何左側類型。
    p3.Double = 'abc'	No	型別不符。
    p3.Double = p1.String	No	型別不符。
    p1.String HAS 'abc'	Yes
    p3.Double HAS '1.0'	Yes	字串常值已成功剖析為 Double 值。

• 如果省略屬性的類型，但指定了名稱，則會執行下列步驟：

  1. 會取得具有指定名稱和類型的所有屬性。
  2. 左側和右側運算元會依類型分組。
  3. 配對會使用 AND 作業串連。

  • 下表顯示String和Double類型屬性p1和p2的屬性範例及其部分對等專案：

    述詞字串	對等的強型別述詞字串	備註
    p1 = 'abc'	p1.String = 'abc'
    p1 = true		沒有類型為 Bool的p1屬性，因此會發出遺漏的屬性錯誤。
    p1 = NULL	p1.String = NULL AND p1.Double = NULL	針對 NULL 右側，假設所有相符的屬性都應該是 NULL 。
    p1 != NULL	p1.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 = NULL
    p1 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 = p2	p1.String = p2.String AND p1.Double = p2.Double
    p1 != p2	p1.String != p2.String OR p1.Double != p2.Double	這是上述運算式的反轉。

• 如果右側屬性類型已妥善定義，則可以省略左側屬性的屬性名稱和類型。 每當右側有常值且不包含 NULL 常值時，就會發生這種情況。

  • 此案例是使用 HAS 運算元之全文檢索搜尋的一般化。

  • 會採用符合右側類型的所有屬性，並透過 OR 作業串連產生的運算式。

  • 下表顯示String和Double型別的屬性p1 屬性 p1，以及String和DateTime類型的屬性p2範例：

    述詞字串	對等強型別述詞字串	備註
    = 'abc'	p1.String = 'abc' OR p2.String = 'abc'
    != 'abc'	p1.String != 'abc' AND p2.String != 'abc'	前一個運算式的反轉
    = 1.0	p1.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 = 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'	沒有類型 為 Bool的屬性。

• 如果運算子與屬性名稱一起省略， HAS 則會假設作業。

純量函式

純量函式會 傳回純量值。

原生函式

Azure 時間序列深入解析 Gen1 支援現成的純量函式包括：

函式名稱	傳回值	引數	範例	注意
utcNow	DateTime	無	utcNow ()	傳回 UTC 格式的目前時間。 函式名稱區分大小寫。

UTC 現在函式會傳回DateTime值，其中包含 UTC 格式的目前時間。 它不接受任何引數。

彙總運算式

匯總運算式可用來分割事件集合和計算資料分割上的量值。 匯總運算式分成下列類型：

• 維度運算式
• 唯一值運算式
• 日期長條圖運算式
• 量值運算式

維度運算式

您可以使用aggregates 子句內的維度運算式來分割一組事件，並將純量索引鍵指派給每個分割區。

維度運算式類型：

JSON 中的屬性名稱	描述	範例
uniqueValues	結果中的維度值是指定屬性的確切值。
dateHistogram	結果中的維度值是指定屬性的時間範圍。	時間戳記的日期長條圖可能會導致 10 小時搜尋範圍的 10 小時範圍。
numericHistogram	結果中的維度值是指定屬性中的值範圍。	溫度的數值長條圖可能會導致 10 度範圍的傳回。

Azure 時間序列深入解析 Gen1 會將輸入匯總查詢的最大基數或最大延遲大小限制為 150，000 個數據格。 若要計算匯總查詢的基數，請將查詢中所有維度的大小相乘。 只要產品小於 150，000，查詢就會接受執行。 如果產品等於或小於 150，000，則查詢會遭到拒絕。

您可以使用take子句來指定uniqueValues和numericHistogram所產生的維度大小上限。 在dateHistogram中，會藉由使用breaks子句指定的dateHistogram間隔大小除以搜尋範圍來計算大小。

例如，匯總查詢的搜尋範圍是從 「2017-11-15T16：00：00.000Z」 設定為 「2017-11-15T19：00：00：00.000Z」 = 3 小時。 如果查詢包含具有breaks子句的dateHistogram，請設定為 1 分鐘 (維度 1) ，而 property XYZ 的uniqueValues，dateHistogram維度大小為 3x60=180。 此結果表示 uniqueValues 最多可能需要 150，000/180 = 833 個專案總計。

唯一值運算式

您可以使用唯一 值 運算式，依指定之事件屬性的值來分組一組事件。

評估此 JSON 運算式會產生最多 100 筆記錄，這些記錄是由 sensorIdString屬性分組。

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

量值運算式

您可以使用聚合子句內的量值運算式，在一組事件上計算純量值。 例如，量值運算式是過去 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": {
    "input": {
      "property": "deviceID",
      "type": "String"
    }
  }
}

另一個範例是使用 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"
            }
          }
        }
      ]
    }
  ]
}

另一個範例是 先 使用 來尋找報告每個工廠最低壓力的裝置：

{
  "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) 、 (orderBy、 "last” input)
Double	"uniqueValues", "numericHistogram"	"sum"、 "avg" 、、 "min" 、 "max" ("first" orderBy、input) 、 (orderBy、 "last” input)
String	"uniqueValues"	"first" (輸入) ， "last" (輸入)

子句

子句 形成 JSON 查詢的組成元件或運算式的一部分。 子句分成下列類型：

• 搜尋範圍子句
• 述詞子句
• 限制 top 子句
• 限制 take 子句
• 限制範例子句
• Breaks 子句
• Aggregates 子句

搜尋範圍子句

您可以使用 搜尋範圍 子句，將事件的內建 Timestamp 屬性篩選為指定的間隔。 間隔的開頭是包含的。 間隔結尾是獨佔的。

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

search span 子句中的 from 和 to 屬性 (searchSpan) 應該是 DateTime 結果類型的有效運算式。 這些運算式會在查詢執行之前進行評估，這表示它們不應包含任何屬性參考。

述詞子句

您可以使用 述 詞子句來篩選滿足述詞的事件。 它應該解析為 布林 運算式。

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

若要篩選事件，表示在環境中每個事件上執行布林運算式所表示的述詞。 如果事件必須包含在進一步的作業中，則事件上的運算式執行會傳回 true 。 如果必須從進一步處理中省略事件，則會傳回 false 。

注意

除了述詞運算式中指定的任何篩選之外，事件一律會依搜尋範圍進行篩選。

限制 top 子句

您可以使用 *limit top 子句，以遞增或遞減順序取得指定的值數目。 根據指定的計數限制值數目。

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

限制 take 子句

您可以使用 limit take 子句來快速取得一組沒有特定順序的值。 傳回的值數目受限於指定的輸入。

{ "take": 10 }

限制範例子句

您可以使用 *limit sample 子句，從一組值取得統計代表性樣本。 傳回的值數目受限於指定的輸入。

{ "sample": 10 }

Breaks 子句

您可以使用長條圖運算式中的 *breaks 子句來指定應該如何分割範圍。

針對日期長條圖，您應該指定 datetime interval 和 interval 界限的大小。 除非長條圖是以內建 的 Timestamp 屬性為基礎，而界限是根據搜尋範圍來決定的：

• 間隔界限是選擇性的，而且可以使用。 例如，如果省略間隔界限，您可以根據搜尋範圍來判斷它們時使用它們。
• 針對數值長條圖，您應該指定分隔符號的數目。 您可以根據屬性的最小值和最大值來判斷間隔界限。

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

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

Aggregates 子句

當您測量其他事件屬性的值時，您可以使用 aggregates 子句，依指定的屬性分割一組事件。

量值會在維度運算式所產生的每個資料分割上進行評估。

• 下列 JSON 範例會計算每個感應器識別碼的平均、最小值和最大值。

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

  注意

  • 目前不支援在匯總陣列中有多個元素。
  • 不過，匯總定義可能包含巢狀陣列，指定更有彈性的多維度 Lattice。

• 下列 JSON 範例會計算每分鐘感應器識別碼的平均溫度。

  {
    "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 時間序列深入解析 Gen1 API 的詳細資訊，請參閱Gen1 API。

• 若要瞭解要求和驗證參數，請參閱 驗證和授權。

• 檢閱Gen1 檔，以深入瞭解 Azure 時間序列深入解析 Gen1。