Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# AWS IoT TwinMaker Knowledge Graph: risorse aggiuntive
<a name="tm-knowledge-graph-resources"></a>

Questa sezione fornisce esempi di base della sintassi PartiQL utilizzata per scrivere query nel knowledge graph, oltre a collegamenti alla documentazione PartiQL che fornisce informazioni sul modello di dati del knowledge graph.
+ [ Documentazione del modello di dati Graph PartiQL](https://partiql.org/gpml/graph_model.html)
+ [ Documentazione relativa alle query Graph PartiQL](https://partiql.org/gpml/graph_query.html)

Questa serie di esempi mostra le domande di base con le relative risposte. Usalo come riferimento per scrivere le tue domande.

**Interrogazioni di base **  
+ **Ottieni tutte le entità con un filtro **

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

   Questa query restituisce tutte le entità in uno spazio di lavoro con il nome`room_0`.

  `FROM`clausola: `EntityGraph` è la raccolta di grafici che contiene tutte le entità e le relative relazioni in uno spazio di lavoro. Questa raccolta viene creata e gestita automaticamente in AWS IoT TwinMaker base alle entità presenti nel tuo spazio di lavoro.

  `MATCH`clausola: specifica un modello che corrisponde a una parte del grafico. In questo caso, il pattern `(entity)` corrisponde a tutti i nodi del grafico ed è associato alla variabile di entità. La `FROM` clausola deve essere seguita dalla `MATCH` clausola.

  `WHERE`clausola: specifica un filtro sul `entityName` campo del nodo, in cui il valore deve corrispondere. `room_0`

  `SELECT`clausola: specifica la `entity` variabile in modo che venga restituito l'intero nodo dell'entità.

  **Risposta:**

  ```
  {
    "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`Restituisce i metadati sulla colonna, come il nome e il tipo. Il tipo restituito è. `NODE` Ciò indica che è stato restituito l'intero nodo. Altri valori per il tipo possono essere quelli `EDGE` che indicherebbero una relazione o `VALUE` che indicherebbero un valore scalare come un numero intero o una stringa.

  `rows`Restituisce un elenco di righe. Poiché è stata trovata una sola entità, ne `rowData` viene restituita una che contiene tutti i campi di un'entità.
**Nota**  
A differenza di SQL, in cui è possibile restituire solo valori scalari, è possibile restituire un oggetto (come JSON) utilizzando PartiQL.

  Ogni nodo contiene tutti i campi a livello di entità come `arn` e `entityId``components`, i campi a livello di componente come e i campi a livello di proprietà come `componentTypeId` e`componentName`, tutti `properties` come JSON annidato. `propertyName` `propertyValue`
+ **Ottieni ** tutte le relazioni con un filtro:

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

  Questa query restituisce tutte le relazioni in uno spazio di lavoro con il nome `isLocationOf` della relazione.

   La `MATCH` clausola: specifica uno schema che corrisponde a due nodi (indicati da`()`) collegati da un bordo diretto (indicato da`-[]->`) e legati a una variabile chiamata. `relationship`

  La `WHERE` clausola: specifica un filtro sul `relationshipName` campo del bordo, dove si trova il valore. `isLocationOf`

  La `SELECT` clausola: specifica la variabile di relazione in modo che venga restituito l'intero nodo edge.

  **Risposta**

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

  Il tipo di colonna in `columnDescriptions` è un. `EDGE`

  Ciascuno `rowData` rappresenta un bordo con campi come`relationshipName`. È lo stesso del nome della proprietà di relazione definito nell'entità. Il`sourceEntityId`, `sourceComponentName` e `sourceComponentTypeId` fornisce informazioni sull'entità e sul componente su cui è stata definita la proprietà della relazione. `targetEntityId`Specifica a quale entità è indirizzata questa relazione.
+ **Ottieni tutte le entità con una relazione specifica con un'entità specifica **

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

  Questa query restituisce tutti i nomi di entità di tutte le entità che hanno una `isLocationOf` relazione con l'`room_0`entità.

  La `MATCH` clausola: specifica un modello che corrisponde a due nodi qualsiasi (`e1`,`e2`) con un bordo diretto (`r`).

  La `WHERE` clausola: specifica un filtro sul nome della relazione e sul nome dell'entità di origine.

  La `SELECT` clausola: restituisce il `entityName` campo nel nodo. `e2`

  **Risposta**

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

  In ColumnDescriptions, il tipo di colonna è `VALUE` poiché `entityName` è una stringa.

  Viene restituita un'entità. `floor_0`

**CORRISPONDE **  
I seguenti modelli sono supportati in una `MATCH` clausola:  
+ Abbina il nodo «b» che punta al nodo «a»:

  ```
  FROM EntityGraph MATCH (a)-[rel]-(b)
  ```
+ Abbina il nodo «a» che punta al nodo «b»:

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

  Non esiste una variabile associata a una relazione, supponendo che non sia necessario specificare un filtro nella relazione.
+ Abbina il nodo «a» che punta al nodo «b» e il nodo «b» che punta al nodo «a»:

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

  Ciò restituirà due corrispondenze: una da «a» a «b» e un'altra da «b» a «a», quindi la raccomandazione è di utilizzare bordi diretti ove possibile.
+ Il nome della relazione è anche un'etichetta del grafico delle proprietà`EntityGraph`, quindi puoi semplicemente specificare il nome della relazione dopo i due punti (:)) invece di specificare un filtro `rel.relationshipName` nella `WHERE` clausola.

  ```
  FROM EntityGraph MATCH (a)-[:isLocationOf]-(b)
  ```
+ Concatenamento: i pattern possono essere concatenati in modo che corrispondano su più relazioni.

  ```
  FROM EntityGraph MATCH (a)-[rel1]->(b)-[rel2]-(c)
  ```
+ I pattern di hop variabili possono estendersi anche su più nodi e bordi:

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

  Questa query corrisponde a qualsiasi modello con bordi in uscita dal nodo 'a' entro 1-5 hop. I quantificatori consentiti sono:

  `{m,n}`- tra m e n ripetizioni

  `{m,}`- m o più ripetizioni.

**DA**:  
Un nodo di entità può contenere dati nidificati, ad esempio componenti che a loro volta contengono ulteriori dati nidificati come le proprietà. È possibile accedervi annullando la nidificazione del risultato del pattern 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'
```
Accedi ai campi annidati puntando `.` in una variabile. Una virgola (,) viene utilizzata per separare (o unire) le entità con i componenti all'interno e quindi le proprietà all'interno di tali componenti. `AS`viene utilizzato per associare una variabile alle variabili non annidate in modo che possano essere utilizzate nelle clausole or. `WHERE` `SELECT` Questa query restituisce tutte le entità che contengono una proprietà denominata `roomFunction` con valore `meeting` in un componente con tipo di componente id `com.example.query.construction.room`   
Per accedere a più campi annidati di un campo, ad esempio a più componenti di un'entità, usa la notazione con virgola per eseguire un'unione.  

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

**SELEZIONA: **  
+ Restituisci un nodo:

  ```
  SELECT e
  FROM EntityGraph MATCH (e)
  ```
+ Restituisci un bordo:

  ```
  SELECT r
  FROM EntityGraph MATCH (e1)-[r]->(e2)
  ```
+ Restituisce un valore scalare:

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

  Formatta il nome del campo di output assegnandogli un alias utilizzando. `AS` Qui, invece che `propertyValue` come nome di colonna nella risposta, `roomfunction` viene restituito.
+ Alias di ritorno:

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

  Si consiglia vivamente di utilizzare gli alias per essere espliciti, aumentare la leggibilità ed evitare ambiguità nelle query.

**DOVE: **  
+ Gli operatori logici supportati sono`AND`,`NOT`, e`OR`.
+ Gli operatori di confronto supportati sono `<` `<=``>`,`=>`,`=`, e`!=`.
+ Usa la `IN` parola chiave se desideri specificare più `OR` condizioni sullo stesso campo.
+ Filtra in base a un campo di entità, componente o proprietà:

  ```
  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'
  ```
+ Filtra sulla `configuration` proprietà. `unit`Ecco la chiave nella mappa di configurazione ed `Celsius` è il valore.

  ```
  WHERE p.definition.configuration.unit = 'Celsius'
  ```
+ Controlla se una proprietà della mappa contiene una chiave e un valore determinati:

  ```
  WHERE p.propertyValue.length = 20.0
  ```
+ Controlla se una proprietà della mappa contiene una determinata chiave:

  ```
  WHERE NOT p.propertyValue.length IS MISSING
  ```
+ Controlla se una proprietà di elenco contiene un determinato valore:

  ```
  WHERE 10.0 IN p.propertyValue
  ```
+ Usa la `lower()` funzione per i confronti senza distinzione tra maiuscole e minuscole. Per impostazione predefinita, tutti i confronti fanno distinzione tra maiuscole e minuscole.

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

**AD ESEMPIO**:  
Utile se non conosci il valore esatto di un campo e puoi eseguire una ricerca a testo completo sul campo specificato. `%`rappresenta zero o più.  

```
WHERE e.entityName LIKE '%room%'
```
+ Ricerca infissa: `%room%`
+ Ricerca per prefisso: `room%`
+ Ricerca per suffissi: `%room`
+ Se hai '%' nei tuoi valori, inserisci un carattere di escape `LIKE` e specifica il carattere di escape con`ESCAPE`.

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

**DISTINTO**:  

```
SELECT DISTINCT c.componentTypeId
FROM EntityGraph MATCH (e), e.components AS c
```
+ La `DISTINCT` parola chiave elimina i duplicati dal risultato finale.

  `DISTINCT`non è supportata su tipi di dati complessi.

**CONTA **  

```
SELECT COUNT(e), COUNT(c.componentTypeId)
FROM EntityGraph MATCH (e), e.components AS c
```
+ La `COUNT` parola chiave calcola il numero di elementi nel risultato di una query.
+ `COUNT`non è supportata nei campi complessi annidati e nei campi con pattern grafico.
+ `COUNT`l'aggregazione non è supportata con le query `DISTINCT` annidate.

  Ad esempio, `COUNT(DISTINCT e.entityId)` non è supportato.

**PERCORSO **  
Le seguenti proiezioni di pattern sono supportate nelle interrogazioni che utilizzano la proiezione del percorso:  
+ Interrogazioni con hop variabile

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

  Questa query abbina e proietta i metadati dei nodi di qualsiasi pattern con bordi in uscita dal nodo * a * entro 1-3 hop.
+ Query con hop fisso

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

  Questa query abbina e proietta i metadati delle entità e degli spigoli in entrata su b. * *
+ Interrogazioni non indirizzate

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

  Questa query corrisponde e proietta i metadati dei nodi in schemi a 1 hop che collegano * a * e * c tramite 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"
                          }
                      ]
                  }
              ]
          }
      ]
  }
  ```

  Questa risposta alla `PATH` query è composta solo da metadati che identificano tutti i nodi e gli spigoli di ciascuno path/pattern tra * a * e c via b. * * * *

**LIMIT ** e OFFSET: ** **  

```
SELECT e.entityName
FROM EntityGraph MATCH (e)
WHERE e.entityName LIKE 'room_%'
LIMIT 10
OFFSET 5
```
`LIMIT`specifica il numero di risultati da restituire nella query e `OFFSET` specifica il numero di risultati da ignorare.

**LIMIT ** e MaxResults: ** **  
L'esempio seguente mostra una query che restituisce 500 risultati in totale, ma ne visualizza solo 50 alla volta per chiamata API. Questo modello può essere utilizzato laddove è necessario limitare la quantità di risultati visualizzati, ad esempio se è possibile visualizzare solo 50 risultati in un'interfaccia utente.  

```
aws iottwinmaker execute-query \
--workspace-id exampleWorkspace \
--query-statement "SELECT e FROM EntityGraph MATCH (e) LIMIT 500"\
--max-results 50
```
+ La `LIMIT` parola chiave influisce sulla query e limita le righe risultanti. Se devi controllare il numero di risultati restituiti per chiamata API senza limitare il numero totale di risultati restituiti, usa`LIMIT`.
+ `max-results`è un parametro opzionale per l'azione [ ExecuteQuery ](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_ExecuteQuery.html) API. `max-results`si applica solo all'API e al modo in cui i risultati vengono letti entro i limiti della query precedente.

  L'utilizzo `max-results` in una query consente di ridurre il numero di risultati visualizzati senza limitare il numero effettivo di risultati restituiti.
La query riportata di seguito scorre nella pagina successiva dei risultati. Questa query utilizza la chiamata `ExecuteQuery` API per restituire le righe 51-100, dove la pagina successiva dei risultati è specificata da `next-token` — in questo caso il 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"
```
+ La `next-token` stringa specifica la pagina successiva dei risultati. Per ulteriori informazioni, consulta l'azione [ ExecuteQuery ](https://docs.aws.amazon.com/iot-twinmaker/latest/apireference/API_ExecuteQuery.html#API_ExecuteQuery_RequestSyntax) API.

AWS IoT TwinMaker L'interrogazione con knowledge graph presenta i seguenti limiti: 



| Nome del limite | Quota | Regolabile | 
| --- | --- | --- | 
| Timeout di esecuzione della query | 10 secondi | No | 
| Numero massimo di salti | 10 | Sì | 
| Numero massimo di sé s `JOIN` | 20 | Sì | 
| Numero massimo di campi proiettati | 20 | Sì | 
| Numero massimo di espressioni condizionali (`AND`,,`OR`) `NOT` | 10 | Sì | 
| Lunghezza massima di un modello di `LIKE` espressione (inclusi caratteri jolly e escape) | 20 | Sì | 
| Numero massimo di elementi che possono essere specificati in una clausola IN | 10 | Sì | 
| Valore massimo per OFFSET | 3000 | Sì | 
| Valore massimo per `LIMIT` | 3000 | Sì | 
| Valore massimo per gli attraversamenti (\+) `OFFSET` `LIMIT` | 3000 | Sì |