Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

# AWS IoT TwinMaker gráfico de conocimiento, recursos adicionales
<a name="tm-knowledge-graph-resources"></a>

Esta sección proporciona ejemplos básicos de la sintaxis PartiQL utilizada para escribir consultas en el gráfico de conocimiento, así como enlaces a la documentación de PartiQL que proporciona información sobre el modelo de datos del gráfico de conocimiento.
+ [Documentación del modelo de datos de gráficos de PartiQL](https://partiql.org/gpml/graph_model.html)
+ [Documentación de consultas de gráficos de PartiQL](https://partiql.org/gpml/graph_query.html)

En este conjunto de ejemplos se muestran las consultas básicas con sus respuestas. Utilízalo como referencia para escribir tus propias consultas.

**Consultas básicas**  
+ **Obtenga todas las entidades con un filtro**

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

   Esta consulta devuelve todas las entidades de un espacio de trabajo con el nombre`room_0`.

  `FROM`cláusula: `EntityGraph` es la colección de gráficos que contiene todas las entidades y sus relaciones en un espacio de trabajo. Esta colección se crea y administra automáticamente en AWS IoT TwinMaker función de las entidades de su espacio de trabajo.

  Cláusula `MATCH`: especifica un patrón que coincide con una parte del gráfico. En este caso, el patrón `(entity)` coincide con todos los nodos del gráfico y está vinculado a la variable de entidad. La cláusula `FROM` debe ir seguida de la cláusula `MATCH`.

  `WHERE`cláusula: especifica un filtro en el `entityName` campo del nodo, donde el valor debe coincidir`room_0`.

  `SELECT`cláusula: especifica la `entity` variable para que se devuelva todo el nodo de la entidad.

  **Respuesta**:

  ```
  {
    "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`Devuelve metadatos sobre la columna, como el nombre y el tipo. El tipo devuelto es `NODE`. Esto indica que se ha devuelto todo el nodo. Otros valores del tipo pueden `EDGE` indicar una relación o `VALUE` indicar un valor escalar, como un entero o una cadena.

  `rows` devuelve una lista de filas. Como solo coincidió una entidad, se devuelve un `rowData` que contiene todos los campos de una entidad.
**nota**  
A diferencia de SQL, donde solo puede devolver valores escalares, puede devolver un objeto (como JSON) mediante PartiQL.

  Cada nodo contiene todos los campos a nivel de entidad, por ejemplo`entityId`, `arn` y los campos a nivel de componente`components`, así como los campos a nivel de propiedad`componentName`, `properties` como `componentTypeId` y, todo ello en formato JSON `propertyName` anidado. `propertyValue`
+ **Obtenga todas las relaciones con un filtro**:

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

  Esta consulta devuelve todas las relaciones de un espacio de trabajo con el nombre de la relación `isLocationOf`.

   La `MATCH` cláusula: especifica un patrón que coincide con dos nodos (indicados por`()`) que están conectados por un borde dirigido (indicados por`-[]->`) y enlazados a una variable llamada. `relationship`

  La `WHERE` cláusula: especifica un filtro en el `relationshipName` campo del borde, donde está el valor`isLocationOf`.

  Cláusula `SELECT`: especifica la variable de relación para que se devuelva todo el nodo de borde.

  **Respuesta**

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

  El tipo de columna `columnDescriptions` es un`EDGE`.

  Cada uno `rowData` representa un borde con campos como`relationshipName`. Es el mismo que el nombre de la propiedad de relación definido en la entidad. Los `sourceEntityId` `sourceComponentName` y `sourceComponentTypeId` proporcionan información sobre la entidad y el componente en los que se definió la propiedad de relación. `targetEntityId`Especifica a qué entidad apunta esta relación.
+ **Obtenga todas las entidades con una relación específica con una entidad específica**

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

  Esta consulta devuelve todos los nombres de las entidades que tienen una `isLocationOf` relación con la `room_0` entidad.

  La `MATCH` cláusula: especifica un patrón que coincide con dos nodos (`e1`,`e2`) que tengan una arista dirigida (`r`).

  Cláusula `WHERE`: especifica un filtro en el nombre de la relación y el nombre de la entidad de origen.

  La `SELECT` cláusula: devuelve el `entityName` campo del `e2` nodo.

  **Respuesta**

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

  En las descripciones de columnas, el tipo de columna es `VALUE` ya que `entityName` es una cadena.

  Se devuelve una entidad,`floor_0`,.

**MATCH**  
Una `MATCH` cláusula admite los siguientes patrones:  
+ Haga coincidir el nodo «b» con el nodo «a»:

  ```
  FROM EntityGraph MATCH (a)-[rel]-(b)
  ```
+ Haga coincidir el nodo «a» con el nodo «b»:

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

  No hay ninguna variable vinculada a una relación, suponiendo que no es necesario especificar un filtro en la relación.
+ Haga coincidir el nodo «a» que apunta al nodo «b» y el nodo «b» que apunta al nodo «a»:

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

  Esto devolverá dos coincidencias: una de «a» a «b» y otra de «b» a «a», por lo que se recomienda utilizar bordes dirigidos siempre que sea posible.
+ El nombre de la relación también es una etiqueta del gráfico de propiedades`EntityGraph`, por lo que simplemente puede especificar el nombre de la relación después de dos puntos (:)) en lugar de especificar un filtro `rel.relationshipName` en la `WHERE` cláusula.

  ```
  FROM EntityGraph MATCH (a)-[:isLocationOf]-(b)
  ```
+ Encadenamiento: los patrones se pueden encadenar para que coincidan en varias relaciones.

  ```
  FROM EntityGraph MATCH (a)-[rel1]->(b)-[rel2]-(c)
  ```
+ Los patrones de saltos variables también pueden abarcar varios nodos y bordes:

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

  Esta consulta hace coincidir cualquier patrón con los bordes salientes del nodo «a» con un intervalo de 1 a 5 saltos. Los cuantificadores permitidos son:

  `{m,n}`: entre m y n repeticiones

  `{m,}`: m o más repeticiones.

**FROM**:  
Un nodo de entidad puede contener datos anidados, como componentes que, a su vez, contienen más datos anidados, como propiedades. Se puede acceder a ellos deshaciendo el resultado del patrón 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'
```
Acceda a los campos anidados colocando puntos `.` en una variable. Se usa una coma (,) para separar (o unir) las entidades con los componentes dentro y, después, las propiedades dentro de esos componentes. `AS`se usa para vincular una variable a las variables no anidadas para que puedan usarse en las cláusulas o. `WHERE` `SELECT` Esta consulta devuelve todas las entidades que contienen una propiedad denominada `roomFunction` con un valor `meeting` en un componente con el id de tipo de componente `com.example.query.construction.room`   
Para acceder a varios campos anidados de un campo, como varios componentes de una entidad, utilice la notación de coma para realizar una unión.  

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

**SELECT**  
+ Devuelve un nodo:

  ```
  SELECT e
  FROM EntityGraph MATCH (e)
  ```
+ Devuelve una ventaja:

  ```
  SELECT r
  FROM EntityGraph MATCH (e1)-[r]->(e2)
  ```
+ Devuelve un valor escalar:

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

  Formatee el nombre del campo de salida asignándole un alias con `AS`. Aquí, en lugar de `propertyValue` como nombre de columna en la respuesta, se devuelve `roomfunction`.
+ Devolver 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%'
  ```

  Se recomienda encarecidamente utilizar alias para ser explícito, aumentar la legibilidad y evitar cualquier ambigüedad en las consultas.

**WHERE**:  
+ Los operadores lógicos compatibles son`AND`, y. `NOT` `OR`
+ Los operadores de comparación compatibles son `<`, `<=`, `>`, `=>`, `=` y `!=`.
+ Utilice la `IN` palabra clave si desea especificar varias `OR` condiciones en el mismo campo.
+ Filtre por un campo de entidad, componente o propiedad:

  ```
  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 por `configuration` propiedad. Aquí `unit` está la clave del mapa de configuración y `Celsius` es el valor.

  ```
  WHERE p.definition.configuration.unit = 'Celsius'
  ```
+ Compruebe si una propiedad del mapa contiene una clave y un valor determinados:

  ```
  WHERE p.propertyValue.length = 20.0
  ```
+ Compruebe si una propiedad del mapa contiene una clave determinada:

  ```
  WHERE NOT p.propertyValue.length IS MISSING
  ```
+ Compruebe si una propiedad de la lista contiene un valor determinado:

  ```
  WHERE 10.0 IN p.propertyValue
  ```
+ Utilice la función `lower()` para realizar comparaciones que no distingan mayúsculas de minúsculas. De forma predeterminada, la comparación distingue entre mayúsculas y minúsculas.

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

**LIKE**:  
Es útil si no conoce el valor exacto de un campo y puede realizar una búsqueda de texto completo en el campo especificado. `%` representa cero o más.  

```
WHERE e.entityName LIKE '%room%'
```
+ Búsqueda de infijos: `%room%`
+ Búsqueda de prefijos: `room%`
+ Búsqueda de sufijos: `%room`
+ Si sus valores son «%», coloque un carácter de escape en `LIKE` y especifique el carácter de escape con`ESCAPE`.

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

**DISTINCT**:  

```
SELECT DISTINCT c.componentTypeId
FROM EntityGraph MATCH (e), e.components AS c
```
+ La palabra clave `DISTINCT` elimina los duplicados del resultado final.

  `DISTINCT` no se admite en tipos de datos complejos.

COUNT  

```
SELECT COUNT(e), COUNT(c.componentTypeId)
FROM EntityGraph MATCH (e), e.components AS c
```
+ La `COUNT` palabra clave calcula el número de elementos del resultado de una consulta.
+ `COUNT`no se admite en campos complejos anidados ni en campos de patrones de gráficos.
+ `COUNT`la agregación no es compatible con `DISTINCT` las consultas anidadas.

  Por ejemplo, `COUNT(DISTINCT e.entityId)` no se admite.

**RUTA**  
Las siguientes proyecciones de patrones son compatibles con las consultas mediante la proyección de trayectoria:  
+ Consultas de saltos variables

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

  Esta consulta hace coincidir los metadatos de los nodos de cualquier patrón y los proyecta, con los bordes salientes del nodo a en *un* intervalo de 1 a 3 saltos.
+ Consultas de salto fijo

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

  Esta consulta coincide con los metadatos de las entidades y los bordes entrantes y los proyecta en *b*.
+ Consultas no dirigidas

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

  *Esta consulta compara y proyecta los metadatos de los nodos en patrones de 1 salto que conectan a y *c* a través de *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"
                          }
                      ]
                  }
              ]
          }
      ]
  }
  ```

  Esta respuesta a la `PATH` consulta se compone únicamente de metadatos que identifican todos los nodos y bordes de cada uno de ellos path/pattern entre *a* y *c* a través de *b*.

**LÍMITE** Y **COMPENSACIÓN**:  

```
SELECT e.entityName
FROM EntityGraph MATCH (e)
WHERE e.entityName LIKE 'room_%'
LIMIT 10
OFFSET 5
```
`LIMIT` especifica el número de resultados que se devolverán en la consulta y `OFFSET` el número de resultados que se van a omitir.

**LIMIT** y **MaxResults**:  
El siguiente ejemplo muestra una consulta que devuelve 500 resultados en total, pero solo muestra 50 a la vez por llamada a la API. Este patrón se puede usar cuando necesite limitar la cantidad de resultados mostrados, por ejemplo, si solo puede mostrar 50 resultados en una interfaz de usuario.  

```
aws iottwinmaker execute-query \
--workspace-id exampleWorkspace \
--query-statement "SELECT e FROM EntityGraph MATCH (e) LIMIT 500"\
--max-results 50
```
+ La `LIMIT` palabra clave afecta a la consulta y limita las filas resultantes. Si necesitas controlar el número de resultados devueltos por llamada a la API sin limitar el número total de resultados devueltos, utiliza`LIMIT`.
+ `max-results`es un parámetro opcional para la [acción de la ExecuteQuery API](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html). `max-results`solo se aplica a la API y a la forma en que se leen los resultados dentro de los límites de la consulta anterior.

  El uso `max-results` en una consulta permite reducir el número de resultados mostrados sin limitar el número real de resultados devueltos.
La siguiente consulta recorre la siguiente página de resultados. Esta consulta utiliza la llamada a la `ExecuteQuery` API para devolver las filas 51 a 100, donde la siguiente página de resultados se especifica mediante el símbolo `next-token` (en este caso, el token es:). `"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` cadena especifica la siguiente página de resultados. Para obtener más información, consulta la acción [ ExecuteQuery](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html#API_ExecuteQuery_RequestSyntax)de la API.

AWS IoT TwinMaker La consulta de Knowledge Graph tiene los siguientes límites: 


****  

| Nombre del límite  | Cuota | Ajustable | 
| --- | --- | --- | 
|  Tiempo de espera de ejecución de la consulta  | 10 segundos | No | 
|  Número máximo de saltos  | 10 | Sí | 
|  Número máximo de sí mismos `JOIN`  | 20 | Sí | 
|  Número máximo de campos proyectados  | 20 | Sí | 
|  Número máximo de expresiones condicionales (`AND`,`OR`,`NOT`)  | 10 | Sí | 
|  Longitud máxima de un patrón de `LIKE` expresión (incluidos los caracteres comodín y los escapes)  | 20 | Sí | 
| Número máximo de elementos que se pueden especificar en una cláusula IN | 10 | Sí | 
| Valor máximo para OFFSET | 3 000 | Sí | 
|  Valor máximo para `LIMIT`  | 3 000 | Sí | 
|  Valor máximo para los recorridos (\$1) `OFFSET` `LIMIT`  | 3 000 | Sí |