Azure 数字孪生查询语言参考：函数

本文档包含有关 Azure 数字孪生查询语言函数的参考信息。

ARRAY_CONTAINS

一个函数，用于确定孪生体的数组属性（在 DTDL v3 中受支持）是否包含另一个指定值。

语法

ARRAY_CONTAINS(<array-to-check>,<contained-value>)

参数

• <array-to-check>：要检查其指定值的数组类型的孪生属性
• <contained-value>：字符串、整数、双精度或布尔值，表示数组内要检查的值

返回

一个布尔值，指示数组是否包含指定的值。

示例

下面的查询返回具有数组属性 floor_number 的所有数字双胞胎的名称，并且存储在此属性中的数组包含值 2。

SELECT T.name 
FROM DIGITALTWINS T 
WHERE ARRAY_CONTAINS (T.floor_number, 2)

限制

ARRAY_CONTAINS() 函数具有以下限制：

• 不支持数组索引编制。
  • 例如： array-name[index] = 'foo_bar'
• 不支持 ARRAY_CONTAINS（） 属性中的子查询。
  • 例如： SELECT T.name FROM DIGITALTWINS T WHERE ARRAY_CONTAINS (SELECT S.floor_number FROM DIGITALTWINS S, 4)
• 关系属性不支持ARRAY_CONTAINS（）。
  • 例如，假设 Floor.Contains 是一个从 Floor 到 Room 的关系，它有一个 ["operating", "under maintenance", "under construction"] 值为 lift 的属性。 不支持此类查询： SELECT Room FROM DIGITALTWINS Floor JOIN Room RELATED Floor.Contains WHERE Floor.$dtId = 'Floor-35' AND ARRAY_CONTAINS(Floor.Contains.lift, "operating")
• ARRAY_CONTAINS（） 不搜索嵌套数组。
  • 例如，假设孪生体有一个值为 [1, [2,3], 3, 4] 的属性 tags。 使用查询SELECT * FROM DIGITALTWINS WHERE ARRAY_CONTAINS(tags, 2)的搜索2将False返回 。 搜索顶级数组中的值（如 1 使用查询 SELECT * FROM DIGITALTWINS WHERE ARRAY_CONTAINS(tags, 1)）将 True返回。
• 如果数组包含对象，则不支持 ARRAY_CONTAINS（）。
  • 例如，假设孪生体具有值为 [Room1, Room2] 的 tags 属性，其中 Room1 和 Room2 是对象。 不支持此类查询： SELECT * FROM DIGITALTWINS WHERE ARRAY_CONTAINS(tags, Room2)

CONTAINS

一个字符串函数，用于确定孪生的字符串属性是否包含另一个指定的字符串值。

语法

CONTAINS(<string-to-check>,<contained-string>)

自变量

• <string-to-check>：要检查其指定值的字符串类型的孪生属性
• <contained-string>：表示要检查的值的字符串

返回

一个布尔值，指示第一个字符串表达式是否包含第二个字符串表达式中定义的字符序列。

示例

以下查询返回 ID 包含 -route 的所有数字孪生。 要检查的字符串是集合中每个孪生的 $dtId，而包含的字符串是 -route。

SELECT *
FROM DIGITALTWINS T
WHERE CONTAINS(T.$dtId, '-route')

ENDSWITH

一个字符串函数，用于确定孪生的字符串属性是否以另一个特定字符串结尾。

语法

ENDSWITH(<string-to-check>,<ending-string>)

自变量

• <string-to-check>：要检查其结尾部分的字符串类型的孪生属性
• <ending-string>：表示要检查的结尾内容的字符串

返回

一个布尔值，该值指示第一个字符串表达式是否以第二个字符串表达式结尾。

示例

下面的查询返回所有 ID 以 -small 结尾的数字孪生体。 要检查的字符串是集合中每个孪生的 $dtId，而结尾字符串是 -small。

SELECT *
FROM DIGITALTWINS T
WHERE ENDSWITH(T.$dtId, '-small')

IS_BOOL

用于确定属性是否具有布尔值的类型检查函数。

如果处理查询结果的程序需要布尔值，并且你想要筛选出属性不是布尔值的事例，则此函数通常与其他谓词组合在一起。

语法

IS_BOOL(<property>)

参数

<property>，一个属性，用于检查它是否为布尔值。

返回

一个布尔值，该值指示指定属性的类型是否为布尔值。

示例

下面的查询选择具有布尔属性 HasTemperature 的数字孪生体。

SELECT *
FROM DIGITALTWINS T
WHERE IS_BOOL( HasTemperature )

以下查询基于上面的示例来选择具有布尔 HasTemperature 属性的数字孪生体，并且该属性的值不是 false。

SELECT *
FROM DIGITALTWINS T
WHERE IS_BOOL( HasTemperature ) AND HasTemperature != false

IS_DEFINED

一种类型检查函数，用于确定是否定义了某个属性。

语法

IS_DEFINED(<property>)

参数

<property>，用于确定它是否定义的属性。

返回

一个布尔值，该值指示属性是否已经分配了值。

示例

下面的查询返回所有定义了 Location 属性的数字孪生体。

SELECT *
FROM DIGITALTWINS
WHERE IS_DEFINED(Location)

IS_NULL

用于确定属性的值null的类型检查函数。

语法

IS_NULL(<property>)

参数

<property>，一个属性，用于检查它是否为 null。

返回

一个布尔值，该值指示指定属性的类型是否为 null。

示例

下面的查询返回 Temperature 不为 null 值的孪生体。 有关此查询中使用的 NOT 运算符的详细信息，请参阅 NOT。

SELECT *
FROM DIGITALTWINS T
WHERE NOT IS_NULL(T.Temperature)

IS_NUMBER

一种类型检查函数，用于确定属性是否具有数值。

如果处理查询结果的程序需要数字值，并且你想要筛选出属性不是数字的情况，则此函数通常与其他谓词组合在一起。

语法

IS_NUMBER(<property>)

参数

<property>，一个属性，用于检查它是否为数字。

返回

一个布尔值，该值指示指定属性的类型是否为数字。

示例

以下查询选择具有数字 Capacity 属性的数字孪生体及其值不等于 0。

SELECT * 
FROM DIGITALTWINS 
WHERE IS_NUMBER( Capacity ) AND Capacity != 0

IS_OBJECT

用于确定属性的值是否为 JSON 对象类型的类型检查函数。

如果处理查询结果的程序需要 JSON 对象，并且你想要筛选出值不是 JSON 对象的事例，则此函数通常与其他谓词组合在一起。

语法

IS_OBJECT<property>)

参数

<property>，一个属性，用于检查它是否为对象类型。

返回

一个布尔值，该值指示指定属性的类型是否为 JSON 对象。

示例

以下查询选择所有数字孪生体，其中这是一个调用 MapObject的对象，并且它没有子属性 TemperatureReading。

SELECT * 
FROM DIGITALTWINS 
WHERE IS_OBJECT( MapObject ) AND NOT IS_DEFINED ( MapObject.TemperatureReading )

IS_OF_MODEL

用于确定孪生体是否属于特定模型类型的检查和函数。 包括从指定模型继承的模型。

语法

IS_OF_MODEL(<twin-collection>,'<model-ID>', exact)

参数

必需：

• <model-ID>：要检查的模型 ID。

可选：

• <twin-collection>：指定一个孪生集合，以在有多个集合（如使用时 JOIN ）进行搜索。
• exact：需要完全匹配。 如果未设置此参数，结果集将包含从指定模型继承的模型的孪生体。

返回

一个布尔值，该值指示指定的孪生体是否与指定的模型类型匹配。

示例

下面的查询返回 DT 集合中完全属于 dtmi:example:room;1 模型类型的孪生体。

SELECT ROOM FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:room;1', exact)

IS_PRIMITIVE

用于确定属性的值是否为基元类型（字符串、布尔值、数值或 null）的类型检查函数。

如果处理查询结果的程序需要基元类型值，并且你想要筛选出属性不是基元的事例，则此函数通常与其他谓词组合在一起。

语法

IS_PRIMITIVE(<property>)

参数

<property>，一个属性，用于检查它是否为基元类型。

返回

一个布尔值，该值指示指定属性的类型是否为基元类型（字符串、布尔、数值或 null）。

示例

下面的查询返回 ID 为“ABC”的 Factory 的 area 属性（仅当 area 属性为基元类型时）。 若要详细了解如何在查询结果中投影某些列（如此查询对 area 的投影），请参阅 area。

SELECT Factory.area
FROM DIGITALTWINS Factory
WHERE Factory.$dtId = 'ABC'
AND IS_PRIMITIVE(Factory.area)

IS_STRING

一种类型检查函数，用于确定属性是否具有字符串值。

如果处理查询结果的程序需要字符串值，并且你想要筛选出属性不是字符串的情况，则此函数通常与其他谓词组合在一起。

语法

IS_STRING(<property>)

参数

<property>，用于检查它是否为字符串的属性。

返回

一个布尔值，该值指示指定表达式的类型是否为字符串。

示例

以下查询选择具有字符串属性属性 Status 的数字孪生，其值不等于 Completed。

SELECT * 
FROM DIGITIALTWINS 
WHERE IS_STRING( Status ) AND Status != 'Completed'

STARTSWITH

一个字符串函数，用于确定孪生的字符串属性是否以另一个特定字符串开头。

语法

STARTSWITH(<string-to-check>,<beginning-string>)

自变量

• <string-to-check>：要检查其开头部分的字符串类型的孪生属性
• <beginning-string>：表示要检查的开头内容的字符串

返回

一个布尔值，该值指示第一个字符串表达式是否以第二个字符串表达式开头。

示例

下面的查询返回所有 ID 以 area1- 开头的数字孪生体。 要检查的字符串是集合中每个孪生的 $dtId，而开头字符串是 area1-。

SELECT *
FROM DIGITALTWINS T
WHERE STARTSWITH(T.$dtId, 'area1-')