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

# AWS IoT TwinMaker 지식 그래프
<a name="tm-knowledge-graph"></a>

 AWS IoT TwinMaker 지식 그래프는 AWS IoT TwinMaker 워크스페이스에 포함된 모든 정보를 구성하고 시각적 그래프 형식으로 표시합니다. 개체, 구성 요소, 구성 요소 유형에 대해 쿼리를 실행하여 AWS IoT TwinMaker 리소스 간의 관계를 보여주는 시각적 그래프를 생성할 수 있습니다.

다음 주제는 지식 그래프를 사용하고 통합하는 방법을 보여줍니다.

**Topics**
+ [AWS IoT TwinMaker 지식 그래프 핵심 개념](#tm-knowledge-graph-concepts)
+ [AWS IoT TwinMaker 지식 그래프 쿼리를 실행하는 방법](tm-knowledge-graph-use.md)
+ [지식 그래프 장면 통합](tm-knowledge-graph-scene.md)
+ [Grafana에서 AWS IoT TwinMaker 지식 그래프를 사용하는 방법](tm-knowledge-Grafana-panel.md)
+ [AWS IoT TwinMaker 지식 그래프 추가 리소스](tm-knowledge-graph-resources.md)

## AWS IoT TwinMaker 지식 그래프 핵심 개념
<a name="tm-knowledge-graph-concepts"></a>

이 주제는 지식 그래프 특성의 주요 개념과 어휘를 다룹니다.

**지식 그래프 작동 방식**:  
지식 그래프는 기존 [CreateEntity](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_CreateEntity.html) 또는 [ UpdateEntity](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_UpdateEntity.html) APIs를 사용하여 개체와 해당 구성 요소 간의 관계를 생성합니다. 관계는 개체의 구성 요소에 정의된 특수 데이터 유형 [ RELATIONSHIP](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_DataType.html#:~:text=Valid%20Values%3A-,RELATIONSHIP,-%7C%20STRING%20%7C%20LONG%20%7C%20BOOLEAN)의 속성일 뿐입니다. AWS IoT TwinMaker 지식 그래프는 [ExecuteQuery](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_ExecuteQuery.html) API를 호출하여 개체의 모든 데이터 또는 개체 간의 관계를 기반으로 쿼리를 생성합니다. 지식 그래프는 그래프 일치 구문 지원이 새로 추가된 유연한 PartiQL 쿼리 언어(많은 AWS 서비스에서 사용)를 사용하여 쿼리를 작성하는 데 도움이 됩니다. 호출이 이루어진 후 결과를 테이블로 보거나 연결된 노드 및 엣지의 그래프로 시각화할 수 있습니다.

**지식 그래프 주요 용어**:  
+ **개체 그래프**: 작업 영역 내의 노드와 엣지 모음
+ **노드**: 작업 영역의 모든 개체가 개체 그래프에서 노드가 됩니다.
+ **엣지**: 개체의 구성 요소에 정의된 모든 관계 속성이 개체 그래프에서 엣지가 됩니다. 또한 개체의 parentEntityId 필드를 사용하여 정의된 계층적 상위-하위 관계도 'isChildOf' 관계 이름을 가진 개체 그래프의 엣지가 됩니다. 모든 엣지는 방향이 있는 모서리입니다.
+ **관계**: AWS IoT TwinMaker 관계는 개체 구성 요소의 특수한 유형의 속성입니다. [ CreateEntity](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_CreateEntity.html) 또는 [UpdateEntity](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_UpdateEntity.html) API를 사용하여 AWS IoT TwinMaker 관계를 정의하고 편집할 수 있습니다. 에서는 엔 AWS IoT TwinMaker터티의 구성 요소에 관계를 정의해야 합니다. 관계는 격리된 리소스로 정의할 수 없습니다. 관계는 한 개체에서 다른 개체로 향해야 합니다.

# AWS IoT TwinMaker 지식 그래프 쿼리를 실행하는 방법
<a name="tm-knowledge-graph-use"></a>

 AWS IoT TwinMaker 지식 그래프를 사용하기 전에 다음 사전 조건을 완료했는지 확인합니다.
+  AWS IoT TwinMaker 워크스페이스를 생성합니다. [AWS IoT TwinMaker 콘솔](https://console.aws.amazon.com/iottwinmaker/)에서 작업 영역을 생성할 수 있습니다.
+  AWS IoT TwinMaker의 개체 구성 요소 시스템과 개체를 생성하는 방법을 숙지합니다. 자세한 내용은 [첫 번째 개체 생성](twinmaker-gs-entity.md) 단원을 참조하십시오.
+  AWS IoT TwinMaker의 데이터 커넥터에 익숙해지세요. 자세한 내용은 [AWS IoT TwinMaker 데이터 커넥터](data-connector-interface.md) 단원을 참조하십시오.

**참고**  
 AWS IoT TwinMaker 지식 그래프를 사용하려면 **표준** 또는 **계층형 번들** 요금 모드에 있어야 합니다. 자세한 내용은 [AWS IoT TwinMaker 가격 책정 모드 전환](tm-pricing-mode.md) 단원을 참조하십시오.

다음 절차는 쿼리 작성, 실행, 저장 및 편집 방법을 보여줍니다.

 **쿼리 편집기 열기**   

**지식 그래프 쿼리 편집기로 이동하려면**

1. [AWS IoT TwinMaker 콘솔](https://console.aws.amazon.com/iottwinmaker/)을 엽니다.

1. 지식 그래프를 사용하려는 작업 영역을 엽니다.

1. 왼쪽 탐색 창에서 **쿼리 편집기**를 선택합니다.

1. 쿼리 편집기가 열립니다. 이제 작업 영역 리소스에 대해 쿼리를 실행할 준비가 완료되었습니다.

 **쿼리 실행**   

**쿼리를 실행하고 그래프를 생성하려면**

1. 쿼리 편집기에서 **편집기** 탭을 선택하여 구문 편집기를 엽니다.

1. 편집기 공간에서 워크스페이스의 리소스에 대해 실행하려는 쿼리를 작성합니다.  
![\[쿼리가 입력된 편집기 공간입니다.\]](http://docs.aws.amazon.com/ko_kr/iot-twinmaker/latest/guide/images/kg-query-updated.png)

   표시된 예제에서 요청은 이름`vav_%`에가 포함된 엔터티를 검색한 다음 다음 코드를 사용하여 해당 엔터티 간의 `feed` 관계를 기준으로 이러한 엔터티를 구성합니다.

   ```
   SELECT ahu, vav, r FROM EntityGraph
   MATCH (vav)<-[r:feed]-(ahu)
   WHERE vav.entityName LIKE 'vav_%'
   ```
**참고**  
지식 그래프 구문은 [PartiQL](https://partiql.org/)을 사용합니다. 이 구문에 대한 자세한 내용은 단원을 참조하십시오[AWS IoT TwinMaker 지식 그래프 추가 리소스](tm-knowledge-graph-resources.md).

1. **쿼리 실행**을 선택하여 생성한 요청을 실행합니다.

   그래프는 요청에 따라 생성됩니다.  
![\[이전 단계에서 자세히 설명한 쿼리의 결과를 보여주는 그래프입니다.\]](http://docs.aws.amazon.com/ko_kr/iot-twinmaker/latest/guide/images/tm-kg-graph-output.png)

   위에 표시된 예제 그래프는 2단계의 쿼리 예제를 기반으로 합니다.

1. 쿼리의 결과도 목록에 표시됩니다. **결과를** 선택하여 목록에서 쿼리 결과를 봅니다.

1. 선택적으로 **다른 이름으로 내보내기**를 선택하여 쿼리 결과를 JSON 또는 CSV 형식으로 내보냅니다.

여기서는 콘솔에서 지식 그래프를 사용하는 기본 방법을 다룹니다. 지식 그래프 구문을 보여주는 자세한 정보와 예는 [AWS IoT TwinMaker 지식 그래프 추가 리소스](tm-knowledge-graph-resources.md)을(를) 참조하십시오.

# 지식 그래프 장면 통합
<a name="tm-knowledge-graph-scene"></a>

 AWS IoT 앱 키트 구성 요소를 사용하여 지식 그래프를 AWS IoT TwinMaker 장면에 통합하는 웹 애플리케이션을 구축할 수 있습니다. 이를 통해 장면 내에 있는 3D 노드(장비 또는 시스템을 나타내는 3D 모델)를 기반으로 그래프를 생성할 수 있습니다. 장면에서 3D 노드를 그래프로 표시하는 애플리케이션을 생성하려면 먼저 3D 노드를 워크스페이스의 개체에 바인딩합니다. 이 매핑을 사용하면는 장면에 있는 3D 모델과 워크스페이스의 개체 간의 관계를 AWS IoT TwinMaker 그래프로 표시합니다. 그런 다음 웹 애플리케이션을 생성하고, 장면으로 3D 모델을 선택하고, 그래프 형식으로 다른 개체와의 관계를 탐색할 수 있습니다.

![\[3D 모델 간의 관계를 보여주는 지식 그래프가 있는 TwinMaker 장면입니다.\]](http://docs.aws.amazon.com/ko_kr/iot-twinmaker/latest/guide/images/intro_kg_scene.png)


 AWS IoT 앱 키트 구성 요소를 활용하여 AWS IoT TwinMaker 장면에서 그래프를 생성하는 작업 웹 애플리케이션의 예는 github의 [AWS IoT TwinMaker 샘플 반응 앱을](https://github.com/awslabs/iot-app-kit/blob/3DKG_Demo/examples/react-app/src/components/index.tsx) 참조하세요.

## AWS IoT TwinMaker 장면 그래프 사전 조건
<a name="tm-knowledge-graph-prereqs"></a>

장면에서 AWS IoT TwinMaker 지식 그래프를 사용하는 웹 앱을 생성하기 전에 다음 사전 조건을 완료하세요.
+  AWS IoT TwinMaker 워크스페이스를 생성합니다. [AWS IoT TwinMaker 콘솔](https://console.aws.amazon.com/iottwinmaker/)에서 작업 영역을 생성할 수 있습니다.
+  AWS IoT TwinMaker의 개체 구성 요소 시스템과 개체를 생성하는 방법을 숙지합니다. 자세한 내용은 [첫 번째 개체 생성](twinmaker-gs-entity.md) 단원을 참조하십시오.
+ 3D 모델로 채워진 AWS IoT TwinMaker 장면을 생성합니다.
+  AWS IoT TwinMaker의 AWS IoT 앱 키트 구성 요소를 숙지합니다. AWS IoT TwinMaker 구성 요소에 대한 자세한 내용은 섹션을 참조하세요[AWS IoT TwinMaker UI 컴포넌트를 사용하여 사용자 지정 웹 애플리케이션 만들기](tm-app-kit.md).
+ 지식 그래프 개념과 주요 용어를 숙지하십시오. [AWS IoT TwinMaker 지식 그래프 핵심 개념](tm-knowledge-graph.md#tm-knowledge-graph-concepts)을(를) 참조하세요.

**참고**  
 AWS IoT TwinMaker 지식 그래프 및 관련 기능을 사용하려면 **표준** 또는 **계층형 번들** 요금 모드에 있어야 합니다. AWS IoT TwinMaker 요금에 대한 자세한 내용은 섹션을 참조하세요[AWS IoT TwinMaker 가격 책정 모드 전환](tm-pricing-mode.md).

## 장면에서 3D 노드를 바인딩하기
<a name="tm-knowledge-graph-scene-data-binidng"></a>

지식 그래프를 장면과 통합하는 웹 앱을 생성하기 전에 장면에 있는 3D 노드라고 하는 3D 모델을 연결된 워크스페이스 개체에 바인딩합니다. 예를 들어 장면에 믹서 장비 모델이 있고 라는 해당 개체가 있는 경우 믹서 모델과 믹서를 나타내는 개체 간에 **데이터 바**인딩을 `mixer_0`생성하여 모델과 개체를 그래프로 표시할 수 있습니다.

**데이터 바인딩 작업을 수행하려면**

1. [AWS IoT TwinMaker 콘솔](https://console.aws.amazon.com/iottwinmaker/)에 로그인합니다.

1. 작업 영역을 열고 바인딩하려는 3D 노드가 있는 장면을 선택합니다.

1. 장면 컴포저에서 노드(3D 모델)를 선택합니다. 노드를 선택하면 화면 오른쪽에 검사기 패널이 열립니다.

1. 검사기 패널에서 패널 상단으로 이동하여 **\$1** 버튼을 선택합니다. 그런 다음 **개체 바인딩 추가** 옵션을 선택합니다. 그러면 현재 선택한 노드에 바인딩할 개체를 선택할 수 있는 드롭다운이 열립니다.  
![\[Inspector 패널에서 더하기 기호가 선택되고 개체 바인딩 추가가 강조 표시된 장면입니다.\]](http://docs.aws.amazon.com/ko_kr/iot-twinmaker/latest/guide/images/binding-step-4.png)

1. 데이터 바인딩 드롭다운 메뉴에서 3D 모델에 매핑할 개체 ID를 선택합니다. **구성 요소 이름** 및 **속성 이름** 필드에서 바인딩하려는 구성 요소 및 속성을 선택합니다.  
![\[Inspector 패널에서 구성 요소 및 속성 이름이 선택된 장면입니다.\]](http://docs.aws.amazon.com/ko_kr/iot-twinmaker/latest/guide/images/binding-step-6.png)

   일단 **개체 ID**, **구성 요소 이름** 및 **속성 이름** 필드를 선택하면 바인딩이 완료됩니다.

1. 그래프로 표시하려는 모든 모델 및 개체에 대해 이 프로세스를 반복합니다.
**참고**  
장면 태그에서도 동일한 데이터 바인딩 작업을 수행할 수 있습니다. 간단하게 개체 대신 태그를 선택하고 동일한 프로세스에 따라 태그를 노드에 바인딩하기만 하면 됩니다.

## 웹 애플리케이션 생성
<a name="tm-knowledge-graph-scene-application"></a>

엔터티를 바인딩한 후 AWS IoT 앱 키트 라이브러리를 사용하여 장면을 보고 장면 노드와 엔터티 간의 관계를 탐색할 수 있는 지식 그래프 위젯이 있는 웹 앱을 빌드합니다.

다음 리소스를 사용하여 자신만의 앱을 만들어 보십시오.
+  AWS IoT TwinMaker 샘플 반응 앱 github [ Readme](https://github.com/awslabs/iot-app-kit/blob/3DKG_Demo/examples/react-app/README.md) 설명서.
+ github의 AWS IoT TwinMaker 샘플 반응 앱 [ 소스](https://github.com/awslabs/iot-app-kit/blob/3DKG_Demo/examples/react-app/src/components/index.tsx)입니다.
+  AWS IoT 앱 키트 [ 시작하기](https://awslabs.github.io/iot-app-kit/?path=/docs/overview-getting-started--docs) 설명서.
+  AWS IoT 앱 키트 [ Video Player 구성 요소](https://awslabs.github.io/iot-app-kit/?path=/docs/components-videoplayer--docs) 설명서.
+  AWS IoT 앱 키트 [장면 뷰어 구성 요소](https://awslabs.github.io/iot-app-kit/?path=/docs/components-sceneviewer--docs) 설명서.

다음 절차에서는 웹 앱에서 장면 뷰어 구성 요소의 기능을 보여줍니다.

**참고**  
이 절차는 AWS IoT TwinMaker 샘플 반응 AWS IoT 앱에서 앱 키트 장면 뷰어 구성 요소의 구현을 기반으로 합니다.

1.  AWS IoT TwinMaker 샘플 반응 앱의 장면 뷰어 구성 요소를 엽니다. 검색 필드에 엔터티 이름 또는 부분 엔터티 이름(대소문자 구분 검색)을 입력한 다음 **검색** 버튼을 선택합니다. 모델이 개체 ID에 바인딩되면 장면의 모델이 강조 표시되고 개체의 노드가 장면 뷰어 패널에 표시됩니다.  
![\[지식 그래프 장면 뷰어 패널이 표시된 장면입니다.\]](http://docs.aws.amazon.com/ko_kr/iot-twinmaker/latest/guide/images/search_select_kg_event.png)

1. 모든 관계의 그래프를 생성하려면 장면 뷰어 위젯에서 노드를 선택하고 **탐색** 버튼을 선택합니다.  
![\[관계 그래프를 표시하는 지식 그래프 장면 뷰어 패널이 있는 장면입니다.\]](http://docs.aws.amazon.com/ko_kr/iot-twinmaker/latest/guide/images/explore_select_kg.png)

1. **지우기** 버튼을 눌러 현재 그래프 선택을 지우고 다시 시작합니다.

# Grafana에서 AWS IoT TwinMaker 지식 그래프를 사용하는 방법
<a name="tm-knowledge-Grafana-panel"></a>

이 섹션에서는 AWS IoT TwinMaker Grafana 대시보드에 쿼리 편집기 패널을 추가하여 쿼리를 실행하고 표시하는 방법을 보여줍니다.

## AWS IoT TwinMaker 쿼리 편집기 사전 조건
<a name="tm-knowledge-graph-Grafana-prereqs"></a>

Grafana에서 AWS IoT TwinMaker 지식 그래프를 사용하기 전에 다음 사전 조건을 완료하세요.
+  AWS IoT TwinMaker 워크스페이스를 생성합니다. [AWS IoT TwinMaker 콘솔](https://console.aws.amazon.com/iottwinmaker/)에서 작업 영역을 생성할 수 있습니다.
+ Grafana와 함께 사용하도록 AWS IoT TwinMaker 를 구성합니다. 지침은 [AWS IoT TwinMaker Grafana 대시보드 통합](grafana-integration.md) 섹션을 참조하세요.

**참고**  
 AWS IoT TwinMaker 지식 그래프를 사용하려면 **표준** 또는 **계층형 번들** 요금 모드에 있어야 합니다. 자세한 내용은 [AWS IoT TwinMaker 가격 책정 모드 전환](tm-pricing-mode.md) 단원을 참조하십시오.

## AWS IoT TwinMaker 쿼리 편집기 권한
<a name="tm-knowledge-graph-Grafana-config"></a>

Grafana에서 AWS IoT TwinMaker 쿼리 편집기를 사용하려면 작업에 대한 권한이 있는 IAM 역할이 있어야 합니다`iottwinmaker:ExecuteQuery`. 이 예제와 같이 워크스페이스 대시보드 역할에 해당 권한을 추가합니다.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket",
                "arn:aws:s3:::amzn-s3-demo-bucket/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iottwinmaker:GetEntity",
                "iottwinmaker:ListEntities",
                "iottwinmaker:ExecuteQuery"
            ],
            "Resource": [
                "arn:aws:iottwinmaker:us-east-2:111122223333:workspace/workspaceId",
                "arn:aws:iottwinmaker:us-east-2:111122223333:workspace/workspaceId/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": "iottwinmaker:ListWorkspaces",
            "Resource": "*"
        }
    ]
}
```

------

**참고**  
 AWS IoT TwinMaker Grafana 데이터 소스를 구성할 때 역할 **ARN 수임 필드에이 권한이 있는 역할을** 사용해야 합니다. 추가한 후에는 **작업 영역** 옆의 드롭다운에서 작업 영역을 선택할 수 있습니다.

자세한 내용은 [대시보드 IAM 역할 생성](dashboard-IAM-role.md#dashboard-IAM-role.title) 단원을 참조하십시오.

### AWS IoT TwinMaker 쿼리 편집기 패널 설정
<a name="tm-knowledge-graph-Grafana-panel"></a>

**지식 그래프에 대한 새 Grafana 대시보드 패널을 설정하려면**

1.  AWS IoT TwinMaker Grafana 대시보드를 엽니다.

1. 새 **대시보드 패널**을 만드십시오. 패널을 생성하는 방법에 대한 자세한 단계는 Grafana 설명서의 [ 대시보드 생성을](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/create-dashboard/) 참조하세요.

1. 시각화 목록에서 **AWS IoT TwinMaker 쿼리 편집기**를 선택합니다.  
![\[AWS IoT TwinMaker 대시보드의 드롭다운 목록에는 AWS IoT TwinMaker 쿼리 편집기에 대한 옵션이 포함되어 있습니다.\]](http://docs.aws.amazon.com/ko_kr/iot-twinmaker/latest/guide/images/tw-query-editor-dropdown.png)

1. 데이터 소스를 선택하여 쿼리를 실행합니다.

1. **(선택 사항)** 제공된 필드에 새 패널의 이름을 추가합니다.

1. **적용을** 선택하여 새 패널을 저장하고 확인합니다.

지식 그래프 패널은 AWS IoT TwinMaker 콘솔에 제공된 쿼리 편집기와 유사한 방식으로 작동합니다. 패널에서 작성한 쿼리를 실행하고, 작성하고, 지울 수 있습니다. 쿼리를 작성하는 방법에 대한 자세한 내용은 섹션을 참조하세요[AWS IoT TwinMaker 지식 그래프 추가 리소스](tm-knowledge-graph-resources.md).

#### AWS IoT TwinMaker 쿼리 편집기 사용 방법
<a name="tm-knowledge-graph-Grafana-use"></a>

쿼리 결과는 다음 이미지와 같이 세 가지 방식으로 표시됩니다. 그래프로 시각화하거나, 표로 나열하거나, 실행 요약으로 표시됩니다.
+ **그래프 시각화:**  
![\[AWS IoT TwinMaker 쿼리 편집기 결과가 시각적 그래프로 표시됩니다.\]](http://docs.aws.amazon.com/ko_kr/iot-twinmaker/latest/guide/images/kg-vis-graph.png)

  시각적 그래프에는 결과에 적어도 하나 이상의 관계가 있는 쿼리에 대한 데이터만 표시됩니다. 그래프에는 개체가 노드로 표시되고 관계는 그래프의 방향 엣지로 표시됩니다.
+ **테이블 형식 데이터:**  
![\[AWS IoT TwinMaker 쿼리 편집기 결과가 테이블 형식으로 표시됩니다.\]](http://docs.aws.amazon.com/ko_kr/iot-twinmaker/latest/guide/images/kg-table-data.png)

  표 형식 데이터 형식은 모든 쿼리의 데이터를 표시합니다. 테이블에서 특정 결과 또는 결과의 하위 집합을 검색할 수 있습니다. 데이터는 JSON 또는 CSV 형식으로 내보낼 수 있습니다.
+ **규칙 요약**  
![\[AWS IoT TwinMaker 쿼리 편집기 결과가 실행 요약으로 표시됩니다.\]](http://docs.aws.amazon.com/ko_kr/iot-twinmaker/latest/guide/images/kg-run-sum.png)

  실행 요약에는 쿼리 상태에 대한 쿼리와 메타데이터가 표시됩니다.

# 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 | 예 |