Azure Digital Twins クエリ言語リファレンス: 関数

  • [アーティクル]

このドキュメントには、Azure Digital Twins クエリ言語の関数に関するリファレンス情報が含まれています。

ARRAY_CONTAINS

ツインの配列プロパティ (DTDL v3 でサポートされています) に別の指定値が含まれているかどうかを判断する関数。

構文

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

引数

  • <array-to-check>: 指定した値をチェックする配列型のツイン プロパティ
  • <contained-value>: 配列内のチェックする値を表す文字列、整数、double、ブール値

返品

指定した値が配列に含まれているかどうかを示すブール値。

例

次のクエリは、配列プロパティ 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() は、入れ子にされた配列の内部を検索しません。
    • たとえば、ツインに tags プロパティがあり、その値が [1, [2,3], 3, 4] であるとします。 クエリ 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>: チェック対象の値を表している文字列

返品

2 番目の文字列式で定義された文字のシーケンスが最初の文字列式に含まれているかどうかを示すブール値。

例

次のクエリでは、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>: チェック対象の末尾を表している文字列

返品

1 つ目の文字列式が 2 つ目の文字列式で終了しているかどうかを示すブール値。

例

次のクエリでは、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 演算子の詳細については、「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>: チェック対象のモデル 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 プロパティがプリミティブ型の場合にのみ、ID が 'ABC' のファクトリの 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>: チェック対象の先頭を表す文字列

返品

1 つ目の文字列式が 2 つ目の文字列で始まっているかどうかを示すブール値。

例

次のクエリでは、ID が area1- で始まるすべてのデジタル ツインが返されます。 チェックする文字列はコレクション内の各ツインの $dtId であり、始まりの文字列は area1- です。

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