Utiliser JSON dans Azure Cosmos DB for NoSQL

  • Article

S’APPLIQUE À : NoSQL

Dans Azure Cosmos DB for NoSQL, les éléments sont stockés au format JSON. Le système de type et les expressions peuvent uniquement traiter des types JSON. Pour en savoir plus, consultez la spécification JSON.

Nous allons résumer certains aspects importants de l’utilisation de JSON :

  • Les objets JSON commencent toujours par une accolade ouvrante { et se terminent par une accolade fermante }.
  • Vous pouvez avoir des propriétés JSON imbriquées les unes dans les autres.
  • Les valeurs de propriétés JSON peuvent être des tableaux.
  • Les noms de propriétés JSON respectent la casse.
  • Le nom d’une propriété JSON peut être n’importe quelle valeur de chaîne (y compris des espaces ou des signes autres que des lettres).

Propriétés imbriquées

Vous pouvez accéder à un JSON imbriqué à l’aide d’un accesseur de point (.). Vous pouvez utiliser des propriétés JSON imbriquées dans vos requêtes de la même façon que vous pouvez en utiliser d’autres.

Voici un document contenant du code JSON imbriqué :

{
  "name": "Teapo rainbow surfboard",
  "manufacturer": {
    "name": "AdventureWorks"
  },
  "releaseDate": null,
  "metadata": {
    "sku": "72109",
    "colors": [
      "cruise",
      "picton-blue"
    ],
    "sizes": {
      "small": {
        "inches": 76,
        "feet": 6.33333
      },
      "large": {
        "inches": 92,
        "feet": 7.66667
      }
    }
  }
}

Dans ce cas, les propriétés sku, colors et sizes sont toutes imbriquées dans la propriété metadata. La name propriété est également imbriquée dans la manufacturer propriété.

Ce premier exemple projette deux propriétés imbriquées.

SELECT
    p.name,
    p.metadata.sku,
    p.sizes.small.inches AS size
FROM
    products p

[
  {
    "name": "Teapo rainbow surfboard",
    "sku": "72109"
  }
]

Utiliser des tableaux

Outre les propriétés imbriquées, JSON prend en charge les tableaux. Lorsque vous utilisez des tableaux, vous pouvez accéder à un élément spécifique dans un tableau en référençant sa position.

Cet exemple montre comment accéder à un élément de tableau à une position spécifique.

SELECT
    p.name,
    p.metadata.colors
FROM
    products p
WHERE
    p.metadata.colors[0] NOT LIKE "%orange%"

[
  {
    "name": "Teapo rainbow surfboard",
    "colors": [
      "cruise",
      "picton-blue"
    ]
  }
]

Toutefois, le plus souvent, vous utilisez une sous-requête ou une jointure réflexive.

Par exemple, voici une requête qui retourne plusieurs permutations à l’aide des valeurs de tableau potentielles et d’une jointure croisée,

SELECT
    p.name,
    c AS color
FROM
    products p
JOIN
    c IN p.metadata.colors

[
  {
    "name": "Teapo rainbow surfboard",
    "color": "cruise"
  },
  {
    "name": "Teapo rainbow surfboard",
    "color": "picton-blue"
  }
]

Autre exemple, la requête peut également utiliser EXISTS avec une sous-requête.

SELECT VALUE
    p.name
FROM
    products p
WHERE
    EXISTS (SELECT VALUE 
        c
    FROM
        c IN p.metadata.colors
    WHERE
        c LIKE "%picton%")

[
  "Teapo rainbow surfboard"
]

Différence entre une valeur Null et non définie

Si une propriété n’est pas définie dans un élément, sa valeur est undefined. Une propriété dont la valeur est null doit être définie explicitement et se voir attribuer une valeur null.

Azure Cosmos DB for NoSQL prend en charge deux fonctions système de contrôle de type utiles pour les propriétés null et undefined :

  • IS_NULL : vérifie si une valeur de propriété est null.
  • IS_DEFINED : vérifie si une valeur de propriété est définie ou undefined.

Voici un exemple de requête qui recherche deux champs sur chaque élément du conteneur.

SELECT
    IS_NULL(p.releaseDate) AS isReleaseDateNull,
    IS_DEFINED(p.releaseDate) AS isReleaseDateDefined,
    IS_NULL(p.retirementDate) AS isRetirementDateNull,
    IS_DEFINED(p.retirementDate) AS isRetirementDateDefined
FROM
    products p

[
  {
    "isReleaseDateNull": true,
    "isReleaseDateDefined": true,
    "isRetirementDateNull": false,
    "isRetirementDateDefined": false
  }
]

Pour plus d’informations sur les opérateurs courants et leur comportement pour les valeurs null et undefined, consultez Opérateurs d’égalité et de comparaison.

Mots clés réservés et caractères spéciaux dans JSON

Vous pouvez accéder à des propriétés en utilisant l’opérateur de propriété entre guillemets []. Par exemple, SELECT c.grade and SELECT c["grade"] sont équivalentes. Cette syntaxe est utile pour placer dans une séquence d’échappement une propriété qui contient des espaces, des caractères spéciaux, ou qui a le même nom qu’un mot clé SQL ou un mot réservé.

Par exemple, voici une requête qui fait référence à une propriété de plusieurs façons distinctes.

SELECT
    p.manufacturer.name AS dotNotationReference,
    p["manufacturer"]["name"] AS bracketReference,
    p.manufacturer["name"] AS mixedReference
FROM
    products p

[
  {
    "dotNotationReference": "AdventureWorks",
    "bracketReference": "AdventureWorks",
    "mixedReference": "AdventureWorks"
  }
]

Expressions JSON

La projection de requête prend en charge la syntaxe et les expressions JSON.

SELECT {
    "productName": p.name,
    "largeSizeInFeet": p.metadata.sizes.large.feet
}
FROM
    products p

[
  {
    "$1": {
      "productName": "Teapo rainbow surfboard",
      "largeSizeInFeet": 7.66667
    }
  }
]

Dans cet exemple, la clause SELECT crée un objet JSON. Puisque l’exemple ne fournit aucune clé, la clause utilise le nom de variable d’argument implicite $<index-number>.

Cet exemple nomme explicitement le même champ.

SELECT {
    "productName": p.name,
    "largeSizeInFeet": p.metadata.sizes.large.feet
} AS product
FROM
    products p

[
  {
    "product": {
      "productName": "Teapo rainbow surfboard",
      "largeSizeInFeet": 7.66667
    }
  }
]

La requête peut également aplatir l’objet pour éviter de nommer un champ redondant.

SELECT VALUE {
    "productName": p.name,
    "largeSizeInFeet": p.metadata.sizes.large.feet
}
FROM
    products p

[
  {
    "productName": "Teapo rainbow surfboard",
    "largeSizeInFeet": 7.66667
  }
]

Valeurs d’alias

Vous pouvez explicitement attribuer des alias à des valeurs dans les requêtes. Si une requête a deux propriétés portant le même nom, utilisez l’attribution d’alias pour renommer l’une ou l’autre des propriétés, afin d’éviter toute ambiguïté dans le résultat projeté.

Exemples

Le mot clé AS utilisé pour l’attribution d’alias est facultatif, comme le montre l’exemple suivant.

SELECT
    p.name,
    p.metadata.sku AS modelNumber
FROM
    products p

[
  {
    "name": "Teapo rainbow surfboard",
    "modelNumber": "72109"
  }
]

Attribution d’alias avec des mots clés réservés ou des caractères spéciaux

Vous ne pouvez pas utiliser d’alias pour projeter une valeur en tant que nom de propriété avec une espace, un caractère spécial ou un mot réservé. Si vous souhaitez modifier la projection d’une valeur en, par exemple, avoir un nom de propriété avec une espace, vous pouvez utiliser une expression JSON.

Voici un exemple :

SELECT VALUE {
    "Product's name | ": p.name,
    "Model number => ": p.metadata.sku
}
FROM
    products p

[
  {
    "Product's name | ": "Teapo rainbow surfboard",
    "Model number => ": "72109"
  }
]

Contenu connexe