Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

# AWS IoT TwinMaker Knowledge Graph: zusätzliche Ressourcen
<a name="tm-knowledge-graph-resources"></a>

Dieser Abschnitt enthält grundlegende Beispiele für die PartiQL-Syntax, die zum Schreiben von Abfragen im Knowledge Graph verwendet wird, sowie Links zur PartiQL-Dokumentation, die Informationen zum Knowledge Graph-Datenmodell enthält.
+ [ Dokumentation zum PartiQL-Diagrammdatenmodell](https://partiql.org/gpml/graph_model.html)
+ [ Dokumentation zur PartiQL-Diagrammabfrage](https://partiql.org/gpml/graph_query.html)

Diese Reihe von Beispielen zeigt grundlegende Abfragen mit ihren Antworten. Verwenden Sie dies als Referenz, um Ihre eigenen Abfragen zu schreiben.

**Grundlegende Abfragen **  
+ **Ruft alle Entitäten mit einem Filter ab **

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

   Diese Abfrage gibt alle Entitäten in einem Workspace mit dem Namen zurück`room_0`.

  `FROM`clause: `EntityGraph` ist die Grafiksammlung, die alle Entitäten und ihre Beziehungen in einem Workspace enthält. Diese Sammlung wird automatisch auf der AWS IoT TwinMaker Grundlage der Entitäten in Ihrem Workspace erstellt und verwaltet.

  `MATCH`Klausel: gibt ein Muster an, das einem Teil des Diagramms entspricht. In diesem Fall `(entity)` entspricht das Muster jedem Knoten im Diagramm und ist an die Entitätsvariable gebunden. Auf die `FROM` Klausel muss die `MATCH` Klausel folgen.

  `WHERE`Klausel: gibt einen Filter für das `entityName` Feld des Knotens an, in dem der Wert übereinstimmen muss`room_0`.

  `SELECT`Klausel: gibt die `entity` Variable an, sodass der gesamte Entitätsknoten zurückgegeben wird.

  **Antwort:**

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

  Der `columnDescriptions` gibt Metadaten über die Spalte zurück, z. B. den Namen und den Typ. Der zurückgegebene Typ ist`NODE`. Dies zeigt an, dass der gesamte Knoten zurückgegeben wurde. Andere Werte für den Typ können sein`EDGE`, die auf eine Beziehung hinweisen würden`VALUE`, oder die auf einen Skalarwert wie eine Ganzzahl oder eine Zeichenfolge hinweisen würden.

  Der `rows` gibt eine Liste von Zeilen zurück. Da nur eine Entität gefunden wurde, `rowData` wird eine zurückgegeben, die alle Felder einer Entität enthält.
**Anmerkung**  
Im Gegensatz zu SQL, wo Sie nur Skalarwerte zurückgeben können, können Sie mit PartiQL ein Objekt (als JSON) zurückgeben.

  Jeder Knoten enthält alle Felder auf Entitätsebene wie`entityId`, `arn` und`components`, Felder auf Komponentenebene wie und sowie Felder auf Eigenschaftsebene `properties` wie `componentTypeId` und`componentName`, alles in Form eines verschachtelten JSONs. `propertyName` `propertyValue`
+ **Ruft alle Beziehungen mit einem Filter ab: **

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

  Diese Abfrage gibt alle Beziehungen in einem Workspace mit dem Beziehungsnamen zurück`isLocationOf`.

   Die `MATCH` Klausel: gibt ein Muster an, das zwei Knoten (gekennzeichnet durch`()`) entspricht, die durch eine gerichtete Kante (gekennzeichnet durch`-[]->`) verbunden und an eine Variable namens gebunden sind`relationship`.

  Die `WHERE` Klausel: spezifiziert einen Filter für das `relationshipName` Feld der Kante, in dem sich der Wert befindet`isLocationOf`.

  Die `SELECT` Klausel: gibt die Beziehungsvariable an, sodass der gesamte Kantenknoten zurückgegeben wird.

  **Antwort**

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

  Der Typ der Spalte in `columnDescriptions` ist ein`EDGE`.

  Jeder `rowData` steht für eine Kante mit Feldern wie`relationshipName`. Dies entspricht dem Namen der Beziehungseigenschaft, der für die Entität definiert ist. Die`sourceEntityId`, `sourceComponentName` und `sourceComponentTypeId` geben Informationen darüber, für welche Entität und Komponente die Beziehungseigenschaft definiert wurde. Das `targetEntityId` gibt an, auf welche Entität diese Beziehung zeigt.
+ **Ruft alle Entitäten ab, die eine bestimmte Beziehung zu einer bestimmten Entität haben **

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

  Diese Abfrage gibt alle Entitätsnamen aller Entitäten zurück, die eine `isLocationOf` Beziehung zu der `room_0` Entität haben.

  Die `MATCH` Klausel: gibt ein Muster an, das zwei beliebigen Knoten (`e1`,`e2`) entspricht, die eine gerichtete Kante (`r`) haben.

  Die `WHERE` Klausel: spezifiziert einen Filter für den Beziehungsnamen und den Namen der Quellentität.

  Die `SELECT` Klausel: gibt das `entityName` Feld im `e2` Knoten zurück.

  **Antwort**

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

  In den ColumnDescriptions ist der Typ der Spalte, `VALUE` da es sich um eine `entityName` Zeichenfolge handelt.

  Eine Entität,`floor_0`, wird zurückgegeben.

**SPIEL **  
Die folgenden Muster werden in einer `MATCH` Klausel unterstützt:  
+ Ordnen Sie Knoten 'b' zu, der auf Knoten 'a' zeigt:

  ```
  FROM EntityGraph MATCH (a)-[rel]-(b)
  ```
+ Finden Sie Knoten 'a', der auf Knoten 'b' zeigt:

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

  Es gibt keine Variable, die an eine Beziehung gebunden ist, vorausgesetzt, für die Beziehung muss kein Filter angegeben werden.
+ Ordnen Sie Knoten 'a', der auf Knoten 'b' zeigt, und Knoten 'b', der auf Knoten 'a' zeigt, zu:

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

  Dadurch werden zwei Treffer zurückgegeben: eine von 'a' nach 'b' und eine weitere von 'b' nach 'a', daher wird empfohlen, nach Möglichkeit gerichtete Kanten zu verwenden.
+ Der Beziehungsname ist auch eine Bezeichnung des Eigenschaftsdiagramms`EntityGraph`. Sie können also einfach den Beziehungsnamen nach einem Doppelpunkt (:) angeben, anstatt einen Filter `rel.relationshipName` in der `WHERE` Klausel anzugeben.

  ```
  FROM EntityGraph MATCH (a)-[:isLocationOf]-(b)
  ```
+ Verkettung: Muster können so verkettet werden, dass sie in mehreren Beziehungen übereinstimmen.

  ```
  FROM EntityGraph MATCH (a)-[rel1]->(b)-[rel2]-(c)
  ```
+ Variable Hop-Muster können sich auch über mehrere Knoten und Kanten erstrecken:

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

  Diese Abfrage entspricht jedem Muster, dessen Kanten innerhalb von 1 bis 5 Sprüngen von Knoten 'A' ausgehen. Die zulässigen Quantifizierer sind:

  `{m,n}`- zwischen m und n Wiederholungen

  `{m,}`- m oder mehr Wiederholungen.

**VON**:  
Ein Entitätsknoten kann verschachtelte Daten enthalten, z. B. Komponenten, die selbst weitere verschachtelte Daten wie Eigenschaften enthalten. Auf diese kann zugegriffen werden, indem die Verschachtelung des Ergebnisses des MATCH-Musters aufgehoben wird.  

```
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'
```
Greifen Sie auf verschachtelte Felder zu, indem Sie Punkte in eine Variable `.` eingeben. Ein Komma (,) wird verwendet, um Entitäten mit den darin enthaltenen Komponenten und dann mit den Eigenschaften in diesen Komponenten zu verschachteln (oder zu verbinden). `AS`wird verwendet, um eine Variable an die nicht verschachtelten Variablen zu binden, sodass sie in den OR-Klauseln verwendet werden können. `WHERE` `SELECT` Diese Abfrage gibt alle Entitäten zurück, die eine mit einem Wert benannte Eigenschaft `meeting` in einer Komponente `roomFunction` mit dem Komponententyp id enthalten `com.example.query.construction.room`   
Um auf mehrere verschachtelte Felder eines Felds zuzugreifen, z. B. auf mehrere Komponenten in einer Entität, verwenden Sie die Kommaschreibweise, um eine Verknüpfung durchzuführen.  

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

**WÄHLEN SIE: **  
+ Einen Knoten zurückgeben:

  ```
  SELECT e
  FROM EntityGraph MATCH (e)
  ```
+ Gibt eine Kante zurück:

  ```
  SELECT r
  FROM EntityGraph MATCH (e1)-[r]->(e2)
  ```
+ Gibt einen Skalarwert zurück:

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

  Formatieren Sie den Namen des Ausgabefeldes, indem Sie es mit einem Alias versehen. `AS` Hier wird nicht `propertyValue` als Spaltenname in der Antwort, sondern `roomfunction` zurückgegeben.
+ Aliase zurückgeben:

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

  Die Verwendung von Aliasen wird dringend empfohlen, um explizit zu sein, die Lesbarkeit zu erhöhen und Unklarheiten in Ihren Abfragen zu vermeiden.

**WO: **  
+ Die unterstützten logischen Operatoren sind `AND``NOT`, und`OR`.
+ Die unterstützten Vergleichsoperatoren sind `<` `<=``>`,`=>`,`=`, und`!=`.
+ Verwenden Sie das `IN` Schlüsselwort, wenn Sie mehrere `OR` Bedingungen für dasselbe Feld angeben möchten.
+ Filtern Sie nach einem Entitäts-, Komponenten- oder Eigenschaftsfeld:

  ```
  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 für die `configuration` Eigenschaft. Hier `unit` ist der Schlüssel in der Konfigurationskarte und der `Celsius` Wert.

  ```
  WHERE p.definition.configuration.unit = 'Celsius'
  ```
+ Prüfen Sie, ob eine Map-Eigenschaft einen bestimmten Schlüssel und Wert enthält:

  ```
  WHERE p.propertyValue.length = 20.0
  ```
+ Prüfen Sie, ob eine Karteneigenschaft einen bestimmten Schlüssel enthält:

  ```
  WHERE NOT p.propertyValue.length IS MISSING
  ```
+ Prüfen Sie, ob eine Listeneigenschaft einen bestimmten Wert enthält:

  ```
  WHERE 10.0 IN p.propertyValue
  ```
+ Verwenden Sie die `lower()` Funktion für Vergleiche ohne Berücksichtigung der Groß- und Kleinschreibung. Standardmäßig wird bei allen Vergleichen zwischen Groß- und Kleinschreibung unterschieden.

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

**WIE**:  
Nützlich, wenn Sie den genauen Wert für ein Feld nicht kennen und eine Volltextsuche für das angegebene Feld durchführen können. `%`steht für Null oder mehr.  

```
WHERE e.entityName LIKE '%room%'
```
+ Infix-Suche: `%room%`
+ Präfix-Suche: `room%`
+ Suffix-Suche: `%room`
+ Wenn Sie '%' in Ihren Werten haben, fügen Sie ein Escape-Zeichen in das ein `LIKE` und geben Sie das Escape-Zeichen mit `ESCAPE` an.

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

**UNVERWECHSELBAR**:  

```
SELECT DISTINCT c.componentTypeId
FROM EntityGraph MATCH (e), e.components AS c
```
+ Das `DISTINCT` Schlüsselwort entfernt Duplikate aus dem Endergebnis.

  `DISTINCT`wird bei komplexen Datentypen nicht unterstützt.

**ZÄHLEN **  

```
SELECT COUNT(e), COUNT(c.componentTypeId)
FROM EntityGraph MATCH (e), e.components AS c
```
+ Das `COUNT` Schlüsselwort berechnet die Anzahl der Elemente in einem Abfrageergebnis.
+ `COUNT`wird für verschachtelte komplexe Felder und Grafikmusterfelder nicht unterstützt.
+ `COUNT`Aggregation wird bei `DISTINCT` und verschachtelten Abfragen nicht unterstützt.

  Beispielsweise wird `COUNT(DISTINCT e.entityId)` nicht unterstützt.

**PFAD **  
Die folgenden Musterprojektionen werden bei Abfragen mithilfe der Pfadprojektion unterstützt:  
+ Variablen-Hop-Abfragen

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

  Bei dieser Abfrage werden Knotenmetadaten beliebiger Muster mit ausgehenden Kanten von Knoten * A * innerhalb von 1 bis 3 Hops abgeglichen und projiziert.
+ Hop-Abfragen wurden korrigiert

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

  Diese Abfrage entspricht und projiziert Metadaten von Entitäten und eingehenden Kanten auf * * b.
+ Ungerichtete Abfragen

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

  Diese Abfrage entspricht den Metadaten von Knoten in 1-Hop-Mustern, die * a * und * c * über * b * verbinden, und projiziert sie.

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

  Diese `PATH` Abfrageantwort besteht nur aus Metadaten, die alle Knoten und Kanten der einzelnen Knoten path/pattern zwischen * a * und * c * über * b identifizieren*.

**LIMIT ** und ** OFFSET**:  

```
SELECT e.entityName
FROM EntityGraph MATCH (e)
WHERE e.entityName LIKE 'room_%'
LIMIT 10
OFFSET 5
```
`LIMIT`gibt die Anzahl der Ergebnisse an, die in der Abfrage zurückgegeben werden sollen, und `OFFSET` gibt die Anzahl der zu überspringenden Ergebnisse an.

**LIMIT ** und ** MaxResults: **  
Das folgende Beispiel zeigt eine Abfrage, die insgesamt 500 Ergebnisse zurückgibt, pro API-Aufruf jedoch nur 50 Ergebnisse gleichzeitig anzeigt. Dieses Muster kann verwendet werden, wenn Sie die Anzahl der angezeigten Ergebnisse einschränken müssen, z. B. wenn Sie in einer Benutzeroberfläche nur 50 Ergebnisse anzeigen können.  

```
aws iottwinmaker execute-query \
--workspace-id exampleWorkspace \
--query-statement "SELECT e FROM EntityGraph MATCH (e) LIMIT 500"\
--max-results 50
```
+ Das `LIMIT` Schlüsselwort wirkt sich auf die Abfrage aus und begrenzt die resultierenden Zeilen. Wenn Sie die Anzahl der pro API-Aufruf zurückgegebenen Ergebnisse kontrollieren müssen, ohne die Gesamtzahl der zurückgegebenen Ergebnisse zu begrenzen, verwenden Sie`LIMIT`.
+ `max-results`ist ein optionaler Parameter für die [ ExecuteQuery API-Aktion](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_ExecuteQuery.html). `max-results`gilt nur für die API und dafür, wie Ergebnisse innerhalb der Grenzen der obigen Abfrage gelesen werden.

  Die Verwendung `max-results` in einer Abfrage ermöglicht es Ihnen, die Anzahl der angezeigten Ergebnisse zu reduzieren, ohne die tatsächliche Anzahl der zurückgegebenen Ergebnisse einzuschränken.
Die folgende Abfrage wiederholt die nächste Ergebnisseite. Diese Abfrage verwendet den `ExecuteQuery` API-Aufruf, um die Zeilen 51-100 zurückzugeben, wobei die nächste Ergebnisseite durch das angegeben wird `next-token` — in diesem Fall lautet das 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"
```
+ Die `next-token` Zeichenfolge gibt die nächste Seite mit Ergebnissen an. Weitere Informationen finden Sie unter der [ ExecuteQuery ](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_ExecuteQuery.html#API_ExecuteQuery_RequestSyntax) API-Aktion.

AWS IoT TwinMaker Für die Knowledge Graph-Abfrage gelten die folgenden Einschränkungen: 



| Bezeichnung des Limits | Kontingent | Einstellbar | 
| --- | --- | --- | 
| Zeitüberschreitung für die Abfrageausführung | 10 Sekunden | Nein | 
| Maximale Anzahl von Sprüngen | 10 | Ja | 
| Maximale Anzahl von `JOIN` Selfs | 20 | Ja | 
| Maximale Anzahl projizierter Felder | 20 | Ja | 
| Maximale Anzahl bedingter Ausdrücke (`AND`,`OR`,`NOT`) | 10 | Ja | 
| Maximale Länge eines `LIKE` Ausdrucksmusters (einschließlich Platzhaltern und Escapes) | 20 | Ja | 
| Maximale Anzahl von Elementen, die in einer Klausel angegeben werden können IN | 10 | Ja | 
| Höchstwert für OFFSET | 3000 | Ja | 
| Maximalwert für `LIMIT` | 3000 | Ja | 
| Maximalwert für Traversierungen (\+) `OFFSET` `LIMIT` | 3000 | Ja |