共用方式為

Azure Digital Twins 查詢語言參考：函式

  • 發行項

本文件包含 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 的關聯性，而且其具有值為 ["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。 搜尋最上層陣列中的值，例如使用查詢 SELECT * FROM DIGITALTWINS WHERE ARRAY_CONTAINS(tags, 1) 的 1 會傳回 True。
  • 如果陣列包含物件，則不支援 ARRAY_CONTAINS()。
    • 例如，假設對應項具有 tags 屬性，其值為 [Room1, Room2]，其中 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。

範例

下列查詢會傳回其溫度沒有 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 屬性是基本類型時，下列查詢才會傳回識別碼為 'ABC' 的 Factory 的 area 屬性。 如需在查詢結果中投影特定資料行的詳細資訊 (像此查詢對 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-')