기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# AWS IoT TwinMaker 지식 그래프 추가 리소스
<a name="tm-knowledge-graph-resources"></a>

이 섹션에서는 지식 그래프에 쿼리를 작성하는 데 사용되는 PartiQL 구문의 기본 예제와 지식 그래프 데이터 모델에 대한 정보를 제공하는 PartiQL 설명서 링크를 제공합니다.
+ [PartiQL 그래프 데이터 모델 문서](https://partiql.org/gpml/graph_model.html)
+ [PartiQL 그래프 쿼리 문서](https://partiql.org/gpml/graph_query.html)

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

**기본 쿼리**  
+ **필터가 있는 모든 개체 얻기**

  ```
  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`, 등의 구성 요소 수준 필드`properties`, `componentTypeId` 및 `propertyName` 등의 속성 수준 필드가 모두 중첩 JSON`propertyValue`으로 포함됩니다.
+ **필터를 가진 모든 관계 얻기**:

  ```
  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\$15개 내에서 노드 '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\$13개의 홉 내에서 노드 **에서 발신 엣지가 있는 모든 패턴의 노드 메타데이터를 일치시키고 프로젝션합니다.
+ 홉 쿼리 수정

  ```
  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 작업](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html)의 선택적 파라미터입니다.는 API에만 적용되며 위 쿼리의 범위 내에서 결과를 읽는 방법`max-results`만 적용합니다.

  쿼리`max-results`에서를 사용하면 반환된 실제 결과 수를 제한하지 않고 표시되는 결과 수를 줄일 수 있습니다.
아래 쿼리는 결과의 다음 페이지를 반복합니다. 이 쿼리는 `ExecuteQuery` API 호출을 사용하여 51\$1100행을 반환합니다. 여기서 결과의 다음 페이지는에 의해 지정됩니다. `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](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html#API_ExecuteQuery_RequestSyntax) API 작업을 참조하세요.

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


****  

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