Azure 时序见解 Gen1 查询语法

本文介绍 Azure 时序见解 Gen1 查询 API 的查询请求格式和语法。

摘要

语言细分为以下元素：

• 生成标量值的标量表达式。 标量表达式包括 谓词字符串表达式、 比较表达式和 算术表达式。
• 返回标量值的标量函数。
• 聚合 表达式，用于对事件集合进行分区，并针对分区计算度量值。
• 子句，构成 JSON 查询的组成部分或表达式的一部分。

数据模型

Azure 时序见解 Gen1 查询 API 对存储在环境中的单个事件的数据进行操作。 每个事件都是一组属性名称和值对。

事件属性

事件属性可以是下列基元类型之一： Bool、 DateTime、 Double 或 String。 所有基元类型都是可以为 null 的。

所有事件都具有以下内置属性，具有预定义的名称和类型：

• 事件时间戳

  默认情况下，事件时间戳值由事件源提供。 例如，来自 IoT 中心的事件的排队时间将作为时间戳。

  客户可以通过配置另一个事件属性来修改此行为。 可以在 事件 中心和 IoT 中心指定自定义时间戳属性。

• 事件源名称

  事件源名称是为事件源显示的名称，Azure 时序见解 Gen1 从中接收事件。 事件源名称在入口时与特定事件相关联。

  重要

  • 事件源名称在事件的生存期内保持不变。
  • 如果修改了事件源的名称，则现有事件将携带旧的事件源名称。 新事件将包含新的事件源名称。

事件类型

自定义事件属性在查询表达式中按名称和类型进行唯一标识和引用。 一个事件可以有多个具有相同名称和不同类型的属性。 同名但类型不同的属性可能因入口类型拆分而产生。

在以下情况下， 字符串 类型的事件属性值可以存储为具有不同类型的属性：

• 如果 String 值是有效的 Double 值，则它同时存储为 Double 和 String。
• 如果 String 值是有效的 DateTime 值，则它仅存储为 DateTime 。

查询 API 将输出中的空 字符串 文本 ("") 转换为 null 。

Azure 时序见解 Gen1 对 Double 类型中的以下值的支持有限：Double.NaN、 Double.PositiveInfinity和 Double.NegativeInfinity。 这些值在入口期间转换为 null ，但如果查询评估生成其中一个值，则会计算该值并将其序列化为 字符串 作为响应。

可以将这些值作为 入口的字符串 传递，因此在查询表达式中，这些值也应作为 字符串传递。

事件架构描述 事件的属性。 事件架构包含事件源的名称和事件的有序属性集。 不同的事件可以具有不同的架构或共享相同的架构。

标量表达式

标量 表达式生成标量值。 标量表达式分为以下几种：

• 常量表达式
• 属性引用表达式
• 比较表达式
• 算术表达式
• 谓词字符串表达式

常量表达式

通过为每个基元类型使用以下文本来表示 常量 表达式：

可以为 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" }

比较表达式

支持以下 布尔比较 表达式：

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

下表显示了每个比较表达式支持的参数类型：

NULL 文本只能与以下比较运算符一起使用：eq 或 in。

• 如果两端都是值，null则 eq 运算符会导致 true 。 否则， 运算符将生成 false。
• 对于其他操作，将针对 NULL 文本引发错误，并且 null 值属性的行为未定义 (导致 false) 的任何比较操作。
• null例如，如果应用按属性排序以返回) 事件列表，则值在排序顺序 (非 null 值之前。

Azure 时序见解 Gen1 支持以下布尔逻辑表达式：

{
  "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 支持以下算术表达式：

所有算术表达式都采用基元类型的左参数和右参数，并返回表示运算结果的值。

所有类型仅隐式转换为自身，不支持显式强制转换。

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

下表显示了每个算术表达式支持的参数类型：

谓词字符串表达式

布尔谓词字符串 表达式包含布尔谓词，这些谓词表示为称为 谓词字符串的可读表达式。

谓词字符串的示例：

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

谓词字符串中的表达式计算为 JSON 布尔表达式。 它应符合以下 (简化) 语法：

Azure 时序见解第 1 代基元数据类型在谓词字符串表达式中受支持。

与 JSON 属性引用表达式不同，可以省略属性的类型，在这种情况下，会自动推断类型。

支持的文本

支持的操作数类型

对于比较谓词，< (、>、<、=、=>、！=) 和 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	是
    p1.String = NULL	是	NULL 匹配任何左侧类型。
    p3.Double = 'abc'	否	类型不匹配。
    p3.Double = p1.String	否	类型不匹配。
    p1.String HAS 'abc'	是
    p3.Double HAS '1.0'	是	字符串文本已成功解析为 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 以及 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		错误。 不存在 布尔 属性，因此发出缺少属性错误。
    = 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 现成支持的标量函数包括：

UTC 函数现在返回 DateTime 值，该值包含 UTC 格式的当前时间。 它不接受任何参数。

聚合表达式

聚合表达式用于对事件集合进行分区，并计算分区上的度量值。 聚合表达式分为以下几种：

• 维度表达式
• 唯一值表达式
• 日期直方图表达式
• 度量值表达式

维度表达式

在聚合子句中使用维度表达式对一组事件进行分区，并为每个分区分配标量键。

维度表达式类型：

Azure 时序见解 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， (维度 1) 设置为 1 分钟，在属性 XYZ 上设置为 uniqueValues，则 dateHistogram 维度大小为 3x60=180。 此结果意味着 uniqueValues 最多可占用 150，000/180 = 833 个项。

唯一值表达式

使用唯一 值 表达式按指定事件属性的值对一组事件进行分组。

此 JSON 表达式的计算结果最多包含 100 条记录，这些记录按 sensorIdString 属性分组。

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

日期直方图表达式

使用 日期直方图 表达式将 DateTime 属性值分组到指定大小的存储桶中。

对此 JSON 表达式的求值会生成一组以下限舍入的 Timestamp 记录，以便每个值将秒数归零。

{
  "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 是用于标识该信息的最有效表达式运算符。

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

维度和度量值类型支持

下面是基于属性类型的支持的维度和度量值表达式：

子句

子句 构成 JSON 查询的组成部分或表达式的一部分。 子句分为以下几种：

• 搜索范围子句
• 谓词子句
• 限制 top 子句
• 限制 take 子句
• 限制示例子句
• 断句
• 聚合子句

搜索范围子句

使用 search span 子句将事件的内置 Timestamp 属性筛选为给定间隔。 间隔的开始是非独占的。 间隔结束是独占的。

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

searchSpan () searchSpan 子句中的 from 和 to 属性应该是 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 子句来指定区域应如何划分。

对于日期直方图，应指定日期时间间隔和间隔边界的大小。 除非直方图基于基于基于搜索范围确定边界的内置 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 的平均温度。

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