AWS IoT TwinMaker 지식 그래프 추가 리소스

이 섹션에서는 지식 그래프에 쿼리를 작성하는 데 사용되는 PartiQL 구문의 기본 예제와 지식 그래프 데이터 모델에 대한 정보를 제공하는 PartiQL 설명서 링크를 제공합니다.

이 예제 세트는 응답이 포함된 기본 쿼리를 보여줍니다. 이를 참조로 사용하여 자체 쿼리를 작성합니다.

기본 쿼리

필터가 있는 모든 개체 얻기
```
SELECT entity
FROM EntityGraph MATCH (entity)
WHERE entity.entityName = 'room_0'
```
이 쿼리는 이름이 인 워크스페이스의 모든 엔터티를 반환합니다room_0.

FROM 절: EntityGraph는 워크스페이스의 모든 엔터티와 해당 관계를 포함하는 그래프 컬렉션입니다. 이 컬렉션은 워크스페이스의 엔터티를 AWS IoT TwinMaker 기반으로에서 자동으로 생성되고 관리됩니다.

MATCH절: 그래프의 일부와 일치하는 패턴을 지정합니다. 이 경우, 패턴은 그래프의 모든 노드와 (entity) 일치하며 개체 변수에 바인딩됩니다. FROM절 뒤에 MATCH절이 와야 합니다.

WHERE 절: 값이와 일치해야 하는 노드의 entityName 필드에 필터를 지정합니다room_0.

SELECT 절: 전체 개체 노드가 반환되도록 entity 변수를 지정합니다.

응답:
```
{
  "columnDescriptions": [
    {
      "name": "entity",
      "type": "NODE"
    }
  ],
  "rows": [
    {
      "rowData": [
        {
          "arn": "arn:aws:iottwinmaker:us-east-1: 577476956029: workspace / SmartBuilding8292022 / entity / room_18f3ef90 - 7197 - 53 d1 - abab - db9c9ad02781 ",
          "creationDate": 1661811123914,
          "entityId": "room_18f3ef90-7197-53d1-abab-db9c9ad02781",
          "entityName": "room_0",
          "lastUpdateDate": 1661811125072,
          "workspaceId": "SmartBuilding8292022",
          "description": "",
          "components": [
            {
              "componentName": "RoomComponent",
              "componentTypeId": "com.example.query.construction.room",
              "properties": [
                {
                  "propertyName": "roomFunction",
                  "propertyValue": "meeting"
                },
                {
                  "propertyName": "roomNumber",
                  "propertyValue": 0
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```
는 이름 및 유형과 같은 열에 대한 메타데이터를 columnDescriptions 반환합니다. 반환되는 유형은 NODE입니다. 이는 전체 노드가 반환되었음을 나타냅니다. 유형의 다른 값은 관계를 나타내EDGE거나 정수 또는 문자열과 같은 스칼라 값을 VALUE 나타낼 수 있습니다.

rows은 행 목록을 반환합니다. 오직 하나의 개체만 일치하므로, 하나인 은하나뿐이므로 개체 안의 모든 필드를 포함하는 하나의 rowData이(가) 반환됩니다.

참고
스칼라 값만 반환할 수 있는 SQL과는 달리, PartiQL을 사용하여 객체(JSON으로서)를 반환할 수 있습니다.

각 노드에는 entityId, arn , 등의 모든 개체 수준 필드components, , 등의 구성 요소 수준 필드componentName, componentTypeId 및 propertyName 등의 properties 속성 수준 필드가 모두 중첩 JSONpropertyValue으로 포함됩니다.
필터를 가진 모든 관계 얻기:
```
SELECT relationship
FROM EntityGraph MATCH (e1)-[relationship]->(e2)
WHERE relationship.relationshipName = 'isLocationOf'
```
이 쿼리는 관계 이름 isLocationOf을(를) 가진 작업 영역의 모든 관계를 반환합니다.

MATCH 절: 방향이 지정된 엣지(로 표시됨())에 의해 연결되고 라는 변수에 바인딩되는 두 노드(로 표시됨-[]->)와 일치하는 패턴을 지정합니다relationship.

WHERE 절: 엣지의 relationshipName 필드에 필터를 지정합니다. 여기서 값은 입니다isLocationOf.

SELECT절: 전체 엣지 노드가 반환되도록 관계 변수를 지정합니다.

응답
```
{
    "columnDescriptions": [{
        "name": "relationship",
        "type": "EDGE"
    }],
    "rows": [{
        "rowData": [{
            "relationshipName": "isLocationOf",
            "sourceEntityId": "floor_83faea7a-ea3b-56b7-8e22-562f0cf90c5a",
            "targetEntityId": "building_4ec7f9e9-e67e-543f-9d1b- 235df7e3f6a8",
            "sourceComponentName": "FloorComponent",
            "sourceComponentTypeId": "com.example.query.construction.floor"
        }]
    },
        ... //rest of the rows are omitted
    ]
}
```
의 열 유형은 columnDescriptions입니다EDGE.

각각은와 같은 필드가 있는 엣지를 rowData 나타냅니다relationshipName. 이는 엔터티에 정의된 관계 속성 이름과 동일합니다. sourceEntityId, sourceComponentName 및는 관계 속성이 정의된 엔터티 및 구성 요소에 대한 정보를 sourceComponentTypeId 제공합니다. 는이 관계가 가리키는 개체를 targetEntityId 지정합니다.
특정 엔터티와 특정 관계가 있는 모든 엔터티 가져오기
```
SELECT e2.entityName
      FROM EntityGraph MATCH (e1)-[r]->(e2)
      WHERE relationship.relationshipName = 'isLocationOf'
      AND e1.entityName = 'room_0'
```
이 쿼리는 엔터티와 isLocationOf 관계가 있는 모든 엔터티의 모든 room_0엔터티 이름을 반환합니다.

MATCH 절: 방향이 지정된 엣지(e2)가 있는 두 노드(e1, )와 일치하는 패턴을 지정합니다r.

WHERE절: 은 관계 이름 및 소스 개체 이름에 대한 필터를 지정합니다.

SELECT 절: e2 노드의 entityName 필드를 반환합니다.

응답
```
{
  "columnDescriptions": [
    {
       "name": "entityName",
       "type": "VALUE"
    }
  ],
   "rows": [
    {
       "rowData": [
         "floor_0"
      ]
    }
  ]
}
```
columnDescriptions에서 열의 유형은 입니다.는 문자열entityName이기 VALUE 때문입니다.

하나의 개체인 floor_0가 반환됩니다.

일치

MATCH 절에서 지원되는 패턴은 다음과 같습니다.

노드 'a'를 가리키는 노드 'b' 일치:
```
FROM EntityGraph MATCH (a)-[rel]-(b)
```
노드 'b'를 가리키는 노드 'a' 일치:
```
FROM EntityGraph MATCH (a)-[]->(b)
```
관계에 필터를 지정할 필요가 없다고 가정할 때 관계에 바인딩된 변수는 없습니다.
노드 'b'를 가리키는 노드 'a'와 노드 'a'를 가리키는 노드 'b'를 일치시킵니다.
```
FROM EntityGraph MATCH (a)-[rel]-(b)
```
이렇게 하면 두 개의 일치 항목이 반환됩니다. 하나는 'a'에서 'b'로, 다른 하나는 'b'에서 'a'로 반환되므로 가능하면 방향이 지정된 엣지를 사용하는 것이 좋습니다.
관계 이름은 속성 그래프의 레이블이기도 EntityGraph하므로 WHERE 절에 필터를 지정하는 대신 콜론(:) 뒤에 관계 이름을 지정하면 rel.relationshipName 됩니다.
```
FROM EntityGraph MATCH (a)-[:isLocationOf]-(b)
```
체인 연결: 패턴을 체인으로 연결하여 여러 관계에서 일치시킬 수 있습니다.
```
FROM EntityGraph MATCH (a)-[rel1]->(b)-[rel2]-(c)
```
가변 홉 패턴은 여러 노드와 엣지에 걸쳐 있을 수도 있습니다.
```
FROM EntityGraph MATCH (a)-[]->{1,5}(b)
```
이 쿼리는 홉 1~5개 내에서 노드 'a'의 발신 엣지가 있는 모든 패턴과 일치합니다. 허용 한정자는 다음과 같습니다.

{m,n}- m회와 n회 사이의 반복

{m,}- m 회 이상의 반복

발신:

개체 노드에는 속성과 같은 추가 중첩 데이터가 포함된 구성 요소와 같은 중첩 데이터가 포함될 수 있습니다. MATCH 패턴의 결과를 중첩 해제하여 이러한 데이터에 액세스할 수 있습니다.


SELECT e
FROM EntityGraph MATCH (e), e.components AS c, c.properties AS p
WHERE c.componentTypeId = 'com.example.query.construction.room',
AND p.propertyName = 'roomFunction'
AND p.propertyValue = 'meeting'

변수에 . 점을 찍어 중첩된 필드에 액세스할 수 있습니다. 쉼표(,)는 엔터티를 구성 요소 내부에서 중첩 해제(또는 조인)한 다음 해당 구성 요소 내부의 속성을 포함하는 데 사용됩니다. AS는 WHERE 또는 SELECT 절에서 사용할 수 있도록 변수를 중첩되지 않은 변수에 바인딩하는 데 사용됩니다. 이 쿼리는 구성 요소 유형이 id com.example.query.construction.room인 구성 요소에서 meeting값을 사용하여 roomFunction 이름이 지정된 속성을 포함하는 모든 개체를 반환합니다.

개체에서 여러 구성 요소와 같은 필드의 여러 중첩된 필드에 액세스하려면 쉼표 표기법을 사용하여 결합을 수행하십시오.


SELECT e
FROM EntityGraph MATCH (e), e.components AS c1, e.components AS c2

선택:

노드 반환:
```
SELECT e
FROM EntityGraph MATCH (e)
```

엣지 반환:


SELECT r
FROM EntityGraph MATCH (e1)-[r]->(e2)

스칼라 값을 반환합니다.
```
SELECT floor.entityName, room.description, p.propertyValue AS roomfunction
FROM EntityGraph MATCH (floor)-[:isLocationOf]-(room),
room.components AS c, c.properties AS p
```
AS를 사용하는 별칭을 지정하여 출력 필드의 이름을 포맷합니다. 여기에서 응답의 열 이름 propertyValue대신에 roomfunction이(가) 반환됩니다.

별칭 반환:


SELECT floor.entityName AS floorName, luminaire.entityName as luminaireName
FROM EntityGraph MATCH (floor)-[:isLocationOf]-(room)-[:hasPart]-
(lightingZone)-[:feed]-(luminaire)
WHERE floor.entityName = 'floor_0'
AND luminaire.entityName like 'lumin%'

별칭을 사용하는 것은 명시적이고, 가독성을 높이고, 쿼리의 모호성을 방지하는 것이 좋습니다.

WHERE:

지원되는 논리 연산자는 AND, NOT및 입니다OR.
지원된 비교 연산자는 e <, <=, >, =>, = 및 !=입니다.
동일한 필드에 여러 OR 조건을 지정하려면 IN 키워드를 사용합니다.

개체, 구성 요소 또는 속성 필드에 필터링:


FROM EntityGraph MATCH (e), e.components AS c, c.properties AS p
WHERE e.entityName = 'room_0'
AND c.componentTypeId = 'com.example.query.construction.room',
AND p.propertyName = 'roomFunction'
AND NOT p.propertyValue = 'meeting'
OR p.propertyValue = 'office'

configuration 속성을 기준으로 필터링합니다. 다음은 구성 맵의 키이고 unit는 값Celsius입니다.
```
WHERE p.definition.configuration.unit = 'Celsius'
```
맵 속성에 지정된 키와 값이 포함되어 있는지 확인하십시오:
```
WHERE p.propertyValue.length = 20.0
```
맵 속성에 지정된 키가 포함되어 있는지 확인하십시오:
```
WHERE NOT p.propertyValue.length IS MISSING
```
목록 속성에 지정된 값이 포함되어 있는지 확인하십시오.
```
WHERE 10.0 IN p.propertyValue
```
이 lower() 함수는 대소문자를 구분하지 않고 비교하는 데 사용합니다. 기본 값으로, 모든 비교는 대소문자를 구분합니다.
```
WHERE lower(p.propertyValue) = 'meeting'
```

LIKE:

필드의 정확한 값을 모르고 지정된 필드에서 전체 텍스트 검색을 수행할 수 있는 경우에 유용합니다. %은 0회 이상을 나타냅니다.


WHERE e.entityName LIKE '%room%'

삽입사 검색: %room%
접두사 검색: room%
접미사 검색: %room
값에 '%'가 있는 경우 이스케이프 문자를에 LIKE 넣고 이스케이프 문자를 로 지정합니다ESCAPE.


WHERE e.entityName LIKE 'room\%' ESCAPE '\'

DISTINCT:


SELECT DISTINCT c.componentTypeId
FROM EntityGraph MATCH (e), e.components AS c

DISTINCT 키워드는 최종 결과에서 중복된 항목을 제거합니다.

DISTINCT는 복잡한 데이터 유형에는 지원되지 않습니다.

COUNT


SELECT COUNT(e), COUNT(c.componentTypeId)
FROM EntityGraph MATCH (e), e.components AS c

COUNT 키워드는 쿼리 결과의 항목 수를 계산합니다.
COUNT는 중첩된 복합 필드 및 그래프 패턴 필드에서 지원되지 않습니다.
COUNT DISTINCT 및 중첩 쿼리에서는 집계가 지원되지 않습니다.

예를 들어 COUNT(DISTINCT e.entityId)은 지원되지 않습니다.

경로

경로 프로젝션을 사용하여 쿼리할 때 다음 패턴 프로젝션이 지원됩니다.

변수 홉 쿼리
```
SELECT p FROM EntityGraph MATCH p = (a)-[]->{1, 3}(b)
```
이 쿼리는 홉 1~3개 내에서 노드 a에서 발신 엣지가 있는 모든 패턴의 노드 메타데이터를 일치시키고 프로젝션합니다.
홉 쿼리 수정
```
SELECT p FROM EntityGraph MATCH p = (a)-[]->(b)<-[]-(c)
```
이 쿼리는 엔터티 및 수신 엣지의 메타데이터를 일치시키고 b로 프로젝션합니다.

비지정 쿼리


SELECT p FROM EntityGraph MATCH p = (a)-[]-(b)-[]-(c)

이 쿼리는 b를 통해 a와 c를 연결하는 1개의 홉 패턴으로 노드의 메타데이터를 일치시키고 프로젝션합니다.


{
    "columnDescriptions": [
        {
            "name": "path",
            "type": "PATH"
        }
    ],
    "rows": [
        {
            "rowData": [
                {
                    "path": [
                        {
                            "entityId": "a",
                            "entityName": "a"
                        },
                        {
                            "relationshipName": "a-to-b-relation",
                            "sourceEntityId": "a",
                            "targetEntityId": "b"
                        },
                        {
                            "entityId": "b",
                            "entityName": "b"
                        }
                    ]
                }
            ]
        },
        {
            "rowData": [
                {
                    "path": [
                        {
                            "entityId": "b",
                            "entityName": "b"
                        },
                        {
                            "relationshipName": "b-to-c-relation",
                            "sourceEntityId": "b",
                            "targetEntityId": "c"
                        },
                        {
                            "entityId": "c",
                            "entityName": "c"
                        }
                    ]
                }
            ]
        }
    ]
}

이 PATH 쿼리 응답은 b를 통해 a와 c 사이의 각 경로/패턴의 모든 노드와 엣지를 식별하는 메타데이터로만 구성됩니다.

LIMIT 및 OFFSET:


SELECT e.entityName
FROM EntityGraph MATCH (e)
WHERE e.entityName LIKE 'room_%'
LIMIT 10
OFFSET 5

LIMIT은(는) 쿼리에서 반환되는 결과 수를 지정하고 OFFSET은(는) 건너뛸 결과 수를 지정합니다.

LIMIT 및 maxResults:

다음 예제는 총 500개의 결과를 반환하지만 API 호출당 한 번에 50개만 표시하는 쿼리를 보여줍니다. 이 패턴은 예를 들어 UI에 50개의 결과만 표시할 수 있는 경우 표시된 결과의 양을 제한해야 하는 경우에 사용할 수 있습니다.


aws iottwinmaker execute-query \
--workspace-id exampleWorkspace \
--query-statement "SELECT e FROM EntityGraph MATCH (e) LIMIT 500"\
--max-results 50

LIMIT 키워드는 쿼리에 영향을 미치고 결과 행을 제한합니다. 반환된 총 결과 수를 제한하지 않고 API 호출당 반환되는 결과 수를 제어해야 하는 경우를 사용합니다LIMIT.
max-results는 ExecuteQuery API 작업의 선택적 파라미터입니다.는 API에만 적용되며 위 쿼리의 범위 내에서 결과를 읽는 방법max-results만 적용합니다.

쿼리max-results에서를 사용하면 반환된 실제 결과 수를 제한하지 않고 표시되는 결과 수를 줄일 수 있습니다.

아래 쿼리는 결과의 다음 페이지를 반복합니다. 이 쿼리는 ExecuteQuery API 호출을 사용하여 51~100행을 반환합니다. 여기서 결과의 다음 페이지는에 의해 지정됩니다. next-token이 경우 토큰은 입니다"H7kyGmvK376L".


aws iottwinmaker execute-query \
--workspace-id exampleWorkspace \
--query-statement "SELECT e FROM EntityGraph MATCH (e) LIMIT 500"\
--max-results 50
--next-token "H7kyGmvK376L"

next-token 문자열은 결과의 다음 페이지를 지정합니다. 자세한 내용은 ExecuteQuery API 작업을 참조하세요.

AWS IoT TwinMaker 지식 그래프 쿼리에는 다음과 같은 제한이 있습니다.

제한 이름	할당량	조정 가능
쿼리 실행 제한 시간	10초	아니요
최대 홉 수	10	예
최대 자체 수 `JOIN`	20	예
최대 보호되는 필드 수	20	예
최대 조건식 수(`AND`, `OR`, `NOT`)	10	예
`LIKE` 표현식 패턴의 최대 길이(와일드카드 및 이스케이프 포함)	20	예
`IN` 절에서 지정할 수 있는 최대 항목 수	10	예
의 최대값 `OFFSET`	3000	예
의 최대값 `LIMIT`	3000	예
최대 순회 값(`OFFSET` + `LIMIT`)	3000	예

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

지식 그래프 Grafana 패널

AWS IoT SiteWise과의 자산 동기화

AWS IoT TwinMaker 지식 그래프 추가 리소스

참고