Bagikan melalui

BUAT INDEKS JSON (Transact-SQL)

Berlaku untuk: SQL Server 2025 (17.x)

Membuat indeks JSON pada tabel dan kolom tertentu di SQL Server 2025 (17.x).

Indeks JSON:

  • Dapat dibuat sebelum ada data dalam tabel.
  • Dapat dibuat pada tabel di database lain dengan menentukan nama database yang memenuhi syarat.
  • Mengharuskan tabel memiliki kunci primer terkluster.
  • Tidak dapat ditentukan pada tampilan terindeks.

Nota

Membuat indeks JSON saat ini dalam pratinjau dan hanya tersedia di SQL Server 2025 (17.x).

Konvensi sintaks Transact-SQL

Sintaksis

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> ::=
{
    OPTIMIZE_FOR_ARRAY_SEARCH = { ON | OFF }
  | 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 }
}

Argumen

nama indeks

Nama indeks. Nama indeks harus unik dalam tabel tetapi tidak harus unik dalam database. Nama indeks harus mengikuti aturan pengidentifikasi.

  • ON <objek> ( json_column_name )

    Menentukan objek (database, skema, atau tabel) tempat indeks akan dibuat, dan nama kolom json .

  • json_column_name

    Nama kolom berjenis data json di table_name yang berisi nol atau lebih jalur SQL/JSON yang ditentukan.

  • sql_json_path

    Jalur SQL/JSON yang perlu diekstrak dan diindeks dari json_column_name. Default untuk sql_json_path adalah $.

    • Secara rekursif mengindeks semua kunci/nilai dari jalur yang ditentukan dan seterusnya.
    • Mendukung hingga 128 tingkat di jalur dokumen JSON.
    • Tidak memungkinkan tumpang tindih.

    Misalnya, $.a dan $.a.b menimbulkan kesalahan, karena jalur $.a secara rekursif menyertakan semua jalur dan niat pengguna tidak jelas.

PADA filegroup_name

Membuat indeks yang ditentukan pada grup file yang ditentukan. Jika tidak ada lokasi yang ditentukan dan tabel tidak dipartisi, indeks menggunakan grup file yang sama dengan tabel yang mendasar. Grup file harus sudah ada.

AKTIF "default"

Membuat indeks yang ditentukan pada grup file default.

Istilah default, dalam konteks ini, bukan kata kunci. Ini adalah pengidentifikasi untuk grup file default dan harus dibatasi, seperti dalam ON "default" atau ON [default]. Jika "default" ditentukan, QUOTED_IDENTIFIER opsi harus untuk ON sesi saat ini. Ini adalah pengaturan default. Untuk informasi selengkapnya, lihat MENGATUR QUOTED_IDENTIFIER.

<objek>:: =

Objek yang sepenuhnya memenuhi syarat atau tidak memenuhi syarat untuk diindeks.

  • database_name

    Nama database.

  • schema_name

    Nama skema tempat tabel berada.

  • table_name

    Nama tabel yang akan diindeks.

OPTIMIZE_FOR_ARRAY_SEARCH = { AKTIF | NONAKTIF }

Menentukan apakah pencarian array dioptimalkan dalam indeks JSON. Defaultnya adalah OFF.

FILLFACTOR = fillfactor

Menentukan persentase yang menunjukkan seberapa lengkap Mesin Database harus membuat tingkat daun setiap halaman indeks selama pembuatan atau pembangunan ulang indeks. fillfactor harus berupa nilai bilangan bulat dari 1 ke 100. Defaultnya adalah 0. Jika fillfactor adalah 100 atau 0, Mesin Database membuat indeks dengan halaman cabang yang diisi sepenuhnya.

Nota

Nilai faktor 0 dan 100 sama dalam semua hal.

FILLFACTOR Pengaturan hanya berlaku saat indeks dibuat atau dibangun kembali. Mesin Database tidak secara dinamis menyimpan persentase ruang kosong yang ditentukan di halaman. Untuk melihat pengaturan faktor pengisian, gunakan tampilan katalog sys.indexes .

Membuat indeks berkluster dengan FILLFACTOR kurang dari 100 memengaruhi jumlah ruang penyimpanan yang ditempati data, karena Mesin Database mendistribusikan ulang data saat membuat indeks berkluster.

Untuk informasi selengkapnya, lihat Menentukan Faktor Pengisian untuk Indeks.

DROP_EXISTING = { AKTIF | NONAKTIF }

Menentukan bahwa indeks JSON bernama yang sudah ada sebelumnya dihilangkan dan dibangun kembali. Defaultnya adalah OFF.

  • AKTIF

    Indeks yang ada dihilangkan dan dibangun kembali. Nama indeks yang ditentukan harus sama dengan indeks yang ada saat ini; namun, definisi indeks dapat dimodifikasi. Misalnya, Anda dapat menentukan kolom, urutan pengurutan, skema partisi, atau opsi indeks yang berbeda.

  • TIDAK AKTIF

    Kesalahan ditampilkan jika nama indeks yang ditentukan sudah ada.

Jenis indeks tidak dapat diubah dengan menggunakan DROP_EXISTING.

ONLINE = NONAKTIF

Menentukan bahwa tabel yang mendasari dan indeks terkait tidak tersedia untuk kueri dan modifikasi data selama operasi indeks. Dalam versi SQL Server ini, build indeks online tidak didukung untuk indeks JSON. Jika opsi ini diatur ke ON untuk indeks JSON, kesalahan akan muncul. Hilangkan ONLINE opsi atau atur ONLINE ke OFF.

Operasi indeks offline yang membuat, membangun ulang, atau menjatuhkan indeks JSON, memperoleh kunci modifikasi Skema (Sch-M) pada tabel. Ini mencegah semua akses pengguna ke tabel yang mendasar selama durasi operasi.

Operasi indeks online tidak tersedia di setiap edisi SQL Server.

Untuk daftar fitur yang didukung oleh edisi SQL Server di Windows, lihat:

ALLOW_ROW_LOCKS = { AKTIF | NONAKTIF }

Menentukan apakah kunci baris diizinkan. Defaultnya adalah ON.

  • AKTIF

    Kunci baris diperbolehkan saat mengakses indeks. Mesin Database menentukan kapan kunci baris digunakan.

  • TIDAK AKTIF

    Kunci baris tidak digunakan.

ALLOW_PAGE_LOCKS = { AKTIF | NONAKTIF }

Menentukan apakah kunci halaman diizinkan. Defaultnya adalah ON.

  • AKTIF

    Kunci halaman diizinkan saat mengakses indeks. Mesin Database menentukan kapan kunci halaman digunakan.

  • TIDAK AKTIF

    Kunci halaman tidak digunakan.

MAXDOP = max_degree_of_parallelism

Mengesampingkan max degree of parallelism opsi konfigurasi selama durasi operasi indeks. Gunakan MAXDOP untuk membatasi jumlah prosesor yang digunakan dalam eksekusi rencana paralel. Maksimum adalah 64 prosesor.

Penting

MAXDOP Meskipun opsi ini didukung secara sintis, CREATE JSON INDEX saat ini hanya menggunakan satu prosesor.

max_degree_of_parallelism bisa menjadi salah satu nilai berikut.

Nilai Deskripsi
1 Menonaktifkan pembuatan rencana paralel.
>1 Membatasi jumlah maksimum prosesor yang digunakan dalam operasi indeks paralel ke jumlah yang ditentukan atau lebih sedikit berdasarkan beban kerja sistem saat ini.
0 (standar) Menggunakan jumlah prosesor aktual atau lebih sedikit berdasarkan beban kerja sistem saat ini.

Untuk informasi selengkapnya, lihat Mengonfigurasi operasi indeks paralel.

Operasi indeks paralel tidak tersedia di setiap edisi SQL Server.

Untuk daftar fitur yang didukung oleh edisi SQL Server di Windows, lihat:

DATA_COMPRESSION = { NONE | BARIS | HALAMAN }

Menentukan tingkat kompresi data yang digunakan oleh indeks.

  • TIDAK ADA

    Tidak ada pemadatan yang digunakan pada data oleh indeks

  • BARIS

    Pemadatan baris yang digunakan oleh indeks pada data

  • HALAMAN

    Pemadatan halaman yang digunakan pada data oleh indeks

Komentar

Setiap opsi hanya dapat ditentukan sekali per CREATE JSON INDEX pernyataan. Menentukan duplikat opsi apa pun menimbulkan kesalahan.

[ AKTIF { filegroup_name | "default" } ]

Jika Anda menentukan grup file untuk indeks JSON, indeks ditempatkan pada grup file tersebut, terlepas dari skema pemartisian tabel.

Untuk informasi selengkapnya tentang membuat indeks, lihat bagian Keterangan di CREATE INDEX.

Predikat yang didukung dengan indeks JSON

Operasi pencarian pada dokumen JSON yang terkandung dalam kolom json dalam tabel dapat dioptimalkan jika indeks JSON ada di kolom json . Indeks JSON digunakan dalam kueri dengan berbagai ekspresi berbasis fungsi JSON.

Contoh berikut menggunakan Sales.SalesOrderHeader tabel dalam AdventureWorks2025 database dengan kolom json yang disebut Info. Kolom Info dibuat sebagai jenis json . Indeks JSON juga dibuat pada Info kolom dengan pengaturan default. Sampel kode berikut menunjukkan CREATE JSON INDEX pernyataan:

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

Untuk contoh ekspresi pencarian, gunakan dokumen JSON berikut sebagai data:

NomorPesananPenjualan Informasi
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}}

fungsi JSON_PATH_EXISTS

Gunakan fungsi JSON_PATH_EXISTS untuk menguji apakah jalur SQL/JSON tertentu ada dalam dokumen JSON.

Kueri ini menunjukkan JSON_PATH_EXISTS pada kolom json yang dapat dioptimalkan menggunakan indeks JSON:

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

Indeks JSON didukung dengan JSON_PATH_EXISTS predikat dan operator berikut:

  • Operator perbandingan (=)
  • IS [NOT] NULL predikat (Saat ini tidak didukung)

fungsi JSON_VALUE

Gunakan JSON_VALUE untuk mengekstrak nilai teks /skalar JSON dalam jalur SQL/JSON tertentu dalam dokumen JSON. Kueri berikut menunjukkan bagaimana JSON_VALUE ekspresi pada kolom json dapat dioptimalkan menggunakan indeks JSON.

  • Pencarian kesetaraan untuk string JSON dalam properti objek:

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

  • Pencarian kesetaraan untuk nomor JSON dalam properti objek setelah mengonversi nilai menjadi jenis data int :

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

  • Pencarian rentang untuk nomor JSON dalam properti objek setelah mengonversi nilai menjadi jenis data int :

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

  • Pencarian rentang untuk nomor JSON dalam properti objek setelah mengonversi nilai menjadi jenis data desimal :

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

Indeks JSON didukung dengan JSON_VALUE predikat, dan operator berikut:

  • Operator perbandingan (=)
  • LIKE predikat (saat ini tidak didukung)
  • IS [NOT] NULL predikat (saat ini tidak didukung)

fungsi JSON_CONTAINS

Fungsi JSON_CONTAINS mendukung pencarian nilai JSON yang mudah dalam dokumen JSON yang dapat menggunakan indeks JSON jika ada di kolom json . Fungsi ini dapat digunakan untuk menguji apakah nilai skalar JSON, objek, atau array terkandung dalam jalur SQL/JSON yang ditentukan dalam dokumen JSON. Nilai pencarian yang ditentukan sebagai jenis skalar SQL dikonversi sesuai aturan konversi jenis SQL/JSON yang ada. Aturan ini didefinisikan di bagian perilaku.

Persyaratan

Kunci pengklusteran diperlukan pada tabel yang berisi kolom JSON. Kesalahan dimunculkan jika kunci pengklusteran tidak ada. Kunci pengklusteran dibatasi hingga 31 kolom dan ukuran maksimum kunci indeks harus kurang dari 128 byte.

Hak akses

Pengguna harus memiliki izin ALTER pada tabel, atau menjadi anggota peran server tetap sysadmin, atau peran database tetap db_ddladmin dan db_owner.

Keterbatasan

Batasan berikut ada untuk pernyataan indeks JSON:

  • Hanya satu indeks JSON yang dapat dibuat pada kolom json dalam tabel.
  • Anda dapat membuat hingga 249 indeks JSON dalam tabel. Membuat lebih dari satu indeks JSON pada kolom JSON tertentu tidak didukung.
  • Indeks JSON tidak dapat dibuat pada kolom json komputasi.
  • Indeks JSON tidak dapat dibuat pada kolom json dalam tampilan, variabel bernilai tabel, atau tabel memori yang dioptimalkan.
  • Indeks JSON hanya dapat dibuat atau diubah secara offline.
  • Jalur JSON tidak dapat tumpang tindih dalam definisi indeks. Misalnya, $a dan $a.b tumpang tindih, dan tidak diizinkan dalam CREATE JSON INDEX pernyataan.
  • Modifikasi jalur memerlukan pembuatan ulang indeks JSON.
  • Indeks JSON tidak didukung dalam petunjuk indeks.
  • Opsi kompresi data tidak didukung.

Contoh

Sebuah. Membuat indeks JSON pada kolom JSON

Contoh berikut membuat tabel bernama docs yang berisi kolom jenis json , content. Contoh kemudian membuat indeks JSON, json_content_index, pada content kolom . Contoh membuat indeks json pada seluruh dokumen JSON atau semua jalur SQL/JSON dalam dokumen JSON.

DROP TABLE IF EXISTS docs;

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

CREATE JSON INDEX json_content_index
    ON docs (content);

Sebuah. Membuat indeks JSON pada kolom JSON dengan jalur tertentu

Contoh berikut membuat tabel bernama docs yang berisi kolom jenis json , content. Contoh kemudian membuat indeks JSON, json_content_index, pada content kolom . Contoh membuat indeks json pada jalur SQL/JSON tertentu dalam dokumen JSON.
Contoh ini juga mengatur indeks FILLFACTOR ke 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);

B. Indeks JSON dengan pengoptimalan pencarian array

Contoh berikut mengembalikan indeks JSON untuk tabel dbo.Customers. Indeks JSON dibuat dengan opsi pengoptimalan pencarian array diaktifkan.

DROP TABLE IF EXISTS dbo.Customers;

CREATE TABLE dbo.Customers
(
    customer_id INT IDENTITY PRIMARY KEY,
    customer_info JSON NOT NULL
);

CREATE JSON INDEX CustomersJsonIndex
    ON dbo.Customers (customer_info) WITH (OPTIMIZE_FOR_ARRAY_SEARCH = ON);

INSERT INTO dbo.Customers (customer_info)
VALUES ('{"name":"customer1", "email": "customer1@example.com", "phone":["123-456-7890", "234-567-8901"]}');

SELECT object_id,
       index_id,
       optimize_for_array_search
FROM sys.json_indexes AS ji
WHERE object_id = OBJECT_ID('dbo.Customers');

Konten terkait

  • Last updated on