CREATE JSON INDEX （Transact-SQL）

2025-05-27

適用於： SQL Server 2025 （17.x）預覽

在 SQL Server 2025 （17.x） Preview 中，於指定的數據表和數據行上建立 JSON 索引。

JSON 索引：

可以在數據表中有數據之前建立。
可以藉由指定限定的資料庫名稱，在另一個資料庫中的數據表上建立。
要求數據表具有叢集主鍵。
無法在索引檢視表上指定。

備註

建立 JSON 索引目前為預覽狀態，且僅適用於 SQL Server 2025 （17.x）預覽版。

Transact-SQL 語法慣例

語法

CREATE JSON INDEX name ON table_name (json_column_name)
  [ FOR ( sql_json_path [ , ...n ] ) ]
  [ WITH ( <json_index_option> [ , ...n ] ) ]
  [ ON { filegroup_name | "default" } ]
[ ; ]

<object> ::=
    { database_name.schema_name.table_name | schema_name.table_name | table_name }

<sql_json_path> ::=
    { character_string_literal }

<json_index_option> ::=
{
    FILLFACTOR = fillfactor
  | DROP_EXISTING = { ON | OFF }
  | ONLINE = OFF
  | ALLOW_ROW_LOCKS = { ON | OFF }
  | ALLOW_PAGE_LOCKS = { ON | OFF }
  | MAXDOP = max_degree_of_parallelism
  | DATA_COMPRESSION = { NONE | ROW | PAGE }
}

論點

索引名稱

索引的名稱。索引名稱在數據表內必須是唯一的，但不需要在資料庫中是唯一的。索引名稱必須遵循識別碼的規則。

ON <物件> (json_column_name)

指定要建立索引的物件（資料庫、架構或數據表），以及 json 數據行的名稱。
json_column_name

中 table_name 數據類型的數據行名稱，其中包含零個或多個指定的 SQL/JSON 路徑。
sql_json_path

需要從 json_column_name擷取和編製索引的 SQL/JSON 路徑。 sql_json_path 的預設值為 $。
- 遞迴地索引指定路徑及其後續的所有鍵/值。
- 在 JSON 檔路徑中支援最多 128 個層級。
- 不允許重疊。
例如， $.a 並 $.a.b 引發錯誤，因為路徑 $.a 遞歸包含所有路徑，且使用者意圖尚不清楚。

ON filegroup_name

在指定的檔案群組上建立指定的索引。如果未指定任何位置且數據表未分割，索引會使用與基礎表相同的檔案群組。檔案群組必須已經存在。

ON “default”

在預設檔案群組上建立指定的索引。

在此內容中，預設字詞不是關鍵詞。它是預設檔案群組的識別碼，並必須以分隔符號括起，例如 ON "default" 或 ON [default]。如果 "default" 已指定，則 QUOTED_IDENTIFIER 選項必須是 ON 目前會話的選項。這是預設設定。如需詳細資訊，請參閱 SET QUOTED_IDENTIFIER。

<object>：： =

要編製索引的完整定義或非完整定義的物件。

database_name

資料庫的名稱。
schema_name

資料表所屬的結構描述名稱。
table_name

要編製索引之數據表的名稱。

FILLFACTOR = fillfactor

指定百分比，以表示 Database Engine 在索引建立或重建期間應該將每個索引頁面的分葉層級填滿的程度。 fillfactor 必須是從 1 到的 100整數值。預設值為 0。如果 fillfactor 為 100 或 0，Database Engine 會建立索引，將分頁頁面填滿至容量上限。

備註

填滿因數值 0 和 100 在所有方面都相同。

只有在建立或重新編製索引時才會套用 FILLFACTOR 設定。資料庫引擎不會動態保留頁面中空白空間的指定百分比。若要檢視填滿因數設定，請使用 sys.indexes 目錄檢視。

建立叢集索引 FILLFACTOR 的小於 100 會影響數據佔用的儲存空間量，因為Database Engine會在建立叢集索引時重新發佈數據。

如需詳細資訊，請參閱指定索引的填滿因素。

DROP_EXISTING = { ON |OFF }

指定卸除並重建已命名、預先存在的空間索引。預設值為 OFF。

開啟

現有的索引會卸除並重建。指定的索引名稱必須與目前現有的索引相同;不過，可以修改索引定義。例如，您可以指定不同的資料行、排序順序、數據分割配置或索引選項。
OFF

如果指定的索引名稱已經存在，就會顯示錯誤。

無法使用DROP_EXISTING來變更索引類型。

在線上 = 關閉

指定在索引作業期間，基礎表和相關聯的索引無法用於查詢和數據修改。在此版本的 SQL Server 中，JSON 索引不支援在線索引組建。如果這個選項設定 ON 為 JSON 索引，就會引發錯誤。省略 ONLINE 選項或設定 ONLINE 為 OFF。

建立、重建或卸除 JSON 索引的離線索引作業，會取得資料表上的架構修改（Sch-M）鎖定。這可防止所有使用者在作業持續期間存取基礎資料表。

SQL Server 的每個版本都無法使用在線索引作業。

如需查看 Windows 上各版本 SQL Server 所支援的功能清單，請參閱：

ALLOW_ROW_LOCKS = { ON |OFF }

指定是否允許數據列鎖定。預設值為 ON。

開啟

當存取索引時，允許資料列鎖定。資料庫引擎會決定使用資料列鎖定的時機。
OFF

不會使用資料列鎖定。

ALLOW_PAGE_LOCKS = { ON |OFF }

指定是否允許頁面鎖定。預設值為 ON。

開啟

當存取索引時，允許頁面鎖定。資料庫引擎會決定使用頁面鎖定的時機。
OFF

不會使用頁面鎖定。

MAXDOP = max_degree_of_parallelism

覆蓋索引作業期間的 max degree of parallelism 組態選項。使用 MAXDOP 來限制平行計劃執行中使用的處理器數目。最大值為64個處理器。

這很重要

雖然MAXDOP選項在語法上受到支援，但CREATE SPATIAL INDEX目前只使用單一處理器。

max_degree_of_parallelism 可以是下列其中一個值。

價值觀	說明
`1`	抑制平行計劃方案的生成。
`>1`	根據目前的系統工作負載，將平行索引作業所使用的處理器數目上限，限制為所指定的數目或更少的數目。
`0` (預設值)	根據目前的系統工作負載，使用實際數目或比實際數目更少的處理器。

如需詳細資訊，請參閱設定平行索引作業。

SQL Server 的所有版本都無法使用平行索引作業。

如需查看 Windows 上各版本 SQL Server 所支援的功能清單，請參閱：

DATA_COMPRESSION = { NONE |ROW |PAGE }

決定索引所使用的數據壓縮層級。

沒有

索引未對數據使用任何壓縮
列

索引使用於數據的資料列壓縮
頁

使用於數據索引的頁面壓縮

備註

每個選項只能為每個 CREATE JSON INDEX 語句指定一次。指定任何重覆選項會引發錯誤。

[ ON { filegroup_name |“default” } ]

如果您指定 JSON 索引的檔案群組，則不論數據表的數據分割配置為何，索引都會放在該檔案群組上。

如需建立索引的詳細資訊，請參閱 CREATE INDEX 的備註。

JSON 索引支援的述詞

如果 JSON 索引存在於 json 數據行上，則可以優化數據表中 JSON 數據行中包含的 JSON 檔搜尋作業。 JSON 索引用於具有各種 JSON 函式表示式的查詢中。

下列範例使用資料庫中的 Sales.SalesOrderHeader 表格，其中有一個名為 AdventureWorks2022 的 json 欄位。 Info 欄會建立為 json 類型。 JSON 索引也會在 Info 數據行上，以預設設定建立。下列程式代碼範例顯示 CREATE JSON INDEX 語句：

CREATE JSON INDEX sales_info_idx ON Sales.SalesOrderHeader(Info);

針對範例搜尋表示式，請使用下列 JSON 檔作為數據：

銷售訂單號碼	資訊
`437`	`{"Customer":{"Name":"Kelsey Raje","ID":16517,"Type":"IN"},"Order":{"ID":43710,"Number":"SO43710","CreationDate":"2011-06-02T00:00:00","TotalDue":3953.9884}}`
`643`	`{"Customer":{"Name":"Aaron Campbell","ID":16167,"Type":"IN"},"Order":{"ID":64304,"Number":"SO64304","CreationDate":"2014-01-16T00:00:00","TotalDue":36.0230, "IsProcessed": true}}`

JSON_PATH_EXISTS函式

使用 JSON_PATH_EXISTS 函式來測試 JSON 檔中是否有指定的 SQL/JSON 路徑。

此查詢示範 JSON_PATH_EXISTS 可在 JSON 數據行上使用 JSON 索引進行優化：

SELECT COUNT(*)
FROM Sales.SalesOrderHeader
WHERE JSON_PATH_EXISTS(Info, '$.Order.IsProcessed') = 1;

JSON 索引支援 JSON_PATH_EXISTS 述詞和下列運算符：

比較運算子（=）
IS [NOT] NULL 述詞（目前不支援）

JSON_VALUE函式

使用 JSON_VALUE ，在 JSON 檔中擷取指定 SQL/JSON 路徑中的 JSON 文字/純量值。下列查詢顯示如何使用 JSON_VALUE JSON 索引優化 json 資料行上的表達式。

在物件屬性中檢查 JSON 字串的相等性：

SELECT COUNT(*)
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.Type') = 'IN';

將值轉換為 int 資料類型後，檢查物件屬性中的 JSON 數字是否相等。

SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) = 16167;

將 JSON 數字轉換為 int 資料類型後，於物件屬性中進行範圍搜尋：

SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) IN (16167, 16517);

在將值轉換成 十進位 數據類型之後，範圍搜尋 JSON 數字於物件屬性中：

SELECT *
FROM Sales.SalesOrderHeader
WHERE JSON_VALUE(Info, '$.Order.TotalDue RETURNING decimal(20, 4)) BETWEEN 1000 and 2000;

JSON 索引支援 JSON_VALUE 述詞，以及下列運算子：

比較運算子（=）
LIKE 謂詞（尚未支援）
IS [NOT] NULL 謂詞（尚未支援）

JSON_CONTAINS函式

JSON_CONTAINS函式支援在 JSON 檔中輕鬆搜尋 JSON 值，如果 JSON 資料行上存在，可以使用 JSON 索引。此函式可用來測試 JSON 純量值、物件或數位是否包含在 JSON 檔中的指定 SQL/JSON 路徑中。指定為 SQL 純量類型的搜尋值會根據現有的 SQL/JSON 類型轉換來轉換。這些規則定義於行為區段中。

要求

包含 JSON 資料行的數據表上需要叢集索引鍵。如果叢集索引鍵不存在，就會引發錯誤。叢集索引鍵限制為31個數據行，索引鍵的大小上限應小於128個字節。

權限

用戶必須在該數據表上具有 ALTER 權限，或是 sysadmin 固定伺服器角色的成員，或者是 db_ddladmin 和 db_owner 固定資料庫角色的成員。

局限性

JSON 索引語句存在下列限制：

數據表中的 json 數據行上只能建立一個 JSON 索引。
您可以在資料表中建立最多 249 個 JSON 索引。不支援在特定 JSON 數據行上建立多個 JSON 索引。
無法在計算的 json 數據行上建立 JSON 索引。
無法在檢視表、表值變數或記憶體優化表的 JSON 列上建立索引。
JSON 索引只能以離線方式建立或變更。
JSON 路徑無法在索引定義中重疊。例如，$a 和 $a.b 重疊，不允許在 CREATE JSON INDEX 語句中。
修改路徑需要重新建立 JSON 索引。
索引提示不支援 JSON 索引。
不支援數據壓縮選項。

範例

A。在 JSON 數據行上建立 JSON 索引

下列範例會建立名為 docs 的數據表，其中包含 json 類型資料行 content。此範例然後會在 json_content_index 資料行上建立 JSON 索引 content。此範例會在 JSON 檔中的整個 JSON 檔或所有 SQL/JSON 路徑上建立 JSON 索引。

DROP TABLE IF EXISTS docs;

CREATE TABLE docs (content JSON, id INT PRIMARY KEY);
CREATE JSON INDEX json_content_index ON docs(content);

A。在具有特定路徑的 JSON 數據行上建立 JSON 索引

下列範例會建立名為 docs 的數據表，其中包含 json 類型資料行 content。此範例然後會在 json_content_index 資料行上建立 JSON 索引 content。此範例會在 JSON 檔中的特定 SQL/JSON 路徑上建立 JSON 索引。
這個範例也會將索引 FILLFACTOR 設定為 80。

DROP TABLE IF EXISTS docs;

CREATE TABLE docs (content JSON, id INT PRIMARY KEY);

CREATE JSON INDEX json_content_index
    ON docs(content) FOR ('$.a', '$.b')
    WITH (FILLFACTOR = 80);

共用方式為