Azure Digital Twins 쿼리 언어 참조: Functions

  • 아티클

이 문서에는 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()는 중첩된 배열 내에서 검색하지 않습니다.
    • 예를 들어 트윈에 값이 [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()는 지원되지 않습니다.
    • 예를 들어 트윈에는 Room1 및 Room2가 개체인 [Room1, Room2] 값을 갖는 tags 속성이 있다고 가정합니다. 이와 같은 쿼리는 지원되지 않습니다. 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인지 여부를 나타내는 부울 값입니다.

예시

다음 쿼리는 온도에 대해 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>: 확인할 시작을 나타내는 문자열

반환

첫 번째 문자열 식이 두 번째 문자열 식으로 시작하는지 여부를 나타내는 부울 값입니다.

예시

다음 쿼리는 해당 ID가 area1-로 시작하는 모든 디지털 트윈을 반환합니다. 확인할 문자열은 컬렉션에 있는 각 트윈의 $dtId이며 시작 문자열은 area1-입니다.

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