Trabalhar com JSON no Azure Cosmos DB para NoSQL

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, veja a especificação JSON.

Resumimos alguns aspetos importantes de trabalhar com JSON:

• Os objetos JSON começam sempre com uma { chaveta esquerda e terminam com uma } chaveta direita
• Pode ter propriedades JSON aninhadas umas nas outras
• Os valores das propriedades JSON podem ser matrizes
• Os nomes das propriedades JSON são sensíveis às maiúsculas e minúsculas
• O nome da propriedade JSON pode ser qualquer valor de cadeia (incluindo espaços ou carateres que não sejam letras)

Propriedades aninhadas

Pode aceder ao JSON aninhado com um acessório de ponto (.). Pode utilizar propriedades JSON aninhadas nas suas consultas da mesma forma que pode utilizar outras propriedades.

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

Neste caso, as skupropriedades , colorse sizes estão todas aninhadas na metadata propriedade . A name propriedade também está aninhada na manufacturer propriedade .

Este primeiro exemplo projeta duas propriedades aninhadas.

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

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

Trabalhar com matrizes

Além das propriedades aninhadas, o JSON também suporta matrizes. Ao trabalhar com matrizes, pode aceder a um elemento específico dentro da matriz ao referenciar a sua posição.

Este exemplo acede a um elemento de matriz numa 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"
    ]
  }
]

No entanto, na maioria dos casos, utiliza uma subconsulta ou associação automática ao trabalhar com matrizes.

Por exemplo, eis uma consulta que devolve múltiplas permutações com os potenciais valores de matriz 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 utilizada 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 num item, o respetivo valor é undefined. Uma propriedade com o valor null tem de ser explicitamente definida e atribuída um null valor.

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

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

Eis um exemplo de consulta que verifica a existência de dois campos em cada item no contentor.

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 o respetivo comportamento null e undefined valores, veja Operadores de igualdade e comparação.

Palavras-chave reservadas e carateres especiais em JSON

Pode aceder às propriedades com o operador []de propriedade quoted . Por exemplo, SELECT c.grade e SELECT c["grade"] são equivalentes. Esta sintaxe é útil para escapar a uma propriedade que contém espaços, carateres especiais ou tem o mesmo nome que uma palavra-chave SQL ou palavra reservada.

Por exemplo, eis uma consulta que referencia uma propriedade de algumas formas 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. Uma vez que o exemplo não fornece nenhuma chave, a cláusula utiliza o nome $<index-number>da variável de argumento implícito .

Este exemplo dá um nome explícito ao 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
    }
  }
]

Em alternativa, a consulta pode aplanar o objeto para evitar atribuir um nome a 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

Pode explicitamente alias valores em consultas. Se uma consulta tiver duas propriedades com o mesmo nome, utilize o aliasing para mudar o nome de uma ou ambas as propriedades para que sejam desambiguadas no resultado projetado.

Exemplos

A AS palavra-chave utilizada para aliasing é opcional, conforme mostrado no exemplo seguinte.

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 carateres especiais

Não pode utilizar o aliasing para projetar um valor como um nome de propriedade com um espaço, caráter especial ou palavra reservada. Se quisesse alterar a projeção de um valor para, por exemplo, ter um nome de propriedade com um espaço, poderia utilizar 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údo relacionado

• SELECT cláusula
• WHERE cláusula