JSON_QUERY (Transact-SQL)JSON_QUERY (Transact-SQL)

Применимо к:Applies to: даSQL Server 2016 (13.x);SQL Server 2016 (13.x)yesSQL Server 2016 (13.x);SQL Server 2016 (13.x) и более поздние версии ДаБаза данных SQL AzureAzure SQL DatabaseYesБаза данных SQL AzureAzure SQL Database ДаУправляемый экземпляр SQL AzureAzure SQL Managed InstanceYesУправляемый экземпляр SQL AzureAzure SQL Managed Instance даAzure Synapse AnalyticsAzure Synapse AnalyticsyesAzure Synapse AnalyticsAzure Synapse AnalyticsПрименимо к:Applies to: даSQL Server 2016 (13.x);SQL Server 2016 (13.x)yesSQL Server 2016 (13.x);SQL Server 2016 (13.x) and later ДаБаза данных SQL AzureAzure SQL DatabaseYesБаза данных SQL AzureAzure SQL Database ДаУправляемый экземпляр SQL AzureAzure SQL Managed InstanceYesУправляемый экземпляр SQL AzureAzure SQL Managed Instance даAzure Synapse AnalyticsAzure Synapse AnalyticsyesAzure Synapse AnalyticsAzure Synapse Analytics

Извлекает объект или массив из строки JSON.Extracts an object or an array from a JSON string.

Чтобы извлечь скалярное значение, а не объект или массив из строки JSON, см. раздел JSON_VALUE (Transact-SQL).To extract a scalar value from a JSON string instead of an object or an array, see JSON_VALUE (Transact-SQL). Сведения о различиях между JSON_VALUE и JSON_QUERY см. в разделе Сравнение JSON_VALUE и JSON_QUERY.For info about the differences between JSON_VALUE and JSON_QUERY, see Compare JSON_VALUE and JSON_QUERY.

Значок ссылки на раздел Синтаксические обозначения в Transact-SQLTopic link icon Transact-SQL Syntax Conventions

СинтаксисSyntax

JSON_QUERY ( expression [ , path ] )  

АргументыArguments

expressionexpression
Выражение.An expression. Обычно имя переменной или столбца, содержащего текст JSON.Typically the name of a variable or a column that contains JSON text.

Если функция JSON_QUERY находит код JSON, который не является допустимым в выражении перед тем, как она найдет значение, определяемое путем, функция возвращает ошибку.If JSON_QUERY finds JSON that is not valid in expression before it finds the value identified by path, the function returns an error. Если функция JSON_QUERY не находит значение, определяемое путем, она просматривает весь текст и возвращает ошибку, если он найдет недопустимый код JSON в любом месте выражения.If JSON_QUERY doesn't find the value identified by path, it scans the entire text and returns an error if it finds JSON that is not valid anywhere in expression.

путьpath
Путь JSON, который указывает объект или массив для извлечения.A JSON path that specifies the object or the array to extract.

В SQL Server 2017 (14.x);SQL Server 2017 (14.x) и База данных SQL AzureAzure SQL Database можно указать переменную в качестве значения пути.In SQL Server 2017 (14.x);SQL Server 2017 (14.x) and in База данных SQL AzureAzure SQL Database, you can provide a variable as the value of path.

В пути JSON можно указать режим синтаксического анализа: нестрогий или строгий режим.The JSON path can specify lax or strict mode for parsing. Если режим анализа не указан явно, по умолчанию используется нестрогий режим.If you don't specify the parsing mode, lax mode is the default. Дополнительные сведения см. в статье Выражения пути JSON (SQL Server).For more info, see JSON Path Expressions (SQL Server).

Значение пути по умолчанию — '$'.The default value for path is '$'. Поэтому если не указать значение для пути, JSON_QUERY возвращает входное выражение.As a result, if you don't provide a value for path, JSON_QUERY returns the input expression.

Если путь имеет недопустимый формат, JSON_QUERY возвращает ошибку.If the format of path isn't valid, JSON_QUERY returns an error.

Возвращаемое значениеReturn value

Возвращает фрагмент JSON типа nvarchar(max).Returns a JSON fragment of type nvarchar(max). Параметры сортировки для возвращаемого значения совпадают с параметрами сортировки входного выражения.The collation of the returned value is the same as the collation of the input expression.

Если значение не является объектом или массивом:If the value is not an object or an array:

  • В нестрогом режиме JSON_QUERY возвращает значение NULL.In lax mode, JSON_QUERY returns null.

  • В строгом режиме JSON_QUERY возвращает сообщение об ошибке.In strict mode, JSON_QUERY returns an error.

RemarksRemarks

Нестрогий и строгий режимыLax mode and strict mode

Рассмотрим следующий текст JSON:Consider the following JSON text:

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

В следующей таблице сравнивается поведение JSON_QUERY в нестрогом и в строгом режиме.The following table compares the behavior of JSON_QUERY in lax mode and in strict mode. Дополнительные сведения о необязательном режиме пути (строгий или нестрогий) см. в статье Выражения пути JSON (SQL Server).For more info about the optional path mode specification (lax or strict), see JSON Path Expressions (SQL Server).

путьPath Возвращаемое значение в нестрогом режимеReturn value in lax mode Возвращаемое значение в строгом режимеReturn value in strict mode Дополнительные сведенияMore info
$ Возвращает весь текст JSON.Returns the entire JSON text. Возвращает весь текст JSON.Returns the entire JSON text. НедоступноN/a
$.info.type$.info.type NULLNULL ErrorError Значение не является объектом или массивом.Not an object or array.

Используйте JSON_VALUE.Use JSON_VALUE instead.
$.info.address.town$.info.address.town NULLNULL ErrorError Значение не является объектом или массивом.Not an object or array.

Используйте JSON_VALUE.Use JSON_VALUE instead.
$.info."address"$.info."address" N'{ "town":"Bristol", "county":"Avon", "country":"England" }'N'{ "town":"Bristol", "county":"Avon", "country":"England" }' N'{ "town":"Bristol", "county":"Avon", "country":"England" }'N'{ "town":"Bristol", "county":"Avon", "country":"England" }' НедоступноN/a
$.info.tags$.info.tags N'[ "Sport", "Water polo"]'N'[ "Sport", "Water polo"]' N'[ "Sport", "Water polo"]'N'[ "Sport", "Water polo"]' НедоступноN/a
$.info.type[0]$.info.type[0] NULLNULL ErrorError Не является массивом.Not an array.
$.info.none$.info.none NULLNULL ErrorError Свойство не существует.Property does not exist.

Использование JSON_QUERY с FOR JSONUsing JSON_QUERY with FOR JSON

JSON_QUERY возвращает допустимый фрагмент JSON.JSON_QUERY returns a valid JSON fragment. Поэтому FOR JSON не экранирует специальные символы в возвращаемом значении JSON_QUERY.As a result, FOR JSON doesn't escape special characters in the JSON_QUERY return value.

Если вы возвращаете результаты для FOR JSON и включаете данные, которые уже находятся в формате JSON (в столбце или в результате выражения), оберните данные JSON с помощью JSON_QUERY без параметра путь.If you're returning results with FOR JSON, and you're including data that's already in JSON format (in a column or as the result of an expression), wrap the JSON data with JSON_QUERY without the path parameter.

ПримерыExamples

Пример 1Example 1

В следующем примере показано, как можно вернуть фрагмент JSON из столбца CustomFields в результатах запроса.The following example shows how to return a JSON fragment from a CustomFields column in query results.

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

Пример 2Example 2

В следующем примере показано, как включить фрагменты JSON в выходные данные предложения FOR JSON.The following example shows how to include JSON fragments in the output of the FOR JSON clause.

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

См. также разделSee also