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 Recursos adicionais do gráfico de conhecimento 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 (\$1) `OFFSET` `LIMIT` | 3000 | Sim |