Delen via

Aan de slag met JSON - Querytaal in Cosmos DB (in Azure en Fabric)

  • Van toepassing op: ✅ Azure Cosmos DB for NoSQL, ✅ Cosmos DB in Microsoft Fabric

Werken met JavaScript Object Notation (JSON) vormt het hart van de querytaal. Items worden opgeslagen als JSON en alle query's, expressies en typen zijn ontworpen om te werken met JSON-gegevens. Zie de formele JSON-specificatie voor meer informatie over JSON zelf.

Hier volgen enkele belangrijke dingen die u moet weten over JSON in deze context:

  • JSON-objecten beginnen altijd met { en eindigen met }.
  • Eigenschappen kunnen tussen elkaar worden genest .
  • Eigenschapswaarden kunnen matrices zijn.
  • Eigenschapsnamen zijn hoofdlettergevoelig.
  • Eigenschapsnamen kunnen elke tekenreeks zijn, zelfs met spaties of speciale tekens.

Geneste eigenschappen

U hebt toegang tot geneste JSON-eigenschappen met behulp van punt notatie. Dit werkt net als het openen van eigenschappen in de meeste programmeertalen.

Hier volgt een voorbeelddocument met geneste JSON:

[
  {
    "name": "Heatker Women's Jacket",
    "category": "apparel",
    "slug": "heatker-women-s-jacket",
    "sizes": [
      {
        "key": "s",
        "description": "Small"
      }
    ],
    "metadata": {
      "link": "https://www.adventure-works.com/heatker-women-s-jacket/68719520138.p"
    }
  }
]

Vervolgens kunt u dezelfde geneste eigenschappen in uw query's projecteren:

SELECT
  p.name,
  p.category,
  p.metadata.link
FROM
  products p
WHERE
  p.name = "Heatker Women's Jacket"

En u krijgt deze verwachte uitvoer:

[
  {
    "name": "Heatker Women's Jacket",
    "category": "apparel",
    "link": "https://www.adventure-works.com/heatker-women-s-jacket/68719520138.p"
  }
]

Matrices en sets

JSON ondersteunt matrices en u kunt ermee werken in uw query's. Als u toegang wilt krijgen tot een specifiek element, gebruikt u de positie ervan in de matrix.

Met hetzelfde voorbeeld uit de vorige sectie hebben we toegang tot een item in de matrix met behulp van de index. Als we bijvoorbeeld toegang willen krijgen tot het eerste item in de matrix, gebruiken we een index van 0 omdat het een op nul gebaseerd indexsysteem is voor matrices in de querytaal:

SELECT
  p.name,
  p.sizes[0].description AS defaultSize
FROM
  products p
WHERE
  p.name = "Heatker Women's Jacket"

Deze query resulteert in het volgende JSON-object:

[
  {
    "name": "Heatker Women's Jacket",
    "defaultSize": "Small"
  }
]

Laten we nu eens kijken naar een voorbeeld met een grotere matrix:

[
  {
    "name": "Vencon Kid's Coat",
    "category": "apparel",
    "slug": "vencon-kid-s-coat",
    "colors": [
      "cardinal",
      "disco"
    ],
    "sizes": [
      {
        "key": "m",
        "description": "Medium"
      },
      {
        "key": "l",
        "description": "Large"
      },
      {
        "key": "xl",
        "description": "Extra Large"
      }
    ]
  }
]

Vaak wilt u een subquery of een self-join gebruiken om te werken met alle elementen in een matrix. Als u bijvoorbeeld elke kleur als een afzonderlijke rij wilt ophalen:

SELECT
  p.name,
  c AS color
FROM
  products p
JOIN
  c IN p.colors
WHERE
  p.name = "Vencon Kid's Coat"

Dit zou resulteren in een JSON-matrix als volgt:

[
  {
    "name": "Vencon Kid's Coat",
    "color": "cardinal"
  },
  {
    "name": "Vencon Kid's Coat",
    "color": "disco"
  }
]

Als u wilt controleren of een bepaalde waarde in een matrix bestaat, kunt u de matrix in het filter gebruiken na het WHERE trefwoord. In dit voorbeeld wordt een subquery gebruikt om de items van de matrix te filteren:

SELECT VALUE
  p.name
FROM
  products p
WHERE
  EXISTS(SELECT VALUE
    c
  FROM
    c IN p.sizes
  WHERE
    c.description LIKE "%Large")

Deze query resulteert in een platte JSON-matrix met tekenreeksen, waaronder het item in het voorbeeld:

[
  ...,
  "Vencon Kid's Coat"
  ...
]

Ten slotte kunt u matrices maken door meerdere eigenschappen te combineren. In dit voorbeeld worden meerdere eigenschappen gecombineerd om een metadata matrix te vormen:

SELECT
  p.name,
  [
    p.category,
    p.slug,
    p.metadata.link
  ] AS metadata
FROM
  products p
WHERE
  p.name = "Heatker Women's Jacket"

[
  {
    "name": "Heatker Women's Jacket",
    "metadata": [
      "apparel",
      "heatker-women-s-jacket",
      "https://www.adventure-works.com/heatker-women-s-jacket/68719520138.p"
    ]
  }
]

Iteration

De querytaal ondersteunt iteratie via JSON-matrices met behulp van het IN trefwoord in de FROM bron.

Bekijk deze voorbeeldgegevensset:

[
  {
    "name": "Pila Swimsuit",
    "colors": [
      "regal-blue",
      "rose-bud-cherry"
    ],
    "sizes": [
      {
        "key": "m",
        "description": "Medium"
      },
      {
        "key": "l",
        "description": "Large"
      },
      {
        "key": "xl",
        "description": "Extra Large"
      }
    ]
  },
  {
    "name": "Makay Bikini",
    "colors": [
      "starship"
    ],
    "sizes": [
      {
        "key": "s",
        "description": "Small"
      },
      {
        "key": "m",
        "description": "Medium"
      },
      {
        "key": "l",
        "description": "Large"
      }
    ]
  }
]

In dit eerste voorbeeld wordt het IN trefwoord gebruikt om iteratie uit te voeren via de colors eigenschap voor elk product:

SELECT
  *
FROM
  p IN p.colors

[
  "regal-blue",
  "rose-bud-cherry",
  "starship"
]

U kunt ook afzonderlijke vermeldingen in de matrix filteren met behulp van de WHERE component. In dit voorbeeld wordt de sizes eigenschap gefilterd:

SELECT
  p.key
FROM
  p IN p.sizes
WHERE
  p.description LIKE "%Large"

[
  {
    "key": "l"
  },
  {
    "key": "xl"
  },
  {
    "key": "l"
  }
]

Met hetzelfde IN trefwoord kunt u het resultaat van een matrix-iteratie aggregeren. In dit voorbeeld retourneert de query het aantal tags dat is opgeteld voor alle items in de container:

SELECT VALUE
  COUNT(1)
FROM
  p IN p.sizes

Opmerking

Wanneer u het IN trefwoord voor iteratie gebruikt, kunt u geen eigenschappen buiten de matrix filteren of projecteren. In plaats daarvan gebruikt u self-joins.

Null- en niet-gedefinieerde waarden

Als een eigenschap niet aanwezig is in een document, is de waarde .undefined Als een eigenschap aanwezig is maar is ingesteld op null, is dat een expliciete waarde. Het onderscheid tussen null en undefined is een belangrijk onderscheid dat verwarring kan veroorzaken in query's.

Dit JSON-object heeft bijvoorbeeld een waarde voor undefined de sku eigenschap omdat de eigenschap nooit is gedefinieerd:

[
  {
    "name": "Witalica helmet",
    "category": "gear",
  }
]

Dit JSON-object heeft een waarde voor null dezelfde eigenschap omdat de eigenschap nog niet is gedefinieerd met een waarde:

[
  {
    "name": "Witalica helmet",
    "category": "gear",
    "sku": null
  }
]

Er zijn ingebouwde functies om te controleren op deze gevallen:

  • IS_NULL controleert of een eigenschap is null.
  • IS_DEFINED controleert of er een eigenschap bestaat (niet undefined).

U kunt als volgt controleren op beide:

SELECT
  IS_DEFINED(p.sku) AS isSkuDefined,
  IS_NULL(p.sku) AS isSkuDefinedButNull
FROM
  products p

Vierkante haak notatie

Hoewel in de meeste voorbeelden punt notatie wordt gebruikt om eigenschappen op te geven, kunt u altijd dezelfde eigenschappen opgeven met behulp van een haakje-notatie .

Laten we beginnen met een eenvoudig object met een genest object als de waarde van de metadata eigenschap:

[
  {
    "name": "Hikomo Sandals",
    "metadata": {
      "link": "https://www.adventure-works.com/hikomo-sandals/68719519305.p"
    }
  }
]

Voor dat object kunnen we op drie verschillende manieren verwijzen naar de metadata.link eigenschap met behulp van combinaties van punt - en haak notatie:

SELECT
  p.metadata.link AS metadataLinkDotNotation,
  p["metadata"]["link"] AS metadataLinkBracketNotation,
  p.metadata["link"] AS metadataLinkMixedNotation
FROM
  products p
WHERE
  p.name = "Hikomo Sandals"

[
  {
    "metadataLinkDotNotation": "https://www.adventure-works.com/hikomo-sandals/68719519305.p",
    "metadataLinkBracketNotation": "https://www.adventure-works.com/hikomo-sandals/68719519305.p",
    "metadataLinkMixedNotation": "https://www.adventure-works.com/hikomo-sandals/68719519305.p"
  }
]

Aanbeveling

Als een eigenschapsnaam spaties, speciale tekens of overeenkomsten heeft met een gereserveerd woord, moet u de notatie haak gebruiken om de eigenschap op te geven.

JSON-expressies

U kunt JSON-objecten rechtstreeks in de queryresultaten maken. Laten we beginnen met deze JSON-matrix als voorbeeld:

[
  {
    "name": "Diannis Watch",
    "category": "apparel",
    "detailCategory": "apparel-accessories-watches",
    "slug": "diannis-watch",
    "sku": "64801",
    "price": 98,
    "quantity": 159
  },
  {
    "name": "Confira Watch",
    "category": "apparel",
    "detailCategory": "apparel-accessories-watches",
    "slug": "confira-watch",
    "sku": "64800",
    "price": 105,
    "quantity": 193
  }
]

Met behulp van de eenvoudigste syntaxis kunt u de eigenschapsnamen van een relatief plat JSON-object beïnvloeden met behulp van punthaken ({/}) en de ingesloten JSON-syntaxis in een NoSQL-query:

SELECT {
  "brandName": p.name,
  "department": p.category
}
FROM
  products p
WHERE
  p.detailCategory = "apparel-accessories-watches"

[
  {
    "$1": {
      "brandName": "Diannis Watch",
      "department": "apparel"
    }
  },
  {
    "$1": {
      "brandName": "Confira Watch",
      "department": "apparel"
    }
  }
]

In het vorige voorbeeld had het resultaat een afgeleid naam $1 omdat er geen expliciete naam is gedefinieerd. In dit volgende voorbeeld heeft het resultaat een expliciete naam die is gedefinieerd met behulp van product een alias:

SELECT {
  "brandName": p.name,
  "department": p.category
} AS product
FROM
  products p
WHERE
  p.detailCategory = "apparel-accessories-watches"

[
  {
    "product": {
      "brandName": "Diannis Watch",
      "department": "apparel"
    }
  },
  {
    "product": {
      "brandName": "Confira Watch",
      "department": "apparel"
    }
  }
]

U kunt het resultaat ook plat maken met behulp van het VALUE trefwoord in een SELECT VALUE instructie:

SELECT VALUE {
  "brandName": p.name,
  "department": p.category
}
FROM
  products p
WHERE
  p.detailCategory = "apparel-accessories-watches"

[
  {
    "brandName": "Diannis Watch",
    "department": "apparel"
  },
  {
    "brandName": "Confira Watch",
    "department": "apparel"
  }
]

Verderop kunt u de JSON-syntaxis gebruiken om het resultaat-JSON-object 'opnieuw vorm te geven' om matrices, subobjecten en andere JSON-constructies op te nemen die mogelijk niet expliciet in het oorspronkelijke item zijn gedefinieerd. Deze techniek is handig als de clienttoepassing gegevens verwacht in een specifiek schema dat niet overeenkomt met onderliggende gegevens.

Bekijk dit JSON-schema, bijvoorbeeld:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "required": [
    "id",
    "category",
    "financial"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "category": {
      "type": "object",
      "properties": {
        "department": {
          "type": "string"
        },
        "section": {
          "type": "string"
        }
      },
      "required": [
        "department"
      ]
    },
    "inventory": {
      "type": "object",
      "properties": {
        "stock": {
          "type": "number"
        }
      }
    },
    "financial": {
      "type": "object",
      "properties": {
        "listPrice": {
          "type": "number"
        }
      },
      "required": [
        "listPrice"
      ]
    }
  }
}

Met dit schema kan een JSON-object in deze indeling worden gestructureerd:

[
  {
    "id": "[string]",
    "name": "[string]",
    "category": {
      "department": "[string]",
      "section": "[string]"
    },
    "inventory": {
      "stock": [number]
    },
    "financial": {
      "listPrice": [number]
    }
  }
]

Met deze NoSQL-query wordt de oorspronkelijke object[s] opnieuw toewijzen om te voldoen aan dit nieuwe schema:

SELECT VALUE {
  "id": p.sku,
  "name": p.name,
  "category": {
    "department": p.category,
    "section": p.detailCategory
  },
  "inventory": {
    "stock": p.quantity
  },
  "financial": {
    "listPrice": p.price
  }
}
FROM
  products p
WHERE
  p.detailCategory = "apparel-accessories-watches"

[
  {
    "id": "64801",
    "name": "Diannis Watch",
    "category": {
      "department": "apparel",
      "section": "apparel-accessories-watches"
    },
    "inventory": {
      "stock": 159
    },
    "financial": {
      "listPrice": 98
    }
  },
  {
    "id": "64800",
    "name": "Confira Watch",
    "category": {
      "department": "apparel",
      "section": "apparel-accessories-watches"
    },
    "inventory": {
      "stock": 193
    },
    "financial": {
      "listPrice": 105
    }
  }
]

Containeraliassen

Standaard verwijst de term die na het FROM trefwoord wordt gebruikt naar de container die het doel van de query is. De term zelf is NIET vereist om de naam van de container te vinden.

Als de container bijvoorbeeld een naam productsheeft, werken deze query's prima en verwijzen ze allemaal naar de products container zolang die container het doel van de query is:

SELECT
  products.id
FROM
  products

SELECT
  p.id
FROM
  p

SELECT
  items.id
FROM
  items

SELECT
  targetContainer.id
FROM
  targetContainer

Om uw NoSQL-query beknopter te maken, is het gebruikelijk om de containernaam een alias te geven met een kortere naam. Aliasing kan worden uitgevoerd met behulp van het AS trefwoord:

SELECT
  p.id
FROM
  products AS p

De querytaal heeft ook een verkorte syntaxis waarbij de alias direct na de verwijzing van de doelcontainer kan worden gedefinieerd zonder het AS trefwoord. Deze afkorting is functioneel gelijk aan het gebruik van het AS trefwoord:

SELECT
  p.id
FROM
  products p

Eigenschapsaliassen

U kunt ook de naam van velden in uw resultaten wijzigen met behulp van aliassen die zijn gedefinieerd met hetzelfde AS trefwoord. Bekijk deze voorbeeldgegevens voor de volgende voorbeelden:

[
  {
    "name": "Oceabelle Scarf",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "metadata": {
      "link": "https://www.adventure-works.com/oceabelle-scarf/68719522190.p"
    }
  },
  {
    "name": "Shinity Socks",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "metadata": {
      "link": "https://www.adventure-works.com/shinity-socks/68719522161.p"
    }
  },
  {
    "name": "Horric Socks",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "metadata": {
      "link": "https://www.adventure-works.com/horric-socks/68719522177.p"
    }
  }
]

In dit eerste voorbeeld wordt de metadataLink alias gebruikt voor de waarde van de metadata.link eigenschap:

SELECT
  p.name,
  p.metadata.link AS metadataLink
FROM
  products p

[
  {
    "name": "Oceabelle Scarf",
    "metadataLink": "https://www.adventure-works.com/oceabelle-scarf/68719522190.p"
  },
  {
    "name": "Shinity Socks",
    "metadataLink": "https://www.adventure-works.com/shinity-socks/68719522161.p"
  },
  {
    "name": "Horric Socks",
    "metadataLink": "https://www.adventure-works.com/horric-socks/68719522177.p"
  }
]

Belangrijk

U kunt aliasing niet gebruiken om een waarde als eigenschapsnaam te projecteren met een spatie, speciaal teken of gereserveerd woord. Als u de projectie van een waarde wilt wijzigen in bijvoorbeeld een eigenschapsnaam met een spatie, moet u een JSON-expressie gebruiken.

Bijvoorbeeld

SELECT VALUE {
  "product name": p.name,
  "from": p.metadata.link,
  "detail/category": p.detailCategory
}
FROM
  products p
WHERE
  p.detailCategory = "apparel-accessories-scarfs-and-socks"

[
  {
    "product name": "Oceabelle Scarf",
    "from": "https://www.adventure-works.com/oceabelle-scarf/68719522190.p",
    "detail/category": "apparel-accessories-scarfs-and-socks"
  },
  {
    "product name": "Shinity Socks",
    "from": "https://www.adventure-works.com/shinity-socks/68719522161.p",
    "detail/category": "apparel-accessories-scarfs-and-socks"
  },
  {
    "product name": "Horric Socks",
    "from": "https://www.adventure-works.com/horric-socks/68719522177.p",
    "detail/category": "apparel-accessories-scarfs-and-socks"
  }
]

Als een NoSQL-query twee eigenschappen met dezelfde naam heeft, gebruikt u aliassen om de naam van een of beide eigenschappen te wijzigen, zodat ze niet eenduidig zijn in het verwachte resultaat.

Bekijk deze voorbeeldgegevens:

[
  {
    "name": "Oceabelle Scarf",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "sizes": [
      {
        "key": "s"
      },
      ...
    ],
    "tags": [
      ...
    ]
  },
  {
    "name": "Shinity Socks",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "sizes": [
      ...
      {
        "key": "10"
      },
      ...
    ],
    "tags": [
      ...
      {
        "key": "length"
      }
    ]
  },
  {
    "name": "Horric Socks",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "sizes": [
      ...
      {
        "key": "7"
      },
      ...
    ],
    "tags": [
      {
        "key": "fabric"
      },
      ...
    ]
  }
]

Opmerking

In deze voorbeeldgegevens en het queryresultaat zijn meerdere eigenschappen en waarden verwijderd om kortheid te hebben.

Deze NoSQL-query retourneert de p.sizes[].key en p.tags[].key eigenschappen in het resultaat van meerdere producten, maar zal elke key eigenschap alias gebruiken om conflicten te voorkomen:

SELECT
  p.name,
  s.key AS sizeKey,
  t.key AS tagKey
FROM
  products p
JOIN
  s IN p.sizes
JOIN
  t in p.tags
WHERE
  p.detailCategory = "apparel-accessories-scarfs-and-socks"

[
  {
    "name": "Oceabelle Scarf",
    "sizeKey": "s",
    "tagKey": "fabric"
  },
  ...
  {
    "name": "Shinity Socks",
    "sizeKey": "10",
    "tagKey": "length"
  },
  ...
  {
    "name": "Horric Socks",
    "sizeKey": "7",
    "tagKey": "fabric"
  }
]

Verwante inhoud

  • Last updated on