Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# AWS IoT TwinMaker grafik pengetahuan sumber daya tambahan
<a name="tm-knowledge-graph-resources"></a>

Bagian ini memberikan contoh dasar sintaks PartiQL yang digunakan untuk menulis kueri dalam grafik pengetahuan, serta tautan ke dokumentasi PartiQL yang memberikan informasi tentang model data grafik pengetahuan.
+ [ Dokumentasi model data grafik PartiQL](https://partiql.org/gpml/graph_model.html)
+ [ Dokumentasi kueri grafik PartiQL](https://partiql.org/gpml/graph_query.html)

Kumpulan contoh ini menunjukkan kueri dasar dengan tanggapannya. Gunakan ini sebagai referensi untuk menulis pertanyaan Anda sendiri.

**Kueri dasar**  
+ **Dapatkan semua entitas dengan filter**

  ```
  SELECT entity
  FROM EntityGraph MATCH (entity)
  WHERE entity.entityName = 'room_0'
  ```

   Query ini mengembalikan semua entitas dalam ruang kerja dengan nama`room_0`.

  `FROM`klausa: `EntityGraph` adalah kumpulan grafik yang berisi semua entitas dan hubungannya di ruang kerja. Koleksi ini dibuat dan dikelola secara otomatis AWS IoT TwinMaker berdasarkan entitas di ruang kerja Anda.

  `MATCH`klausa: menentukan pola yang cocok dengan sebagian dari grafik. Dalam hal ini, pola `(entity)` cocok dengan setiap node dalam grafik dan terikat ke variabel entitas. `FROM`Klausul harus diikuti oleh `MATCH` klausa.

  `WHERE`klausa: menentukan filter pada `entityName` bidang node, di mana nilai harus cocok. `room_0`

  `SELECT`klausa: menentukan `entity` variabel sehingga seluruh node entitas dikembalikan.

  **Tanggapan:**

  ```
  {
    "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`Mengembalikan metadata tentang kolom, seperti nama dan jenis. Jenis yang dikembalikan adalah`NODE`. Ini menunjukkan bahwa seluruh node telah dikembalikan. Nilai lain untuk tipe dapat `EDGE` yang akan menunjukkan hubungan atau `VALUE` yang akan menunjukkan nilai skalar seperti bilangan bulat atau string.

  `rows`Mengembalikan daftar baris. Karena hanya satu entitas yang dicocokkan, satu `rowData` dikembalikan yang berisi semua bidang dalam entitas.
**catatan**  
Tidak seperti SQL di mana Anda hanya dapat mengembalikan nilai skalar, Anda dapat mengembalikan objek (sebagai JSON) menggunakan PartiQL.

  Setiap node berisi semua bidang tingkat entitas seperti`entityId`, `arn` dan`components`, bidang tingkat komponen seperti, dan serta bidang tingkat properti `properties` seperti `componentTypeId` dan`componentName`, semua sebagai JSON `propertyName` bersarang`propertyValue`.
+ **Dapatkan semua hubungan dengan filter**:

  ```
  SELECT relationship
  FROM EntityGraph MATCH (e1)-[relationship]->(e2)
  WHERE relationship.relationshipName = 'isLocationOf'
  ```

  Query ini mengembalikan semua hubungan dalam ruang kerja dengan nama `isLocationOf` hubungan.

   `MATCH`Klausa: menentukan pola yang cocok dengan dua node (ditunjukkan oleh`()`) yang dihubungkan oleh tepi terarah (ditunjukkan oleh`-[]->`) dan terikat ke variabel yang disebut. `relationship`

  `WHERE`Klausa: menentukan filter pada `relationshipName` bidang tepi, di mana nilainya. `isLocationOf`

  `SELECT`Klausa: menentukan variabel hubungan sehingga seluruh simpul tepi dikembalikan.

  **Respons**

  ```
  {
      "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
      ]
  }
  ```

  Jenis kolom di dalam `columnDescriptions` adalah`EDGE`.

  Masing-masing `rowData` mewakili tepi dengan bidang seperti`relationshipName`. Ini sama dengan nama properti hubungan yang didefinisikan pada entitas. The`sourceEntityId`, `sourceComponentName` dan `sourceComponentTypeId` memberikan informasi tentang entitas dan komponen mana properti hubungan didefinisikan. `targetEntityId`Menentukan entitas mana yang ditunjuk oleh hubungan ini.
+ **Dapatkan semua entitas dengan hubungan tertentu dengan entitas tertentu**

  ```
  SELECT e2.entityName
        FROM EntityGraph MATCH (e1)-[r]->(e2)
        WHERE relationship.relationshipName = 'isLocationOf'
        AND e1.entityName = 'room_0'
  ```

  Query ini mengembalikan semua nama entitas dari semua entitas yang memiliki `isLocationOf` hubungan dengan `room_0` entitas.

  `MATCH`Klausa: menentukan pola yang cocok dengan dua node (`e1`,`e2`) yang memiliki tepi terarah (`r`).

  `WHERE`Klausul: menentukan filter pada nama hubungan dan nama entitas sumber.

  `SELECT`Klausul: mengembalikan `entityName` bidang di `e2` node.

  **Respons**

  ```
  {
    "columnDescriptions": [
      {
         "name": "entityName",
         "type": "VALUE"
      }
    ],
     "rows": [
      {
         "rowData": [
           "floor_0"
        ]
      }
    ]
  }
  ```

  Dalam ColumnDescriptions, jenis kolom adalah `VALUE` karena `entityName` adalah string.

  Satu entitas dikembalikan. `floor_0`

**PERTANDINGAN**  
Pola berikut didukung dalam `MATCH` klausa:  
+ Cocokkan simpul 'b' yang menunjuk ke simpul 'a':

  ```
  FROM EntityGraph MATCH (a)-[rel]-(b)
  ```
+ Cocokkan simpul 'a' yang menunjuk ke simpul 'b':

  ```
  FROM EntityGraph MATCH (a)-[]->(b)
  ```

  Tidak ada variabel yang terikat pada hubungan dengan asumsi filter tidak perlu ditentukan pada hubungan tersebut.
+ Cocokkan simpul 'a' yang menunjuk ke simpul 'b' dan simpul 'b' menunjuk ke simpul 'a':

  ```
  FROM EntityGraph MATCH (a)-[rel]-(b)
  ```

  Ini akan mengembalikan dua kecocokan: satu dari 'a' ke 'b' dan satu lagi dari 'b' ke 'a', jadi rekomendasinya adalah menggunakan tepi yang diarahkan sedapat mungkin.
+ Nama hubungan juga merupakan label grafik properti`EntityGraph`, jadi Anda cukup menentukan nama hubungan mengikuti titik dua (:) alih-alih menentukan filter di `rel.relationshipName` dalam `WHERE` klausa.

  ```
  FROM EntityGraph MATCH (a)-[:isLocationOf]-(b)
  ```
+ Rantai: pola dapat dirantai agar sesuai dengan beberapa hubungan.

  ```
  FROM EntityGraph MATCH (a)-[rel1]->(b)-[rel2]-(c)
  ```
+ Pola hop variabel dapat menjangkau beberapa node dan tepi juga:

  ```
  FROM EntityGraph MATCH (a)-[]->{1,5}(b)
  ```

  Kueri ini cocok dengan pola apa pun dengan tepi keluar dari simpul 'a' dalam 1 hingga 5 hop. Kuantifier yang diizinkan adalah:

  `{m,n}`- antara m dan n pengulangan

  `{m,}`- m atau lebih pengulangan.

**DARI**:  
Node entitas dapat berisi data bersarang, seperti komponen yang berisi data bersarang lebih lanjut seperti properti. Ini dapat diakses dengan menghapus hasil pola 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'
```
Akses bidang bersarang dengan mendotting `.` ke dalam variabel. Koma (,) digunakan untuk menghapus (atau menggabungkan) entitas dengan komponen di dalamnya dan kemudian properti di dalam komponen tersebut. `AS`digunakan untuk mengikat variabel ke variabel unnested sehingga mereka dapat digunakan dalam atau klausa. `WHERE` `SELECT` Query ini mengembalikan semua entitas yang berisi properti bernama `roomFunction` dengan nilai `meeting` dalam komponen dengan id tipe komponen `com.example.query.construction.room`   
Untuk mengakses beberapa bidang bersarang dari bidang seperti beberapa komponen dalam entitas, gunakan notasi koma untuk melakukan gabungan.  

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

**PILIH**:  
+ Kembalikan simpul:

  ```
  SELECT e
  FROM EntityGraph MATCH (e)
  ```
+ Kembalikan tepi:

  ```
  SELECT r
  FROM EntityGraph MATCH (e1)-[r]->(e2)
  ```
+ Mengembalikan nilai skalar:

  ```
  SELECT floor.entityName, room.description, p.propertyValue AS roomfunction
  FROM EntityGraph MATCH (floor)-[:isLocationOf]-(room),
  room.components AS c, c.properties AS p
  ```

  Format nama bidang output dengan aliasing menggunakan`AS`. Di sini, bukan `propertyValue` sebagai nama kolom dalam respons, `roomfunction` dikembalikan.
+ Kembalikan alias:

  ```
  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%'
  ```

  Menggunakan alias sangat disarankan untuk menjadi eksplisit, meningkatkan keterbacaan, dan menghindari ambiguitas dalam kueri Anda.

**DIMANA**:  
+ Operator logis yang didukung adalah`AND`,`NOT`, dan`OR`.
+ Operator perbandingan yang didukung adalah`<`,`<=`,`>`,`=>`,`=`, dan`!=`.
+ Gunakan `IN` kata kunci jika Anda ingin menentukan beberapa `OR` kondisi pada bidang yang sama.
+ Filter pada bidang entitas, komponen, atau properti:

  ```
  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'
  ```
+ Filter pada `configuration` properti. Berikut `unit` adalah kunci dalam peta konfigurasi dan `Celsius` nilainya.

  ```
  WHERE p.definition.configuration.unit = 'Celsius'
  ```
+ Periksa apakah properti peta berisi kunci dan nilai yang diberikan:

  ```
  WHERE p.propertyValue.length = 20.0
  ```
+ Periksa apakah properti peta berisi kunci yang diberikan:

  ```
  WHERE NOT p.propertyValue.length IS MISSING
  ```
+ Periksa apakah properti list berisi nilai yang diberikan:

  ```
  WHERE 10.0 IN p.propertyValue
  ```
+ Gunakan `lower()` fungsi untuk perbandingan yang tidak peka huruf besar/kecil. Secara default, semua perbandingan peka huruf besar/kecil.

  ```
  WHERE lower(p.propertyValue) = 'meeting'
  ```

**SUKA**:  
Berguna jika Anda tidak tahu nilai pasti untuk bidang dan dapat melakukan pencarian teks lengkap pada bidang yang ditentukan. `%`mewakili nol atau lebih.  

```
WHERE e.entityName LIKE '%room%'
```
+ Pencarian Infix: `%room%`
+ Pencarian awalan: `room%`
+ Pencarian akhiran: `%room`
+ Jika Anda memiliki '%' dalam nilai Anda, maka letakkan karakter escape di `LIKE` dan tentukan karakter escape dengan`ESCAPE`.

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

**BERBEDA**:  

```
SELECT DISTINCT c.componentTypeId
FROM EntityGraph MATCH (e), e.components AS c
```
+ `DISTINCT`Kata kunci menghilangkan duplikat dari hasil akhir.

  `DISTINCT`tidak didukung pada tipe data yang kompleks.

**MENGHITUNG**  

```
SELECT COUNT(e), COUNT(c.componentTypeId)
FROM EntityGraph MATCH (e), e.components AS c
```
+ `COUNT`Kata kunci menghitung jumlah item dalam hasil query.
+ `COUNT`tidak didukung pada bidang kompleks bersarang dan bidang pola grafik.
+ `COUNT`agregasi tidak didukung dengan `DISTINCT` dan kueri bersarang.

  Misalnya, `COUNT(DISTINCT e.entityId)` tidak didukung.

**JALAN**  
Proyeksi pola berikut didukung dalam kueri menggunakan proyeksi jalur:  
+ Kueri hop variabel

  ```
  SELECT p FROM EntityGraph MATCH p = (a)-[]->{1, 3}(b)
  ```

  Kueri ini cocok dan memproyeksikan metadata node dari pola apa pun dengan tepi keluar dari simpul *a* dalam 1 hingga 3 hop.
+ Kueri hop tetap

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

  *Kueri ini mencocokkan dan memproyeksikan metadata entitas dan tepi yang masuk ke b.*
+ Kueri tidak terarah

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

  *Kueri ini cocok dan memproyeksikan metadata node dalam 1 pola hop *yang menghubungkan a* dan *c melalui b*.*

  ```
  {
      "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"
                          }
                      ]
                  }
              ]
          }
      ]
  }
  ```

  **Respons `PATH` kueri ini hanya terdiri dari metadata yang mengidentifikasi semua node dan tepi masing-masing path/pattern antara *a* dan c melalui b.**

**LIMIT** dan **OFFSET**:  

```
SELECT e.entityName
FROM EntityGraph MATCH (e)
WHERE e.entityName LIKE 'room_%'
LIMIT 10
OFFSET 5
```
`LIMIT`menentukan jumlah hasil yang akan dikembalikan dalam query, dan `OFFSET` menentukan jumlah hasil untuk dilewati.

**LIMIT** dan **maxResults**:  
Contoh berikut menunjukkan kueri yang mengembalikan 500 hasil secara total, tetapi hanya menampilkan 50 pada satu waktu per panggilan API. Pola ini dapat digunakan di mana Anda perlu membatasi jumlah hasil yang ditampilkan, misalnya jika Anda hanya dapat menampilkan 50 hasil di UI.  

```
aws iottwinmaker execute-query \
--workspace-id exampleWorkspace \
--query-statement "SELECT e FROM EntityGraph MATCH (e) LIMIT 500"\
--max-results 50
```
+ `LIMIT`Kata kunci mempengaruhi query dan membatasi baris yang dihasilkan. Jika Anda perlu mengontrol jumlah hasil yang dikembalikan per panggilan API tanpa membatasi jumlah total hasil yang dikembalikan, gunakan`LIMIT`.
+ `max-results`adalah parameter opsional untuk [tindakan ExecuteQuery API](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html). `max-results`hanya berlaku untuk API dan bagaimana hasil dibaca dalam batas-batas kueri di atas.

  Menggunakan `max-results` dalam kueri memungkinkan Anda untuk mengurangi jumlah hasil yang ditampilkan tanpa membatasi jumlah aktual hasil yang dikembalikan.
Kueri di bawah ini berulang melalui halaman hasil berikutnya. Kueri ini menggunakan panggilan `ExecuteQuery` API untuk mengembalikan baris 51-100, di mana halaman hasil berikutnya ditentukan oleh `next-token` — dalam hal ini tokennya adalah:. `"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`String menentukan halaman berikutnya dari hasil. Untuk informasi selengkapnya, lihat tindakan [ ExecuteQuery](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html#API_ExecuteQuery_RequestSyntax)API.

AWS IoT TwinMaker kueri grafik pengetahuan memiliki batasan sebagai berikut: 


****  

| Batasi Nama | Kuota | Dapat Disesuaikan | 
| --- | --- | --- | 
| Batas waktu eksekusi kueri | 10 detik | Tidak | 
| Jumlah hop maksimum | 10 | Ya | 
| Jumlah maksimum self `JOIN` s | 20 | Ya | 
| Jumlah maksimum bidang yang diproyeksikan | 20 | Ya | 
| Jumlah maksimum ekspresi bersyarat (`AND`,`OR`,`NOT`) | 10 | Ya | 
| Panjang maksimum pola `LIKE` ekspresi (termasuk wildcard dan escapes) | 20 | Ya | 
| Jumlah maksimum item yang dapat ditentukan dalam IN klausa | 10 | Ya | 
| Nilai maksimum untuk OFFSET | 3000 | Ya | 
| Nilai maksimum untuk `LIMIT` | 3000 | Ya | 
| Nilai maksimum untuk traversal (\+) `OFFSET` `LIMIT` | 3000 | Ya |