Referência de linguagem de consulta do Azure Digital Twins: cláusulas SELECT

Este documento contém informações de referência sobre a cláusula SELECT para a linguagem de consulta de Gêmeos Digitais do Azure.

A cláusula SELECT é a primeira parte de uma consulta. Especifica a lista de colunas que a consulta retornará.

Esta cláusula é necessária para todas as consultas.

SELECIONAR *

Use o caractere em uma instrução select para projetar o documento do gêmeo digital como está, sem atribuí-lo a uma * propriedade no conjunto de resultados.

Sintaxe

SELECT *
--FROM ...

Retornos

O conjunto de propriedades retornadas da consulta.

Exemplo

A consulta a seguir retorna todos os gêmeos digitais na instância.

SELECT *
FROM DIGITALTWINS

Colunas SELECT com projeções

Você pode usar projeções na cláusula SELECT para escolher quais colunas uma consulta retornará. Você pode especificar coleções nomeadas de gêmeos e relações ou propriedades de gêmeos e relações.

Agora há suporte para projeção para propriedades primitivas e propriedades complexas.

Sintaxe

Para projetar uma coleção:

SELECT <twin-or-relationship-collection>

Para projetar uma propriedade:

SELECT <twin-or-relationship-collection>.<property-name>

Retornos

Uma coleção de gêmeos, propriedades ou relações especificadas na projeção.

Se uma propriedade incluída na projeção não estiver presente para uma linha de dados específica, a propriedade não estará presente no conjunto de resultados. Para ver um exemplo desse comportamento, consulte Exemplo de propriedade do projeto: propriedade não presente para uma linha de dados.

Exemplos

Cenário de exemplo

Para os exemplos a seguir, considere um grafo gêmeo que contém os seguintes elementos de dados:

• Um gêmeo alocador chamado FactoryA
  • Contém uma propriedade chamada name com um valor de FactoryA
• Um consumidor gêmeo chamado Contoso
  • Contém uma propriedade chamada name com um valor de Contoso
• Uma relação consumerRelationship de FactoryA para Contoso, chamada FactoryA-consumerRelationship-Contoso
  • Contém uma propriedade chamada managedBy com um valor de Jeff

Aqui está um diagrama que ilustra este cenário:

Exemplo de coleção de projetos

Veja abaixo uma consulta de exemplo que projeta uma coleção deste grafo. A consulta a seguir retorna todos os gêmeos digitais na instância, nomeando toda a coleção T e projeção de conjunto de itens T como a coleção a ser retornada.

SELECT T
FROM DIGITALTWINS T

Esta é a carga JSON retornada pela consulta:

{
  "value": [
    {
      "result": [
        {
          "T": {
            "$dtId": "FactoryA",
            "$etag": "W/\"d22267a0-fd4f-4f6b-916d-4946a30453c9\"",
            "$metadata": {
              "$model": "dtmi:contosocom:DigitalTwins:Factory;1",
              "name": {
                "lastUpdateTime": "2021-04-19T17:15:54.4977151Z"
              }
            },
            "name": "FactoryA"
          }
        },
        {
          "T": {
            "$dtId": "Contoso",
            "$etag": "W/\"a96dc85e-56ae-4061-866b-058a149e03d8\"",
            "$metadata": {
              "$model": "dtmi:com:contoso:Consumer;1",
              "name": {
                "lastUpdateTime": "2021-04-19T17:16:30.2154166Z"
              }
            },
            "name": "Contoso"
          }
        }
      ]
    }
  ],
  "continuationToken": "null"
}

Projeto com exemplo de junção

A projeção normalmente é usada para retornar uma coleção especificada em um JOIN. A consulta a seguir usa a projeção para retornar os dados do Consumidor, da Fábrica e da Relação. Para obter mais informações sobre a JOIN sintaxe usada no exemplo, consulte referência de linguagem de consulta do Azure digital gêmeos: cláusula JOIN.

SELECT Consumer, Factory, Relationship
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.consumerRelationship Relationship
WHERE Factory.$dtId = 'FactoryA'

Esta é a carga JSON retornada pela consulta:

{
  "value": [
    {
      "result": [
        {
          "Consumer": {
            "$dtId": "Contoso",
            "$etag": "W/\"a96dc85e-56ae-4061-866b-058a149e03d8\"",
            "$metadata": {
              "$model": "dtmi:com:contoso:Consumer;1",
              "name": {
                "lastUpdateTime": "2021-04-19T17:16:30.2154166Z"
              }
            },
            "name": "Contoso"
          },
          "Factory": {
            "$dtId": "FactoryA",
            "$etag": "W/\"d22267a0-fd4f-4f6b-916d-4946a30453c9\"",
            "$metadata": {
              "$model": "dtmi:contosocom:DigitalTwins:Factory;1",
              "name": {
                "lastUpdateTime": "2021-04-19T17:15:54.4977151Z"
              }
            },
            "name": "FactoryA"
          },
          "Relationship": {
            "$etag": "W/\"f01e07c1-19e4-4bbe-a12d-f5761e86d3e8\"",
            "$relationshipId": "FactoryA-consumerRelationship-Contoso",
            "$relationshipName": "consumerRelationship",
            "$sourceId": "FactoryA",
            "$targetId": "Contoso",
            "managedBy": "Jeff"
          }
        }
      ]
    }
  ],
  "continuationToken": "null"
}

Exemplo da Propriedade Project

Aqui está um exemplo que projeta uma propriedade. A consulta a seguir usa projeção para retornar a name Propriedade do consumidor e a managedBy propriedade da relação.

SELECT Consumer.name, Relationship.managedBy
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.consumerRelationship Relationship
WHERE Factory.$dtId = 'FactoryA'

Esta é a carga JSON retornada pela consulta:

{
  "value": [
    {
      "result": [
        {
          "managedBy": "Jeff",
          "name": "Contoso"
        }
      ]
    }
  ],
  "continuationToken": "null"
}

Exemplo de propriedade do projeto: propriedade não presente para uma linha de dados

Se uma propriedade incluída na projeção não estiver presente para uma linha de dados específica, a propriedade não estará presente no conjunto de resultados.

Considere para este exemplo um conjunto de gêmeos que representam as pessoas. Alguns dos gêmeos têm idades associadas a eles, mas outros não.

Aqui está uma consulta que projeta as propriedades name e age:

SELECT name, age 
FROM DIGITALTWINS

O resultado pode ser algo parecido com isso, com a propriedade age ausente de alguns gêmeos no resultado em que os gêmeos não têm essa propriedade.

{
  "value": [
    {
      "result": [
        {
          "name": "John",
          "age": 27
        },
        {
          "name": "Keanu"
        }
      ]
    }
  ],
  "continuationToken": "null"
}

SELECT COUNT

Use esse método para contar o número de itens no conjunto de resultados e retornar esse número.

Sintaxe

SELECT COUNT()

Argumentos

Nenhum.

Retornos

Um valor int.

Exemplo

A consulta a seguir retorna a contagem de todos os gêmeos digitais na instância.

SELECT COUNT()
FROM DIGITALTWINS

A consulta a seguir retorna a contagem de todos os relacionamentos na instância.

SELECT COUNT()
FROM RELATIONSHIPS

SELECT TOP

Use esse método para retornar apenas alguns dos itens principais que atendem aos requisitos da consulta.

Sintaxe

SELECT TOP(<number-of-return-items>)

Argumentos

Um int valor que especifica o número de itens principais a selecionar.

Retornos

Uma coleção de gêmeos.

Exemplo

A consulta a seguir retorna apenas os cinco primeiros gêmeos digitais na instância.

SELECT TOP(5)
FROM DIGITALTWINS