Trabalhe com JSON no Azure Cosmos DB for NoSQL

APLICA-SE A: NoSQL

No Azure Cosmos DB for NoSQL, os itens são armazenados como JSON. As expressões e sistema de tipos são restritos para lidar somente com tipos JSON. Para obter mais informações, consulte as especificações do JSON.

Resumimos alguns aspectos 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 entre si
• Os valores de propriedade JSON podem ser matrizes
• Os nomes de propriedade JSON diferenciam maiúsculas de minúsculas
• O nome de propriedade JSON pode ser qualquer valor de cadeia de caracteres (incluindo espaços ou caracteres que não sejam letras)

Propriedades aninhadas

Você pode acessar o JSON aninhado usando um acessador de ponto (.). Você pode usar Propriedades JSON aninhadas em suas consultas da mesma maneira que pode usar qualquer outra propriedade.

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 propriedades sku, colorse sizes estão todas aninhadas dentro da propriedade metadata. A propriedade name também está aninhada na propriedade manufacturer.

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 matrizes

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 referenciando sua posição.

Esse 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, entretanto, você usa uma subconsulta ou uma autojunção ao trabalhar com matrizes.

Por exemplo, aqui está uma consulta que retorna várias permutações usando os valores potenciais da matriz e uma junçã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 poderia usar 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 receber um valor null.

O Azure Cosmos DB for NoSQL suporta duas funções úteis do sistema de verificação de tipos para propriedades as null e undefined:

• 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 se há dois campos em cada item do 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 os valores null e undefined, consulte operadores de igualdade e comparação.

Palavras-chave reservadas e caracteres especiais em JSON

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

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

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 e sintaxe JSON.

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

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

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

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 achatar 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 do alias

Você pode usar explicitamente alias de valores em consultas. Caso uma consulta tenha duas propriedades com o mesmo nome, use a atribuição para renomear uma ou as duas propriedades para que elas não sejam ambíguas no resultado projetado.

Exemplos

A palavra-chave AS usada para atribuição de alias é opcional, conforme 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

Você não pode usar a atribuição de alias para projetar um valor como um nome de propriedade com um espaço, um caractere especial ou uma 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.

Veja 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údo relacionado

• SELECTcláusula
• WHEREcláusula