Trabalhar com JSON no Azure Cosmos DB para NoSQL

  • Artigo

APLICA-SE A: NoSQL

No Azure Cosmos DB para NoSQL, os itens são armazenados como JSON. O sistema de tipos e as expressões são restringidos para processar apenas os tipos JSON. Para obter mais informações, consulte a especificação JSON.

Resumimos alguns aspetos importantes do trabalho com JSON:

  • Os objetos JSON sempre começam com uma { chave esquerda e terminam com uma } chave direita
  • Você pode ter propriedades JSON aninhadas umas nas outras
  • Os valores de propriedade JSON podem ser matrizes
  • Os nomes de propriedade JSON diferenciam maiúsculas de minúsculas
  • O nome da propriedade JSON pode ser qualquer valor de cadeia de caracteres (incluindo espaços ou caracteres que não são letras)

Propriedades aninhadas

Você pode acessar JSON aninhado usando um acessador de ponto (.). Você pode usar propriedades JSON aninhadas em suas consultas da mesma forma que pode usar quaisquer outras propriedades.

Aqui está um documento com JSON aninhado:

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

Nesse caso, as skupropriedades , colorse e sizes são todas aninhadas dentro da metadata propriedade. A name propriedade também está aninhada dentro da manufacturer propriedade.

Este primeiro exemplo projeta três propriedades aninhadas.

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

[
  {
    "name": "AdventureWorks",
    "sku": "72109",
    "size": 76
  }
]

Trabalhar com arrays

Além das propriedades aninhadas, o JSON também oferece suporte a matrizes. Ao trabalhar com matrizes, você pode acessar um elemento específico dentro da matriz fazendo referência à sua posição.

Este exemplo acessa um elemento de matriz em uma posição específica.

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

Na maioria dos casos, no entanto, você usa uma subconsulta ou associação automática ao trabalhar com matrizes.

Por exemplo, aqui está uma consulta que retorna várias permutações usando os valores de matriz potencial e uma associação cruzada,

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

Como outro exemplo, a consulta também pode ser usada EXISTS com uma subconsulta.

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"
]

Diferença entre nulo e indefinido

Se uma propriedade não estiver definida em um item, seu valor será undefined. Uma propriedade com o valor null deve ser explicitamente definida e atribuída a um null valor.

O Azure Cosmos DB para NoSQL dá suporte a duas funções e undefined propriedades úteis do sistema de verificação de null tipo:

  • IS_NULL - verifica se o valor de uma propriedade é null.
  • IS_DEFINED - verifica se um valor de propriedade está definido ou undefined.

Aqui está um exemplo de consulta que verifica dois campos em cada item no contêiner.

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
  }
]

Para obter mais informações sobre operadores comuns e seu comportamento para null e undefined valores, consulte Operadores de igualdade e comparação.

Palavras-chave reservadas e caracteres especiais em JSON

Você pode acessar propriedades usando o operador []de propriedade cotado. Por exemplo, SELECT c.grade e SELECT c["grade"] são equivalentes. Essa sintaxe é útil para escapar de uma propriedade que contém espaços, caracteres especiais ou tem o mesmo nome que uma palavra-chave SQL ou palavra reservada.

Por exemplo, aqui está uma consulta que faz referência a uma propriedade de algumas maneiras distintas.

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

Expressões JSON

A projeção de consulta suporta expressões JSON e sintaxe.

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

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

Neste exemplo, a SELECT cláusula cria um objeto JSON. Como o exemplo não fornece nenhuma chave, a cláusula usa o nome $<index-number>da variável de argumento implícito .

Este exemplo nomeia explicitamente o mesmo campo.

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

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

Como alternativa, a consulta pode nivelar o objeto para evitar nomear um campo redundante.

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

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

Valores de alias

Você pode explicitamente alias valores em consultas. Se uma consulta tiver duas propriedades com o mesmo nome, use o aliasing para renomear uma ou ambas as propriedades para que elas sejam desambiguadas no resultado projetado.

Exemplos

A AS palavra-chave usada para aliasing é opcional, como mostrado no exemplo a seguir.

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

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

Valores de alias com palavras-chave reservadas ou caracteres especiais

Não é possível usar aliasing para projetar um valor como um nome de propriedade com um espaço, caractere especial ou palavra reservada. Se você quisesse alterar a projeção de um valor para, por exemplo, ter um nome de propriedade com um espaço, poderia usar uma expressão JSON.

Eis um exemplo:

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

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

Conteúdos relacionados