JSON_VALUE（Transact-SQL）

适用于：sql Server 2016 （13.x） 及更高版本 Azure SQL 数据库Azure SQL 托管实例Azure Synapse AnalyticsSQL 分析终结点Microsoft FabricWarehouse 中的Microsoft Fabric SQL 数据库在 Microsoft Fabric 中的 fabric SQL 数据库

语法 JSON_VALUE 从 JSON 字符串中提取标量值。

若要从 JSON 字符串而不是标量值中提取对象或数组，请参阅 JSON_QUERY。 有关 JSON_VALUE 和 JSON_QUERY 之间差异的信息，请参阅比较 JSON_VALUE 和 JSON_QUERY。

Transact-SQL 语法约定

Syntax

JSON_VALUE ( expression , path [ RETURNING data_type ] )

Arguments

expression

表达式。 通常是包含 JSON 文本的变量或列的名称。

如果在JSON_VALUE找到路径标识的值之前在表达式中找不到无效的 JSON，则函数将返回错误。 如果 JSON_VALUE 找不到 路径标识的值，它将扫描整个文本，如果发现 表达式中的任何位置都无效的 JSON，则会返回错误。

path

指定要提取属性的 JSON 路径。 有关详细信息，请参阅 SQL 数据库引擎中的 JSON 路径表达式。

在 SQL Server 2017（14.x）和 Azure SQL 数据库中，可以将变量作为 路径的值提供。

如果 路径 的格式无效， JSON_VALUE 则返回错误。

data_type

返回在 SQL 类型中指定的值。 仅当输入为 JSON 类型时才受支持。 支持的 SQL 类型包括：tinyint、smallint、int、bigint、decimal、numeric、float、real、char、varchar、varchar、varchar（max）、nchar、nvarchar（max）、date、time、datetime2 和 datetimeoffset。

返回值

如果未 RETURNING 包括：

• 返回 nvarchar(4000) 类型的单个文本值。 返回值的排序规则与输入表达式的排序规则相同。

• 如果值大于 4000 个字符：

  • 在宽松模式下，JSON_VALUE 返回 NULL。
  • 在严格模式下，JSON_VALUE 返回错误。

  如果必须返回大于 4000 个字符的标量值，请使用 OPENJSON 而不是 JSON_VALUE。 有关详细信息，请参阅 OPENJSON。

如果 RETURNING 包括：

返回在 SQL 类型中指定的值。 支持的 SQL 类型包括：tinyint、smallint、int、bigint、decimal、numeric、float、real、char、varchar、varchar、varchar（max）、nchar、nvarchar（max）、date、time、datetime2 和 datetimeoffset。

无论 JSON 文档存储在 varchar、 nvarchar 还是本机 json 数据类型中，JSON 函数的工作方式都相同。

Remarks

宽松模式和严格模式

请参考以下 JSON 文本：

DECLARE @jsonInfo AS NVARCHAR (MAX);

SET @jsonInfo = N'{
     "info":{
       "type":1,
       "address":{
         "town":"Bristol",
         "county":"Avon",
         "country/region":"England"
       },
       "tags":["Sport", "Water polo"]
    },
    "type":"Basic"
 }';

下表对宽松模式和严格模式下 JSON_VALUE 的行为进行了比较。 有关可选路径模式规范（宽松或严格）的详细信息，请参阅 SQL 数据库引擎中的 JSON 路径表达式。

Path	宽松模式下的返回值	严格模式下的返回值	详细信息
$	NULL	Error	不是标量值。 请改用 JSON_QUERY。
$.info.type	N'1'	N'1'	N/a
$.info.address.town	N'Bristol'	N'Bristol'	N/a
$.info."address"	NULL	Error	不是标量值。 请改用 JSON_QUERY。
$.info.tags	NULL	Error	不是标量值。 请改用 JSON_QUERY。
$.info.type[0]	NULL	Error	不是数组。
$.info.none	NULL	Error	属性不存在。

Examples

示例 1

以下示例在查询结果中使用 JSON 属性 town 和 state 的值。 由于 JSON_VALUE 保留了源的排序规则，因此结果的排序顺序取决于 jsonInfo 列的排序规则。

Note

（本示例假定命名 Person.Person 的表包含 jsonInfo JSON 文本列，并且此列具有前面在讨论宽松模式和严格模式时显示的结构。在 AdventureWorks 示例数据库中， Person 表实际上不包含列 jsonInfo 。

SELECT FirstName,
       LastName,
       JSON_VALUE(jsonInfo, '$.info.address.town') AS Town
FROM Person.Person
WHERE JSON_VALUE(jsonInfo, '$.info.address.state') LIKE 'US%'
ORDER BY JSON_VALUE(jsonInfo, '$.info.address.town');

示例 2

下面的示例将 JSON 属性 town 的值提取到本地变量。

DECLARE @jsonInfo AS NVARCHAR (MAX);
DECLARE @town AS NVARCHAR (32);

SET @jsonInfo = N'{"info":{"address":[{"town":"Paris"},{"town":"London"}]}}';
SET @town = JSON_VALUE(@jsonInfo, '$.info.address[0].town'); -- Paris
SET @town = JSON_VALUE(@jsonInfo, '$.info.address[1].town'); -- London

示例 3

下面的示例基于 JSON 属性的值创建计算列。

CREATE TABLE dbo.Store
(
    StoreID INT IDENTITY (1, 1) NOT NULL,
    Address VARCHAR (500),
    jsonContent NVARCHAR (4000),
    Longitude AS JSON_VALUE(jsonContent, '$.address[0].longitude'),
    Latitude AS JSON_VALUE(jsonContent, '$.address[0].latitude')
);

示例 4

以下示例使用 JSON_VALUE JSON 数组提取值，并将该值作为日期类型值返回。

DECLARE @j AS JSON = '[1, 1.3333, true, "a", "1", "2025-01-01"]';

SELECT JSON_VALUE(@j, '$[5]' RETURNING date) AS date_value;

date_value
--------
2025-01-01

相关内容

• SQL 数据库引擎中的 JSON 路径表达式
• SQL Server 中的 JSON 数据