Azure Digital Twins 트윈 그래프 쿼리

이 문서에서는 Azure Digital Twins 쿼리 언어를 사용하여 트윈 그래프에서 정보를 쿼리하는 방법에 대한 쿼리 예제와 지침을 제공합니다. (쿼리 언어에 대한 소개는 다음을 참조하세요 .쿼리 언어입니다.)

이 문서에는 디지털 트윈에 대한 쿼리 언어 구조 및 일반적인 쿼리 작업을 보여 주는 샘플 쿼리가 포함되어 있습니다. 쿼리를 작성한 후 Azure Digital Twins 쿼리 API 또는 SDK를 사용하여 쿼리를 실행하는 방법도 설명합니다.

참고 항목

API 또는 SDK 호출을 사용하여 아래 샘플 쿼리를 실행하는 경우 쿼리 텍스트를 한 줄로 압축해야 합니다.

참조 설명서

쿼리 언어 참조는 Azure Digital Twins 설명서의 왼쪽 목차에 있는 참조에서 찾을 수 있습니다. 아래 링크를 사용하여 참조 섹션으로 직접 이동할 수도 있습니다.

• 절
  • SELECT
  • FROM
  • MATCH
  • JOIN
  • WHERE
• 함수
• 연산자
• 예약 키워드

모든 디지털 트윈 표시

인스턴스의 모든 디지털 트윈 목록을 반환하는 기본 쿼리는 다음과 같습니다.

SELECT * FROM DIGITALTWINS

속성별 쿼리

속성(ID 및 메타 데이터 포함)별로 디지털 트윈을 가져옵니다.

SELECT  *
FROM DIGITALTWINS T  
WHERE T.firmwareVersion = '1.1'
AND T.$dtId in ['123', '456']
AND T.Temperature = 70

위의 쿼리에 표시된 것처럼 디지털 트윈의 ID는 메타데이터 필드 $dtId를 사용하여 쿼리됩니다.

팁

Cloud Shell을 사용하여 $로 시작하는 메타데이터 필드로 쿼리를 실행하는 경우 Cloud Shell에서 이 필드가 변수가 아니고 쿼리 텍스트에서 리터럴로 사용되어야 함을 인식할 수 있도록 $를 백슬래시로 이스케이프해야 합니다.

또한 특정 속성이 정의되었는지 여부에 따라 트윈을 가져올 수 있습니다. 다음은 정의된 Location 속성이 있는 트윈을 가져오는 쿼리입니다.

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

이 쿼리는 디지털 트윈에 태그 추가에 설명된 대로 tag 속성별로 트윈을 가져오는 데 도움이 될 수 있습니다. 다음은 태그가 지정된 모든 트윈을 가져오는 쿼리입니다.red

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

속성의 형식에 따라 트윈을 가져올 수도 있습니다. 다음은 속성이 숫자인 Temperature 트윈을 가져오는 쿼리입니다.

SELECT * FROM DIGITALTWINS​ T WHERE IS_NUMBER(T.Temperature)

쿼리 맵 속성

속성이 복합 형식 Map인 경우 다음과 같이 쿼리에서 직접 맵 키와 값을 사용할 수 있습니다.

SELECT * FROM DIGITALTWINS​ T WHERE T.<propertyName>.<mapKey> = '<mapValue>'

맵 키가 숫자 문자로 시작하는 경우 예약된 키워드를 사용하여 쿼리하는 전략과 유사하게 쿼리에서 이스케이프하려면 키를 이중 대괄호([[<mapKey>]])로 래핑해야 합니다.

모델별 쿼리

연산자를 IS_OF_MODEL 사용하여 트윈의 모델을 기준으로 필터링할 수 있습니다.

상속 및 모델 버전 관리가 고려되며 트윈이 다음 조건 중 하나를 충족하는 true 경우 지정된 트윈에 대해 평가됩니다.

• 트윈은 제공된 IS_OF_MODEL()모델을 직접 구현하고 트윈에 있는 모델의 버전 번호가 제공된 모델의 버전 번호보다 크거나 같음
• 트윈은 제공된 IS_OF_MODEL()모델을 확장하는 모델을 구현하고 트윈의 확장 모델 버전 번호가 제공된 모델의 버전 번호보다 크거나 같음

예를 들어 모델 dtmi:example:widget;4의 트윈을 쿼리하면 쿼리가 버전 4 이상의 위젯 모델을 기반으로 하는 모든 트윈을 반환하고, 위젯에서 상속되는 모든 모델의 버전 4 이상을 기반으로 하는 트윈도 반환합니다.

IS_OF_MODEL 는 여러 다른 매개 변수를 사용할 수 있으며, 이 섹션의 나머지 부분은 다른 오버로드 옵션 전용입니다.

가장 간단한 사용 IS_OF_MODEL 은 매개 변수IS_OF_MODEL(twinTypeName)만 twinTypeName 사용합니다. 다음은 이 매개 변수의 값을 전달하는 쿼리 예제입니다.

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1')

둘 이상의 경우 검색할 트윈 컬렉션을 지정하려면(예: 사용되는 경우JOIN) 매개 변수IS_OF_MODEL(twinCollection, twinTypeName)를 twinCollection 추가합니다. 다음은 이 매개 변수의 값을 추가하는 쿼리 예입니다.

SELECT * FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:thing;1')

정확히 일치하려면 매개 변수를 exact 추가합니다 IS_OF_MODEL(twinTypeName, exact). 다음은 이 매개 변수의 값을 추가하는 쿼리 예입니다.

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1', exact)

세 인수를 모두 함께 IS_OF_MODEL(twinCollection, twinTypeName, exact)전달할 수도 있습니다. 다음은 세 매개 변수 모두에 대한 값을 지정하는 쿼리 예제입니다.

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

관계별 쿼리

디지털 트윈의 관계를 기반으로 쿼리하는 경우 Azure Digital Twins 쿼리 언어에 특수 구문이 사용됩니다.

관계는 FROM 절의 쿼리 범위로 가져옵니다. "클래식" SQL 형식 언어와 달리 절의 FROM 각 식은 테이블 FROM 이 아니라 엔터티 간 관계 통과를 표현합니다. 관계를 트래버스하기 위해 Azure Digital Twins는 사용자 지정 버전의 JOIN.를 사용합니다.

Azure Digital Twins 모델 기능을 사용하면 관계가 트윈과 독립적으로 존재하지 않습니다. 즉, 여기서의 관계는 독립적으로 쿼리할 수 없으며 트윈에 연결되어야 합니다. 이 사실을 반영하기 위해 키워드 RELATED 는 쌍 컬렉션에서 오는 특정 유형의 관계 집합을 끌어오기 위해 절에 사용됩니다 JOIN . 그런 다음 쿼리는 WHERE 절에서 필터링하여 관계 쿼리에서 사용할 특정 트윈을 표시해야 합니다(트윈의 $dtId 값 사용).

다음 섹션에서는 이러한 모양에 대한 예제를 제공합니다.

기본 관계 쿼리

다음은 샘플 관계 기반 쿼리입니다. 이 코드 조각은 ID 속성이 ABC인 모든 디지털 트윈을 선택하고 contains 관계를 통해 이러한 디지털 트윈과 관련된 모든 디지털 트윈을 선택합니다.

SELECT T, CT
FROM DIGITALTWINS T
JOIN CT RELATED T.contains
WHERE T.$dtId = 'ABC'

관계의 형식(contains위 예제에서)은 해당 DTDL 정의의 name관계 필드를 사용하여 표시됩니다.

참고 항목

개발자는 이를 JOIN 절의 키 값 WHERE 과 상호 연결하거나 정의와 JOIN 인라인으로 키 값을 지정할 필요가 없습니다. 관계 속성 자체가 대상 엔터티를 식별하기 때문에 이 상관 관계는 시스템에서 자동으로 컴퓨팅됩니다.

관계의 원본 또는 대상별 쿼리

관계 쿼리 구조를 사용하여 관계의 원본 또는 대상인 디지털 트윈을 식별할 수 있습니다.

예를 들어 원본 트윈으로 시작하고 해당 관계를 따라 관계의 대상 쌍을 찾을 수 있습니다. 다음은 트윈 소스 쌍에서 오는 관계의 대상 쌍을 feeds 찾는 쿼리의 예입니다.

SELECT target 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE source.$dtId = 'source-twin'

관계의 대상으로 시작하고 관계를 다시 추적하여 원본 쌍을 찾을 수도 있습니다. 다음은 트윈 대상 쌍에 대한 관계의 원본 쌍을 feeds 찾는 쿼리의 예입니다.

SELECT source 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE target.$dtId = 'target-twin'

관계의 속성 쿼리

디지털 트윈이 DTDL을 통해 설명한 속성을 갖는 방식과 마찬가지로 관계에도 속성이 있을 수 있습니다. 해당 관계의 속성을 기반으로 트윈을 쿼리할 수 있습니다. Azure Digital Twins 쿼리 언어는 JOIN 절 내에서 관계에 별칭을 할당하여 관계의 필터링 및 프로젝션을 허용합니다.

예를 들어 속성이 있는 servicedByreportedCondition 관계를 고려해 보세요. 아래 쿼리에서는 속성을 참조하기 위해 이 관계에 별칭 R을 지정합니다.

SELECT T, SBT, R
FROM DIGITALTWINS T
JOIN SBT RELATED T.servicedBy R
WHERE T.$dtId = 'ABC'
AND R.reportedCondition = 'clean'

위의 예제에서는 관계 자체의 servicedBy 속성이 어떻게 되는지 reportedCondition 확인합니다(관계가 있는 일부 디지털 트윈의 속성은 servicedBy 아님).

여러 JON을 사용하여 쿼리

단일 쿼리에서 최대 5 JOIN개의 s가 지원되므로 한 번에 여러 수준의 관계를 트래버스할 수 있습니다.

여러 수준의 관계를 쿼리하려면 단일 FROM 문 뒤에 N JOIN 문을 사용합니다. 여기서 JOIN 문은 이전 FROM 또는 JOIN 문의 결과에 대한 관계를 표현합니다.

다음은 회의실 1과 2의 조명 패널에 포함된 모든 전구를 가져오는 다중 조인 쿼리의 예입니다.

SELECT LightBulb
FROM DIGITALTWINS Room
JOIN LightPanel RELATED Room.contains
JOIN LightBulb RELATED LightPanel.contains
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb ;1')
AND Room.$dtId IN ['room1', 'room2']

항목 개수

절을 사용하여 결과 집합의 항목 수를 계산할 수 있습니다.Select COUNT

SELECT COUNT()
FROM DIGITALTWINS

WHERE 특정 조건을 충족하는 항목 수를 계산하는 절을 추가합니다. 다음은 트윈 모델 유형에 따라 적용된 필터로 계산하는 몇 가지 예입니다(이 구문에 대한 자세한 내용은 아래 모델별 쿼리 참조).

SELECT COUNT()
FROM DIGITALTWINS
WHERE IS_OF_MODEL('dtmi:sample:Room;1')

SELECT COUNT()
FROM DIGITALTWINS c
WHERE IS_OF_MODEL('dtmi:sample:Room;1') AND c.Capacity > 20

절과 함께 JOIN 사용할 COUNT 수도 있습니다. 다음은 회의실 1과 2의 조명 패널에 포함된 모든 전구를 계산하는 쿼리입니다.

SELECT COUNT()  
FROM DIGITALTWINS Room  
JOIN LightPanel RELATED Room.contains  
JOIN LightBulb RELATED LightPanel.contains  
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')  
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb;1')  
AND Room.$dtId IN ['room1', 'room2']

결과 필터링: 상위 항목 선택

Select TOP 절을 사용하여 쿼리의 여러 "최상위" 항목을 선택할 수 있습니다.

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

결과 필터링: 프로젝션을 사용하여 반환 집합 지정

문에서 프로젝션을 SELECT 사용하여 쿼리가 반환할 열을 선택할 수 있습니다. 이제 기본 속성과 복합 속성 모두에 프로젝션이 지원됩니다. Azure Digital Twins를 사용한 프로젝션에 대한 자세한 내용은 SELECT 절 참조 설명서를 참조 하세요.

다음은 프로젝션을 사용하여 트윈과 관계를 반환하는 쿼리의 예입니다. 다음 쿼리는 ID가 ABC인 Factory가 Factory.customer의 관계를 통해 Consumer와 관련이 있는 시나리오에서 Consumer, Factory 및 Edge를 프로젝션하고, 해당 관계는 Edge로 표시됩니다.

SELECT Consumer, Factory, Edge
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

프로젝션을 사용하여 트윈의 속성을 반환할 수도 있습니다. 다음 쿼리는 팩터리에 관련된 소비자의 속성을 관계를 Factory.customer통한 ID ABC 로 프로젝션 Name 합니다.

SELECT Consumer.name
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

프로젝션을 사용하여 관계의 속성을 반환할 수도 있습니다. 이전 예제와 마찬가지로 다음 쿼리는 팩터리와 관련된 소비자의 속성을 관계를 통한 ID ABC 로 프로젝션 Name 하지만, 이제는 해당 관계의 prop1 두 속성도 반환합니다prop2.Factory.customer 관계의 이름을 지정 Edge 하고 해당 속성을 수집하여 이 작업을 수행합니다.

SELECT Consumer.name, Edge.prop1, Edge.prop2, Factory.area
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

별칭을 사용하여 프로젝션으로 쿼리를 간소화할 수도 있습니다.

다음 쿼리는 이전 예제와 동일한 작업을 수행하지만 속성 이름을 consumerName, firstsecond및 factoryArea에 별칭으로 지정합니다.

SELECT Consumer.name AS consumerName, Edge.prop1 AS first, Edge.prop2 AS second, Factory.area AS factoryArea
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

다음은 위와 동일한 집합을 쿼리하지만 속성을 로만 Consumer.name 프로젝트하고 전체 팩터리를 쌍으로 consumerName프로젝터하는 유사한 쿼리입니다.

SELECT Consumer.name AS consumerName, Factory
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

IN 연산자를 사용하여 효율적인 쿼리 빌드

트윈 배열을 빌드하고 IN 연산자로 쿼리하여 필요한 쿼리 수를 크게 줄일 수 있습니다.

예를 들어 Buildings에 Floors가 포함되고 Floors에 Rooms가 포함되는 시나리오를 생각해보겠습니다. 뜨거운 건물 내에서 방을 검색하려면 다음 단계를 수행하는 것이 한 가지 방법입니다.

1. 관계에 따라 건물의 바닥을 찾습니다 contains .

   SELECT Floor
   FROM DIGITALTWINS Building
   JOIN Floor RELATED Building.contains
   WHERE Building.$dtId = @buildingId
   

2. 방을 찾으려면 층을 하나씩 고려하고 쿼리를 JOIN 실행하여 각 객실을 찾는 대신 건물의 바닥 컬렉션을 사용하여 쿼리할 수 있습니다(아래 쿼리에서는 Floor).

   클라이언트 앱에서:

   var floors = "['floor1','floor2', ..'floorn']"; 
   

   쿼리에서:

   SELECT Room
   FROM DIGITALTWINS Floor
   JOIN Room RELATED Floor.contains
   WHERE Floor.$dtId IN ['floor1','floor2', ..'floorn']
   AND Room. Temperature > 72
   AND IS_OF_MODEL(Room, 'dtmi:com:contoso:Room;1')
   

기타 복합 쿼리 예제

조합 연산자를 사용하여 위의 쿼리 유형을 결합하여 단일 쿼리에 더 많은 세부 정보를 포함할 수 있습니다. 다음은 한 번에 둘 이상의 트윈 설명자를 쿼리하는 복합 쿼리의 몇 가지 다른 예입니다.

• Room 123에 있는 장치에서 운영자 역할을 수행하는 MxChip 디바이스를 반환합니다.

  SELECT device
  FROM DIGITALTWINS space
  JOIN device RELATED space.has
  WHERE space.$dtid = 'Room 123'
  AND device.$metadata.model = 'dtmi:contoso:com:DigitalTwins:MxChip:3'
  AND has.role = 'Operator'
  

• ID가 있는 다른 트윈과 이름이 지정된 Contains 관계가 있는 트윈을 가져옵니다. id1

  SELECT Room
  FROM DIGITALTWINS Room
  JOIN Thermostat RELATED Room.Contains
  WHERE Thermostat.$dtId = 'id1'
  

• floor11에 포함된 이 객실 모델의 모든 객실을 가져옵니다.

  SELECT Room
  FROM DIGITALTWINS Floor
  JOIN Room RELATED Floor.Contains
  WHERE Floor.$dtId = 'floor11'
  AND IS_OF_MODEL(Room, 'dtmi:contoso:com:DigitalTwins:Room;1')
  

API를 사용하여 쿼리 실행

쿼리 문자열을 결정한 후에는 쿼리 API를 호출하여 실행합니다.

API를 직접 호출하거나 Azure Digital Twins에 사용할 수 있는 SDK 중 하나를 사용할 수 있습니다.

다음 코드 조각은 클라이언트 앱의 .NET(C#) SDK 호출을 보여 줍니다.

// Run a query for all twins   
string query = "SELECT * FROM DIGITALTWINS";
AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>(query);

이 호출에 사용된 쿼리는 디지털 트윈 목록을 반환합니다. 위의 예는 BasicDigitalTwin 개체를 나타냅니다. 각 쿼리에 대한 데이터 반환 형식은 문으로 SELECT 지정한 용어에 따라 달라집니다.

• SELECT * FROM ...으로 시작하는 쿼리는 디지털 트윈 목록을 반환합니다(BasicDigitalTwin 개체 또는 사용자가 만든 기타 사용자 정의 디지털 트윈 형식으로 직렬화될 수 있음).
• SELECT <A>, <B>, <C> FROM ... 형식으로 시작하는 쿼리는 <A>, <B> 및 <C> 키가 있는 사전을 반환합니다.
• 다른 형식의 SELECT 문은 사용자 지정 데이터를 반환하도록 만들 수 있습니다. 사용자 지정된 결과 집합을 처리하기 위해 고유한 클래스를 만드는 것이 좋습니다.

페이징을 사용하여 쿼리

쿼리 호출은 페이징을 지원합니다. 다음은 오류 처리 및 페이징과 함께 BasicDigitalTwin를 쿼리 결과 유형으로 사용하는 전체 예입니다.

AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>("Select * From DigitalTwins");
try
{
    await foreach (BasicDigitalTwin twin in result)
    {
        // You can include your own logic to print the result
        // The logic below prints the twin's ID and contents
        Console.WriteLine($"Twin ID: {twin.Id} \nTwin data");
        foreach (KeyValuePair<string, object> kvp in twin.Contents)
        {
            Console.WriteLine($"{kvp.Key}  {kvp.Value}");
        }
    }
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Error {ex.Status}, {ex.ErrorCode}, {ex.Message}");
    throw;
}

다음 단계

이 문서에서 쿼리를 실행하는 데 사용되는 쿼리 API를 포함하여 Azure Digital Twins API 및 SDK에 대해 자세히 알아봅니다.