As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# AWS IoT TwinMaker recursos adicionais do gráfico de conhecimento
<a name="tm-knowledge-graph-resources"></a>

Esta seção fornece exemplos básicos da sintaxe do partiQL usada para escrever consultas no gráfico de conhecimento, bem como links para a documentação do partiQL que fornecem informações sobre o modelo de dados do gráfico de conhecimento.
+ [Documentação do modelo de dados gráficos PartiQL](https://partiql.org/gpml/graph_model.html)
+ [Documentação de consulta gráfica PartiQL](https://partiql.org/gpml/graph_query.html)

Esse conjunto de exemplos mostra consultas básicas com suas respostas. Use isso como referência para escrever suas próprias consultas.

**Consultas básicas**  
+ **Obtenha todas as entidades com um filtro**

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

   Essa consulta retorna todas as entidades em um espaço de trabalho com o nome`room_0`.

  `FROM`cláusula: `EntityGraph` é a coleção de gráficos que contém todas as entidades e seus relacionamentos em um espaço de trabalho. Essa coleção é criada e gerenciada automaticamente AWS IoT TwinMaker com base nas entidades em seu espaço de trabalho.

  Cláusula `MATCH`: especifica um padrão que corresponde a uma parte do gráfico. Nesse caso, o padrão `(entity)` corresponde a cada nó no gráfico e está vinculado à variável da entidade. A cláusula `FROM` deve ser seguida pela cláusula `MATCH`.

  `WHERE`cláusula: especifica um filtro no `entityName` campo do nó, onde o valor deve corresponder. `room_0`

  `SELECT`cláusula: especifica a `entity` variável para que todo o nó da entidade seja retornado.

  **Resposta:**

  ```
  {
    "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`Retorna metadados sobre a coluna, como nome e tipo. O tipo retornado é `NODE`. Isso indica que o nó inteiro foi retornado. Outros valores para o tipo podem `EDGE` indicar uma relação ou `VALUE` indicar um valor escalar, como um inteiro ou uma string.

  O `rows` retorna uma lista de linhas. Como apenas uma entidade foi correspondida, um `rowData` é retornado, que contém todos os campos em uma entidade.
**nota**  
Ao contrário do SQL, em que você só pode retornar valores escalares, você pode retornar um objeto (como JSON) usando partiQL.

  Cada nó contém todos os campos em nível de entidade`entityId`, como, `arn` e campos em nível de componente`components`, como`componentName`, `componentTypeId` e também campos em nível de propriedade, `properties` como e, tudo como um JSON `propertyName` aninhado`propertyValue`.
+ **Obtenha todos os relacionamentos com um filtro**:

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

  Essa consulta retorna todos os relacionamentos em um espaço de trabalho com o nome do relacionamento `isLocationOf`.

   A `MATCH` cláusula: especifica um padrão que corresponde a dois nós (indicados por`()`) conectados por uma borda direcionada (indicada por`-[]->`) e vinculados a uma variável chamada. `relationship`

  A `WHERE` cláusula: especifica um filtro no `relationshipName` campo da borda, onde está o valor. `isLocationOf`

  A `SELECT` cláusula: especifica a variável de relacionamento para que todo o nó de borda seja retornado.

  **Resposta**

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

  O tipo da coluna em `columnDescriptions` é um`EDGE`.

  Cada um `rowData` representa uma borda com campos como`relationshipName`. É o mesmo nome da propriedade do relacionamento definido na entidade. O`sourceEntityId`, `sourceComponentName` e `sourceComponentTypeId` fornece informações sobre em qual entidade e componente a propriedade do relacionamento foi definida. O `targetEntityId` especifica para qual entidade esse relacionamento está apontando.
+ **Obtenha todas as entidades com um relacionamento específico com uma entidade específica**

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

  Essa consulta retorna todos os nomes de entidades de todas as entidades que têm um `isLocationOf` relacionamento com a `room_0` entidade.

  A `MATCH` cláusula: especifica um padrão que corresponde a quaisquer dois nós (`e1`,`e2`) que tenham uma borda direcionada (`r`).

  A cláusula `WHERE`: especifica um filtro no nome do relacionamento e no nome da entidade de origem.

  A `SELECT` cláusula: retorna o `entityName` campo no `e2` nó.

  **Resposta**

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

  Em ColumnDescriptions, o tipo da coluna é `VALUE` porque `entityName` é uma string.

  Uma entidade,`floor_0`, é retornada.

**MATCH**  
Os seguintes padrões são suportados em uma `MATCH` cláusula:  
+ Combine o nó 'b' apontando para o nó 'a':

  ```
  FROM EntityGraph MATCH (a)-[rel]-(b)
  ```
+ Combine o nó 'a' apontando para o nó 'b':

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

  Não há nenhuma variável vinculada a um relacionamento, supondo que um filtro não precise ser especificado no relacionamento.
+ Combine o nó 'a' apontando para o nó 'b' e o nó 'b' apontando para o nó 'a':

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

  Isso retornará duas correspondências: uma de 'a' para 'b' e outra de 'b' para 'a', então a recomendação é usar bordas direcionadas sempre que possível.
+ O nome do relacionamento também é um rótulo do gráfico de propriedades`EntityGraph`, então você pode simplesmente especificar o nome do relacionamento após dois pontos (:) em vez de especificar um filtro `rel.relationshipName` na `WHERE` cláusula.

  ```
  FROM EntityGraph MATCH (a)-[:isLocationOf]-(b)
  ```
+ Encadeamento: os padrões podem ser encadeados para corresponder a vários relacionamentos.

  ```
  FROM EntityGraph MATCH (a)-[rel1]->(b)-[rel2]-(c)
  ```
+ Os padrões de salto variáveis também podem abranger vários nós e bordas:

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

  Essa consulta corresponde a qualquer padrão com bordas de saída do nó 'a' em 1 a 5 saltos. Os quantificadores permitidos são:

  `{m,n}`- entre m e n repetições

  `{m,}`- m ou mais repetições.

**FROM**:  
Um nó de entidade pode conter dados aninhados, como componentes que, por sua vez, contêm mais dados aninhados, como propriedades. Eles podem ser acessados desaninhando o resultado do padrão 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'
```
Acesse campos aninhados pontilhando `.` em uma variável. Uma vírgula (,) é usada para desaninhar (ou unir) entidades com os componentes internos e, em seguida, com as propriedades dentro desses componentes. `AS`é usado para vincular uma variável às variáveis não aninhadas para que elas possam ser usadas nas cláusulas or. `WHERE` `SELECT` Essa consulta retorna todas as entidades que contêm uma propriedade nomeada `roomFunction` com valor `meeting` em um componente com id do tipo de componente `com.example.query.construction.room`.   
Para acessar vários campos aninhados de um campo, como vários componentes em uma entidade, use a notação de vírgula para fazer uma junção.  

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

**SELECT**:  
+ Retorne um nó:

  ```
  SELECT e
  FROM EntityGraph MATCH (e)
  ```
+ Retorne uma borda:

  ```
  SELECT r
  FROM EntityGraph MATCH (e1)-[r]->(e2)
  ```
+ Retorne um 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
  ```

  Formate o nome do campo de saída atribuindo um alias a ele usando `AS`. Aqui, em vez de `propertyValue` como nome da coluna na resposta, `roomfunction` é retornado.
+ Retorne os aliases:

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

  É altamente recomendável usar aliases para ser explícito, aumentar a legibilidade e evitar ambigüidades em suas consultas.

**WHERE**:  
+ Os operadores lógicos suportados são `AND``NOT`, `OR` e.
+ Os operadores de comparação compatíveis são `<`, `<=`, `>`, `=>`, `=` e `!=`.
+ Use a `IN` palavra-chave se quiser especificar várias `OR` condições no mesmo campo.
+ Filtrar em um campo de entidade, componente ou propriedade:

  ```
  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'
  ```
+ Filtre na `configuration` propriedade. Aqui `unit` está a chave no mapa de configuração e `Celsius` é o valor.

  ```
  WHERE p.definition.configuration.unit = 'Celsius'
  ```
+ Verifique se uma propriedade do mapa contém uma determinada chave e valor:

  ```
  WHERE p.propertyValue.length = 20.0
  ```
+ Verifique se uma propriedade do mapa contém uma determinada chave:

  ```
  WHERE NOT p.propertyValue.length IS MISSING
  ```
+ Verifique se uma propriedade da lista contém um determinado valor:

  ```
  WHERE 10.0 IN p.propertyValue
  ```
+ Use a função `lower()` para comparações sem distinção entre maiúsculas e minúsculas. Por padrão, todas as comparações são sensíveis a maiúsculas e minúsculas.

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

**LIKE**:  
Útil se você não souber o valor exato de um campo e puder realizar uma pesquisa de texto completo no campo especificado. `%` representa zero ou mais.  

```
WHERE e.entityName LIKE '%room%'
```
+ Pesquisa de infixos: `%room%`
+ Pesquisa de prefixos: `room%`
+ Pesquisa de sufixo: `%room`
+ Se você tiver '%' em seus valores, coloque um caractere de escape no `LIKE` e especifique o caractere de escape com`ESCAPE`.

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

**DISTINCT**:  

```
SELECT DISTINCT c.componentTypeId
FROM EntityGraph MATCH (e), e.components AS c
```
+ A palavra-chave `DISTINCT` elimina duplicatas do resultado final.

  `DISTINCT` não é compatível com tipos de dados complexos.

**CONTAGEM**  

```
SELECT COUNT(e), COUNT(c.componentTypeId)
FROM EntityGraph MATCH (e), e.components AS c
```
+ A `COUNT` palavra-chave calcula o número de itens em um resultado de consulta.
+ `COUNT`não é compatível com campos complexos aninhados e campos de padrões gráficos.
+ `COUNT`a agregação não é compatível com consultas `DISTINCT` aninhadas.

  Por exemplo, não há suporte para `COUNT(DISTINCT e.entityId)`.

**CAMINHO**  
As seguintes projeções de padrões são suportadas na consulta usando a projeção de caminho:  
+ Consultas de salto variável

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

  *Essa consulta combina e projeta metadados de nós de qualquer padrão com bordas de saída do nó a em 1 a 3 saltos.*
+ Consultas de salto fixo

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

  *Essa consulta combina e projeta metadados de entidades e bordas de entrada para b.*
+ Consultas não direcionadas

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

  Essa consulta combina e projeta os metadados dos nós em padrões de 1 salto conectando *a* e *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"
                          }
                      ]
                  }
              ]
          }
      ]
  }
  ```

  *Essa resposta de `PATH` consulta é composta apenas por metadados que identificam todos os nós e bordas de cada *um path/pattern * entre a e *c* via b.*

**LIMITE** e **COMPENSAÇÃO**:  

```
SELECT e.entityName
FROM EntityGraph MATCH (e)
WHERE e.entityName LIKE 'room_%'
LIMIT 10
OFFSET 5
```
`LIMIT` especifica o número de resultados a serem retornados na consulta e `OFFSET` especifica o número de resultados a serem ignorados.

**LIMIT** e **maxResults**:  
O exemplo a seguir mostra uma consulta que retorna 500 resultados no total, mas exibe apenas 50 por vez por chamada de API. Esse padrão pode ser usado quando você precisa limitar a quantidade de resultados exibidos, por exemplo, se você só puder exibir 50 resultados em uma interface de usuário.  

```
aws iottwinmaker execute-query \
--workspace-id exampleWorkspace \
--query-statement "SELECT e FROM EntityGraph MATCH (e) LIMIT 500"\
--max-results 50
```
+ A `LIMIT` palavra-chave afeta a consulta e limita as linhas resultantes. Se você precisar controlar o número de resultados retornados por chamada de API sem limitar o número total de resultados retornados, use`LIMIT`.
+ `max-results`é um parâmetro opcional para a [ação ExecuteQuery da API](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html). `max-results`só se aplica à API e à forma como os resultados são lidos dentro dos limites da consulta acima.

  O uso `max-results` em uma consulta permite reduzir o número de resultados exibidos sem limitar o número real de resultados retornados.
A consulta abaixo percorre a próxima página de resultados. Essa consulta usa a chamada de `ExecuteQuery` API para retornar as linhas 51 a 100, onde a próxima página de resultados é especificada pelo `next-token` — nesse caso, o 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"
```
+ A `next-token` string especifica a próxima página de resultados. Para obter mais informações, consulte a ação [ ExecuteQuery](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ExecuteQuery.html#API_ExecuteQuery_RequestSyntax)da API.

AWS IoT TwinMaker a consulta do gráfico de conhecimento tem os seguintes limites: 


****  

| Nome do limite | Quota | Ajustável | 
| --- | --- | --- | 
| Tempo limite de execução da consulta | 10 segundos | Não | 
| Número máximo de saltos | 10 | Sim | 
| Número máximo de `JOIN` selos | 20 | Sim | 
| Número máximo de campos projetados | 20 | Sim | 
| Número máximo de expressões condicionais (`AND`,`OR`,`NOT`) | 10 | Sim | 
| Tamanho máximo de um padrão de `LIKE` expressão (incluindo curingas e escapes) | 20 | Sim | 
| Número máximo de itens que podem ser especificados em uma IN cláusula | 10 | Sim | 
| Valor máximo para OFFSET | 3000 | Sim | 
| Valor máximo para `LIMIT` | 3000 | Sim | 
| Valor máximo para travessias (\+) `OFFSET` `LIMIT` | 3000 | Sim |