Azure Digital Twins 查詢語言參考：Functions

  • 發行項

本檔包含 Azure Digital Twins 查詢語言 函式的 參考資訊。

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 的關聯性，而且其具有 lift 值為 ["operating", "under maintenance", "under construction"] 的屬性。 不支援這類查詢： SELECT Room FROM DIGITALTWINS Floor JOIN Room RELATED Floor.Contains WHERE Floor.$dtId = 'Floor-35' AND ARRAY_CONTAINS(Floor.Contains.lift, "operating") 。
  • ARRAY_CONTAINS（） 不會在巢狀陣列內搜尋。
    • 例如，假設對應項具有 tags 值為 的屬性 [1, [2,3], 3, 4] 。 使用查詢 SELECT * FROM DIGITALTWINS WHERE ARRAY_CONTAINS(tags, 2) 的 2 搜尋會傳 False 回 。 搜尋最上層陣列中的值，例如 1 使用查詢 SELECT * FROM DIGITALTWINS WHERE ARRAY_CONTAINS(tags, 1) ，會傳 True 回 。
  • 如果陣列包含 物件，則不支援ARRAY_CONTAINS（）。
    • 例如，假設對應項具有 tags 屬性，其值為 [Room1, Room2] where Room1 和 Room2 是 物件。 不支援這類查詢： SELECT * FROM DIGITALTWINS WHERE ARRAY_CONTAINS(tags, Room2) 。

CONTAINS

字串函式，判斷對應項的字串屬性是否包含另一個指定的字串值。

語法

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

引數

  • <string-to-check>：您想要檢查指定值的字串類型對應項屬性
  • <contained-string>：字串，表示要檢查的值

傳回

布林值，指出第一個字串運算式是否包含第二個字串運算式中定義的字元序列。

範例

下列查詢會傳回識別碼包含 -route 的所有數位對應項。 要檢查的字串是 $dtId 集合中每個對應項的 ，而包含的字串為 -route 。

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

ENDSWITH

字串函式，判斷對應項的字串屬性是否以特定其他字串結尾。

語法

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

引數

  • <string-to-check>：您想要檢查結尾的字串類型對應項屬性
  • <ending-string>：字串，表示要檢查的結尾

傳回

布林值，指出第一個字串運算式是否以第二個字串運算式結尾。

範例

下列查詢會傳回識別碼以 -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 ，請參閱 Azure Digital Twins 查詢語言參考：運算子 。

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>：要檢查的模型識別碼。

選擇性：

  • <twin-collection>：指定當有多個對應項集合時要搜尋的集合（例如使用 時 JOIN ）。
  • exact：需要完全相符的專案。 如果未設定此參數，結果集會包含具有繼承自指定模型之模型的對應項。

傳回

布林值，指出指定的對應項是否符合指定的模型類型。

範例

下列查詢會從完全屬於模型類型的 dtmi:example:room;1 DT 集合傳回對應項。

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

IS_PRIMITIVE

型別檢查函式，用於判斷屬性值是否為基本類型（字串、布林值、數值或 null ）。

如果處理查詢結果的程式需要基本類型值，而且您想要篩選出屬性不是基本類型的案例，此函式通常會與其他述詞結合。

語法

IS_PRIMITIVE(<property>)

引數

<property>，用來檢查其是否為基本型別的屬性。

傳回

布林值，指出指定屬性的類型是否為其中一個基本類型（字串、布林值、數值或 null ）。

範例

只有在屬性是基本類型時 area ，下列查詢才會傳回 area 識別碼為 'ABC' 的 Factory 屬性。 如需在查詢結果中投影特定資料行的詳細資訊， area 請參閱 Azure Digital Twins 查詢語言參考：SELECT 子句 。

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>：字串，表示要檢查的開頭

傳回

布林值，指出第一個字串運算式是否以第二個開頭。

範例

下列查詢會傳回識別碼開頭 area1- 為 的所有數位對應項。 要檢查的字串是 $dtId 集合中每個對應項的 ，而開頭字串為 area1- 。

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