Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# AWS IoT TwinMaker Knowledge Graph (ressources supplémentaires)
<a name="tm-knowledge-graph-resources"></a>

Cette section fournit des exemples de base de la syntaxe partiQL utilisée pour écrire des requêtes dans le graphe de connaissances, ainsi que des liens vers la documentation partiQL qui fournit des informations sur le modèle de données du graphe de connaissances.
+ [ Documentation sur les modèles de données graphiques PartiQL](https://partiql.org/gpml/graph_model.html)
+ [ Documentation sur les requêtes graphiques PartiQL](https://partiql.org/gpml/graph_query.html)

Cet ensemble d'exemples montre les requêtes de base avec leurs réponses. Utilisez-le comme référence pour rédiger vos propres requêtes.

**Requêtes de base**  
+ **Obtenir toutes les entités à l'aide d'un filtre**

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

   Cette requête renvoie toutes les entités d'un espace de travail portant le nom`room_0`.

  `FROM`clause : `EntityGraph` est la collection de graphes qui contient toutes les entités et leurs relations dans un espace de travail. Cette collection est automatiquement créée et gérée en AWS IoT TwinMaker fonction des entités de votre espace de travail.

  `MATCH`clause : spécifie un modèle qui correspond à une partie du graphique. Dans ce cas, le modèle `(entity)` correspond à chaque nœud du graphe et est lié à la variable d'entité. La `FROM` clause doit être suivie de la `MATCH` clause.

  `WHERE`clause : spécifie un filtre sur le `entityName` champ du nœud, où la valeur doit correspondre`room_0`.

  `SELECT`clause : spécifie la `entity` variable afin que l'ensemble du nœud de l'entité soit renvoyé.

  **Réponse :**

  ```
  {
    "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`Renvoie les métadonnées relatives à la colonne, telles que le nom et le type. Le type renvoyé est`NODE`. Cela indique que le nœud entier a été renvoyé. Les autres valeurs du type peuvent `EDGE` indiquer une relation ou `VALUE` une valeur scalaire telle qu'un entier ou une chaîne.

  `rows`Renvoie une liste de lignes. Comme une seule entité a été mise en correspondance, `rowData` une entité contenant tous les champs d'une entité est renvoyée.
**Note**  
Contrairement au SQL où vous ne pouvez renvoyer que des valeurs scalaires, vous pouvez renvoyer un objet (au format JSON) en utilisant partiQL.

  Chaque nœud contient tous les champs au niveau de l'entité tels que`entityId`, `arn` et les champs au niveau des composants tels que`components`, et, ainsi que les champs au niveau de la propriété tels que `componentTypeId` et `componentName``properties`, le tout sous forme de JSON `propertyName` `propertyValue` imbriqué.
+ **Obtenez toutes les relations à l'aide d'un filtre** :

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

  Cette requête renvoie toutes les relations d'un espace de travail avec le nom de la relation`isLocationOf`.

   La `MATCH` clause : spécifie un modèle qui correspond à deux nœuds (indiqués par`()`) connectés par une arête dirigée (indiquée par`-[]->`) et liés à une variable appelée`relationship`.

  La `WHERE` clause : spécifie un filtre sur le `relationshipName` champ de l'arête, où se trouve la valeur`isLocationOf`.

  La `SELECT` clause : spécifie la variable de relation afin que l'ensemble du nœud périphérique soit renvoyé.

  **Réponse**

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

  Le type de colonne dans `columnDescriptions` est un`EDGE`.

  Chacun `rowData` représente une arête avec des champs tels que`relationshipName`. Il est identique au nom de propriété de relation défini sur l'entité. Les`sourceEntityId`, `sourceComponentName` et `sourceComponentTypeId` fournissent des informations sur l'entité et le composant sur lesquels la propriété de relation a été définie. `targetEntityId`Spécifie l'entité vers laquelle cette relation pointe.
+ **Obtenez toutes les entités ayant une relation spécifique avec une entité spécifique**

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

  Cette requête renvoie tous les noms d'entité de toutes les entités ayant une `isLocationOf` relation avec l'`room_0`entité.

  La `MATCH` clause : spécifie un modèle qui correspond à deux nœuds (`e1`,`e2`) ayant une arête dirigée (`r`).

  La `WHERE` clause : spécifie un filtre sur le nom de la relation et le nom de l'entité source.

  La `SELECT` clause : renvoie le `entityName` champ dans le `e2` nœud.

  **Réponse**

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

  Dans les ColumnDescriptions, le type de la colonne est `VALUE` puisque c'`entityName`est une chaîne.

  Une entité est renvoyée. `floor_0`

**CORRESPONDRE**  
Les modèles suivants sont pris en charge dans une `MATCH` clause :  
+ Faites correspondre le nœud « b » pointant vers le nœud « a » :

  ```
  FROM EntityGraph MATCH (a)-[rel]-(b)
  ```
+ Faites correspondre le nœud « a » pointant vers le nœud « b » :

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

  Aucune variable n'est liée à une relation en supposant qu'il n'est pas nécessaire de spécifier un filtre sur la relation.
+ Faites correspondre le nœud « a » pointant vers le nœud « b » et le nœud « b » pointant vers le nœud « a » :

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

  Cela renverra deux correspondances : une de « a » à « b » et une autre de « b » à « a ». Il est donc recommandé d'utiliser des arêtes orientées dans la mesure du possible.
+ Le nom de la relation est également une étiquette du graphe `EntityGraph` de propriétés. Vous pouvez donc simplement spécifier le nom de la relation après deux points (:) au lieu de spécifier un filtre `rel.relationshipName` dans la `WHERE` clause.

  ```
  FROM EntityGraph MATCH (a)-[:isLocationOf]-(b)
  ```
+ Enchaînement : les modèles peuvent être enchaînés pour correspondre à plusieurs relations.

  ```
  FROM EntityGraph MATCH (a)-[rel1]->(b)-[rel2]-(c)
  ```
+ Les modèles de sauts variables peuvent également s'étendre sur plusieurs nœuds et arêtes :

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

  Cette requête correspond à n'importe quel modèle avec des arêtes sortantes du nœud « a » entre 1 et 5 sauts. Les quantificateurs autorisés sont les suivants :

  `{m,n}`- entre m et n répétitions

  `{m,}`- 5 répétitions ou plus.

**À PARTIR DE** :  
Un nœud d'entité peut contenir des données imbriquées, telles que des composants qui contiennent eux-mêmes d'autres données imbriquées telles que des propriétés. Vous pouvez y accéder en démêlant le résultat du modèle 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'
```
Accédez aux champs imbriqués en pointant des points `.` dans une variable. Une virgule (,) est utilisée pour désimbriquer (ou joindre) des entités contenant les composants, puis les propriétés contenues dans ces composants. `AS`est utilisé pour lier une variable aux variables non imbriquées afin qu'elles puissent être utilisées dans les clauses `WHERE` or`SELECT`. Cette requête renvoie toutes les entités qui contiennent une propriété nommée `roomFunction` avec une valeur `meeting` dans un composant avec un identifiant de type de composant `com.example.query.construction.room`   
Pour accéder à plusieurs champs imbriqués d'un champ, tels que plusieurs composants d'une entité, utilisez la notation par virgule pour effectuer une jointure.  

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

**SÉLECTIONNEZ** :  
+ Renvoie un nœud :

  ```
  SELECT e
  FROM EntityGraph MATCH (e)
  ```
+ Renvoie une arête :

  ```
  SELECT r
  FROM EntityGraph MATCH (e1)-[r]->(e2)
  ```
+ Renvoie une valeur scalaire :

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

  Formatez le nom du champ de sortie en lui attribuant un alias en utilisant`AS`. Ici, au lieu d'`propertyValue`un nom de colonne dans la réponse, `roomfunction` il est renvoyé.
+ Alias de retour :

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

  Il est fortement recommandé d'utiliser des alias pour être explicite, améliorer la lisibilité et éviter toute ambiguïté dans vos requêtes.

**OÙ** :  
+ Les opérateurs logiques pris en charge sont `AND``NOT`, et`OR`.
+ Les opérateurs de comparaison pris en charge sont `<` `<=``>`,`=>`,`=`, et`!=`.
+ Utilisez le `IN` mot clé si vous souhaitez spécifier plusieurs `OR` conditions dans le même champ.
+ Filtrez sur un champ d'entité, de composant ou de propriété :

  ```
  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'
  ```
+ Filtrez sur la `configuration` propriété. `unit`Voici la clé de la carte de configuration et `Celsius` la valeur.

  ```
  WHERE p.definition.configuration.unit = 'Celsius'
  ```
+ Vérifiez si une propriété de carte contient une clé et une valeur données :

  ```
  WHERE p.propertyValue.length = 20.0
  ```
+ Vérifiez si une propriété de carte contient une clé donnée :

  ```
  WHERE NOT p.propertyValue.length IS MISSING
  ```
+ Vérifiez si une propriété de liste contient une valeur donnée :

  ```
  WHERE 10.0 IN p.propertyValue
  ```
+ Utilisez cette `lower()` fonction pour les comparaisons sans distinction majuscules/majuscules. Par défaut, toutes les comparaisons font la distinction majuscules/minuscules.

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

**COMME** :  
Utile si vous ne connaissez pas la valeur exacte d'un champ et que vous pouvez effectuer une recherche en texte intégral sur le champ spécifié. `%`représente zéro ou plus.  

```
WHERE e.entityName LIKE '%room%'
```
+ Recherche d'infixes : `%room%`
+ Recherche par préfixe : `room%`
+ Recherche de suffixes : `%room`
+ Si vous avez « % » dans vos valeurs, insérez un caractère d'échappement dans `LIKE` et spécifiez le caractère d'échappement avec`ESCAPE`.

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

**DISTINCT** :  

```
SELECT DISTINCT c.componentTypeId
FROM EntityGraph MATCH (e), e.components AS c
```
+ Le `DISTINCT` mot clé élimine les doublons du résultat final.

  `DISTINCT`n'est pas pris en charge sur les types de données complexes.

**COMPTER**  

```
SELECT COUNT(e), COUNT(c.componentTypeId)
FROM EntityGraph MATCH (e), e.components AS c
```
+ Le `COUNT` mot clé calcule le nombre d'éléments dans le résultat d'une requête.
+ `COUNT`n'est pas pris en charge sur les champs complexes imbriqués et les champs de modèle graphique.
+ `COUNT`l'agrégation n'est pas prise en charge par `DISTINCT` les requêtes imbriquées.

  Par exemple, `COUNT(DISTINCT e.entityId)` n’est pas pris en charge.

**CHEMIN**  
Les projections de modèles suivantes sont prises en charge lors des requêtes utilisant la projection de trajectoire :  
+ Requêtes à sauts variables

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

  Cette requête fait correspondre et projette les métadonnées des nœuds de tous les modèles présentant des bords sortants depuis le nœud *a* en 1 à 3 sauts.
+ Requêtes à saut fixe

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

  Cette requête fait correspondre et projette les métadonnées des entités et des arêtes entrantes vers *b.*
+ Requêtes non dirigées

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

  Cette requête correspond et projette les métadonnées des nœuds dans des modèles à 1 saut reliant *a* et *c* via *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"
                          }
                      ]
                  }
              ]
          }
      ]
  }
  ```

  Cette réponse à la `PATH` requête comprend uniquement des métadonnées qui identifient tous les nœuds et les arêtes de chacun path/pattern entre *a* et *c* via *b.*

**LIMITE** et **DÉCALAGE** :  

```
SELECT e.entityName
FROM EntityGraph MATCH (e)
WHERE e.entityName LIKE 'room_%'
LIMIT 10
OFFSET 5
```
`LIMIT`indique le nombre de résultats à renvoyer dans la requête, ainsi `OFFSET` que le nombre de résultats à ignorer.

**LIMIT** et **MaxResults** :  
L'exemple suivant montre une requête qui renvoie 500 résultats au total, mais qui n'en affiche que 50 à la fois par appel d'API. Ce modèle peut être utilisé lorsque vous devez limiter le nombre de résultats affichés, par exemple si vous ne pouvez afficher que 50 résultats dans une interface utilisateur.  

```
aws iottwinmaker execute-query \
--workspace-id exampleWorkspace \
--query-statement "SELECT e FROM EntityGraph MATCH (e) LIMIT 500"\
--max-results 50
```
+ Le `LIMIT` mot clé affecte la requête et limite les lignes qui en résultent. Si vous devez contrôler le nombre de résultats renvoyés par appel d'API sans limiter le nombre total de résultats renvoyés, utilisez`LIMIT`.
+ `max-results`est un paramètre facultatif pour l'[action d'ExecuteQuery API](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html). `max-results`s'applique uniquement à l'API et à la façon dont les résultats sont lus dans les limites de la requête ci-dessus.

  L'utilisation `max-results` dans une requête vous permet de réduire le nombre de résultats affichés sans limiter le nombre réel de résultats renvoyés.
La requête ci-dessous passe par la page de résultats suivante. Cette requête utilise l'appel d'`ExecuteQuery`API pour renvoyer les lignes 51 à 100, où la page de résultats suivante est spécifiée par le `next-token` — dans ce cas, le jeton est :. `"H7kyGmvK376L"`  

```
aws iottwinmaker execute-query \
--workspace-id exampleWorkspace \
--query-statement "SELECT e FROM EntityGraph MATCH (e) LIMIT 500"\
--max-results 50
--next-token "H7kyGmvK376L"
```
+ La `next-token` chaîne indique la page de résultats suivante. Pour plus d'informations, consultez l'action de [ ExecuteQuery](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html#API_ExecuteQuery_RequestSyntax)l'API.

AWS IoT TwinMaker Les limites d'une requête Knowledge Graph sont les suivantes : 


****  

| Nom de la limite | Quota | Ajustable | 
| --- | --- | --- | 
| Délai d'exécution de la requête | 10 secondes | Non | 
| Nombre maximum de sauts | 10 | Oui | 
| Nombre maximum de `JOIN` self-s | 20 | Oui | 
| Nombre maximum de champs projetés | 20 | Oui | 
| Nombre maximum d'expressions conditionnelles (`AND`,`OR`,`NOT`) | 10 | Oui | 
| Longueur maximale d'un modèle d'`LIKE`expression (y compris les caractères génériques et les échappements) | 20 | Oui | 
| Nombre maximum d'éléments pouvant être spécifiés dans une IN clause | 10 | Oui | 
| Valeur maximale pour OFFSET | 3000 | Oui | 
| Valeur maximale pour `LIMIT` | 3000 | Oui | 
| Valeur maximale pour les traversées (`OFFSET`\+`LIMIT`) | 3000 | Oui |