Informations de référence sur le langage de requête Azure Digital Twins : clause SELECT

  • Article

Ce document contient des informations de référence sur la clause SELECT du langage de requête Azure Digital Twins.

La clause SELECT constitue la première partie d’une requête. Elle spécifie la liste des colonnes renvoyées par la requête.

Cette clause est requise pour toutes les requêtes.

SELECT *

Utilisez le caractère * dans une instruction SELECT pour projeter le document de jumeau numérique tel que, sans l’attribuer à une propriété dans le jeu de résultats.

Notes

SELECT * est une syntaxe valide uniquement lorsque la requête n’utilise pas de JOIN. Pour plus d’informations sur les requêtes utilisant JOIN, consultez Informations de référence sur le langage de requête Azure Digital Twins  : clause JOIN.

Syntaxe

SELECT *
--FROM ...

Retours

Jeu des propriétés qui sont retournées par la requête.

Exemple

La requête suivante renvoie tous les jumeaux numériques de l’instance.

SELECT *
FROM DIGITALTWINS

Colonnes SELECT avec projections

Vous pouvez utiliser des projections dans la clause SELECT pour choisir les colonnes renvoyées par une requête. Vous pouvez spécifier des collections nommées de jumeaux et de relations, ou des propriétés de jumeaux et de relations.

La projection est désormais prise en charge pour les propriétés primitives et complexes.

Syntaxe

Pour projeter une collection :

SELECT <twin-or-relationship-collection>

Pour projeter une propriété :

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

Retours

Collection de jumeaux, propriétés ou relations spécifiés dans la projection.

Si une propriété incluse dans la projection n’est pas présente pour une ligne de données spécifique, la propriété n’est pas présente dans le jeu de résultats. Pour obtenir un exemple de ce comportement, consultez Exemple de projection de propriété : propriété non présente pour une ligne de données.

Exemples

Exemple de scénario

Pour les exemples suivants, envisagez un graphique de jumeaux contenant les éléments de données suivants :

  • Un jumeau de fabrique appelé FactoryA
    • Contient une propriété appelée name avec la valeur FactoryA
  • Un jumeau de consommateur appelé Contoso
    • Contient une propriété appelée name avec la valeur Contoso
  • Une relation consumerRelationship de FactoryA à Contoso, appelée FactoryA-consumerRelationship-Contoso
    • Contient une propriété appelée managedBy avec la valeur Jeff

Le diagramme suivant illustre ce scénario :

Diagramme montrant l’exemple de graphique décrit ci-dessus.

Exemple de projection de collection

Vous trouverez ci-dessous un exemple de requête qui projette une collection à partir de ce graphique. La requête suivante renvoie tous les jumeaux numériques de l’instance, en nommant l’ensemble de la collection de jumeaux T et en projetant T en tant que collection à renvoyer.

SELECT T
FROM DIGITALTWINS T

Voici la charge utile JSON qui est retournée par cette requête :

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

Exemple de projection avec JOIN

La projection est couramment utilisée pour renvoyer une collection spécifiée dans un JOIN. La requête suivante utilise la projection pour retourner les données du consommateur, de la fabrique et de la relation. Pour plus d’informations sur la syntaxe JOIN utilisée dans l’exemple, consultez Informations de référence sur le langage de requête Azure Digital Twins : clause JOIN.

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

Voici la charge utile JSON qui est retournée par cette requête :

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

Exemple de projection de propriété

Voici un exemple projetant une propriété. La requête suivante utilise la projection pour renvoyer la propriété name du jumeau de consommateur et la propriété managedBy de la relation.

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

Voici la charge utile JSON qui est retournée par cette requête :

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

Exemple de projection de propriété : propriété non présente pour une ligne de données

Si une propriété incluse dans la projection n’est pas présente pour une ligne de données spécifique, la propriété n’est pas présente dans le jeu de résultats.

Prenez l’exemple d’un ensemble de jumeaux représentant des personnes. Des âges sont associés à certains jumeaux, mais pas à d’autres.

Voici une requête qui projette les propriétés name et age :

SELECT name, age 
FROM DIGITALTWINS

Le résultat peut ressembler à ceci, avec la propriété age absente de certains jumeaux dans le résultat où les jumeaux ne présentent pas cette propriété.

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

SELECT COUNT

Utilisez cette méthode pour compter le nombre d’éléments du jeu de résultats et renvoyer ce nombre.

Syntaxe

SELECT COUNT()

Arguments

Aucun.

Retours

Valeur int.

Exemple

La requête suivante renvoie le nombre de jumeaux numériques de l’instance.

SELECT COUNT()
FROM DIGITALTWINS

La requête suivante renvoie le nombre de relations de l’instance.

SELECT COUNT()
FROM RELATIONSHIPS

SELECT TOP

Utilisez cette méthode pour retourner uniquement les principaux éléments qui satisfont aux exigences de requête.

Syntaxe

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

Arguments

Valeur int spécifiant le nombre d’éléments principaux à sélectionner.

Retours

Collection de jumeaux.

Exemple

La requête suivante renvoie uniquement les cinq premiers jumeaux numériques de l’instance.

SELECT TOP(5)
FROM DIGITALTWINS