Condividi tramite

JSON_QUERY (Transact-SQL)

  • Articolo

Si applica a: SQL Server 2016 (13.x) e Database SQL di Azure Istanza gestita di SQL di Azure Azure Synapse Analytics Endpoint di analisi SQL in Microsoft Fabric Warehouse in Microsoft Fabric

Estrae un oggetto o una matrice da una stringa JSON.

Per estrarre un valore scalare da una stringa JSON anziché un oggetto o una matrice, vedere JSON_VALUE (Transact-SQL). Per informazioni sulle differenze tra JSON_VALUE e JSON_QUERY, si veda Confronto tra JSON_VALUE e JSON_QUERY.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

JSON_QUERY ( expression [ , path ] )

Argomenti

expression

Espressione. In genere il nome di una variabile o di una colonna che contiene testo JSON.

Se JSON_QUERY individua JSON non valido in expression prima di trovare il valore identificato da path, la funzione restituisce un errore. Se JSON_QUERYY non trova il valore identificato da path, analizza l'intero testo e restituisce un errore se rileva JSON non valido in un punto qualsiasi di expression.

path

Percorso JSON che specifica l'oggetto o la matrice da estrarre.

In SQL Server 2017 (14.x) e in Azure SQL Database è possibile fornire una variabile come valore del percorso.

Il percorso JSON può specificare la modalità lax o strict per l'analisi. Se non si specifica la modalità di analisi, la modalità predefinita è lax. Per altre informazioni, vedere Espressioni di percorso JSON (SQL Server).

Il valore predefinito per path è $. Di conseguenza, se non si specifica un valore per path, JSON_QUERY restituisce l'input expression.

Se il formato di path non è valido, JSON_QUERY restituisce un errore.

Valore restituito

Restituisce un frammento JSON di tipo nvarchar(max). Le regole di confronto del valore restituito sono le stesse di quelle dell'espressione di input.

Se il valore non è un oggetto o una matrice:

  • In modalità lax, JSON_QUERY restituisce null.

  • In modalità strict, JSON_QUERY restituisce un errore.

Osservazioni:

Modalità lax e modalità strict

Si consideri il testo JSON seguente:

{
   "info": {
      "type": 1,
      "address": {
         "town": "Cheltenham",
         "county": "Gloucestershire",
         "country": "England"
      },
      "tags": ["Sport", "Water polo"]
   },
   "type": "Basic"
}

Nella tabella seguente viene confrontato il comportamento di JSON_QUERY in modalità lax e in modalità strict. Per altre informazioni sulla specifica facoltativa della modalità del percorso (lax o strict), vedere Espressioni di percorso JSON (SQL Server).

Percorso Valore restituito in modalità lax Valore restituito in modalità strict Altre informazioni
$ Restituisce l'intero testo JSON. Restituisce l'intero testo JSON. N/a
$.info.type NULL Error Non è un oggetto o una matrice.

Utilizzare invece JSON_VALUE.
$.info.address.town NULL Error Non è un oggetto o una matrice.

Utilizzare invece JSON_VALUE.
$.info."address" N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }' N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }' N/a
$.info.tags N'[ "Sport", "Water polo"]' N'[ "Sport", "Water polo"]' N/a
$.info.type[0] NULL Error Non è una matrice.
$.info.none NULL Error La proprietà non esiste.

Uso di JSON_QUERY con FOR JSON

JSON_QUERY restituisce un frammento JSON valido. Di conseguenza, FOR JSON non ignora i caratteri speciali nel valore restituito di JSON_QUERY.

Se vengono restituiti risultati con FOR JSON e vengono inclusi dati che sono già in formato JSON, in una colonna o come risultato di un'espressione, eseguire il wrapping dei dati JSON con JSON_QUERY senza il parametro path.

Esempi

Esempio 1

Nell'esempio seguente viene illustrato come restituire un frammento JSON da una colonna CustomFields nei risultati della query.

SELECT PersonID,FullName,
  JSON_QUERY(CustomFields,'$.OtherLanguages') AS Languages
FROM Application.People

Esempio 2

Nell'esempio seguente viene illustrato come includere frammenti JSON nell'output della clausola FOR JSON.

SELECT StockItemID, StockItemName,
         JSON_QUERY(Tags) as Tags,
         JSON_QUERY(CONCAT('["',ValidFrom,'","',ValidTo,'"]')) ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH

Contenuto correlato