Jenis data JSON

Berlaku untuk: Database SQL SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed Instancedi Microsoft Fabric

Tipe data json menyimpan dokumen JSON dalam format biner.

Tipe json menyediakan penyimpanan dokumen JSON dengan fidelitas tinggi yang dioptimalkan untuk kueri dan manipulasi. Ini menawarkan keuntungan berikut dibandingkan menyimpan data JSON sebagai varchar atau nvarchar:

  • Bacaan yang lebih efisien, karena dokumen sudah diurai.
  • Penulisan lebih efisien, karena kueri dapat memperbarui nilai individual tanpa mengakses seluruh dokumen.
  • Penyimpanan lebih efisien, dioptimalkan untuk kompresi.
  • Tidak ada perubahan kompatibilitas dengan kode yang ada.

Tipe json secara internal menyimpan string menggunakan pengkodean UTF-8 (Latin1_General_100_BIN2_UTF8). Tipe data lain disimpan sebagai tipe data asli. Perilaku ini cocok dengan spesifikasi JSON.

Untuk informasi selengkapnya tentang mengkueri data JSON, lihat data JSON di SQL Server.

Sintaksis sampel

Sintaks penggunaan untuk jenis json mirip dengan semua jenis data SQL Server lainnya dalam tabel.

column_name JSON [ NOT NULL | NULL ] [CHECK ( constraint_expression ) ] [ DEFAULT ( default_expression ) ]

Gunakan tipe data json dalam definisi kolom yang terdapat dalam CREATE TABLE pernyataan. Contohnya:

CREATE TABLE Orders
(
    order_id INT,
    order_details JSON NOT NULL
);

Tentukan batasan sebagai bagian dari definisi kolom. Contohnya:

CREATE TABLE Orders
(
    order_id INT,
    order_details JSON NOT NULL
        CHECK (JSON_PATH_EXISTS(order_details, '$.basket') = 1)
);

Ketersediaan fitur

Dukungan untuk fungsi JSON diperkenalkan di SQL Server 2016 (13.x). Tipe data json bawaan tersedia di Azure SQL Database, Azure SQL Managed Instance, dan SQL Server 2025 (17.x).

Untuk informasi lebih lanjut tentang dukungan JSON di SQL Server 2025 (17.x), lihat Kapabilitas Key JSON di SQL Server 2025.

Jenis data json tersedia di bawah semua tingkat kompatibilitas database.

Note

Tipe data json dan indeks JSON umumnya tersedia di SQL Server 2025 (17.x), Azure SQL Database, Azure SQL Managed Instance (dengan kebijakan pembaruan tanggal SQL Server 2025 atau Always-up-to, dan database SQL di Microsoft Fabric.

Metode modifikasi

Jenis data json mendukung metode .modify Gunakan modify untuk mengubah dokumen JSON yang disimpan dalam kolom. Metode ini modify mencakup optimasi yang melakukan modifikasi data secara langsung bila memungkinkan. Ini adalah cara yang disarankan untuk memodifikasi dokumen JSON dalam kolom json .

Untuk string JSON, jika nilai baru sama panjang atau lebih pendek dari nilai yang ada, metode dapat memodifikasi data yang ada.

Untuk angka JSON, jika nilai baru adalah tipe yang sama atau sesuai dengan rentang nilai yang ada, metode dapat memodifikasi data yang ada.

DROP TABLE IF EXISTS JsonTable;

CREATE TABLE JsonTable
(
    id INT PRIMARY KEY,
    d JSON
);

INSERT INTO JsonTable
(
    id,
    d
)
VALUES (1, '{"a":1, "b":"abc", "c":true}');

UPDATE JsonTable
SET d.modify('$.a', 14859)
WHERE id = 1;

UPDATE JsonTable
SET d.modify('$.b', 'def')
WHERE id = 1;

Data yang valid

Input ke jenis data json harus berupa objek JSON atau array JSON. Skalar, boolean, dan NULL nilai tidak didukung. Jenis data JSON sesuai dengan IETF RFC 4627 yang hanya memungkinkan objek atau array JSON.

Gunakan fungsi ISJSON untuk menguji apakah sebuah string mengandung JSON yang valid. Tanpa batasan tipe, ISJSON hanya menerima objek atau array JSON di tingkat atas, sama seperti tipe data json . Batasan VALUE tipe menerima nilai JSON apa pun di tingkat atas, termasuk skalar, sesuai dengan IETF RFC 8259. Kendala ARRAY, OBJECT, dan SCALAR tipe hanya menerima tipe tersebut.

Contohnya:

DECLARE @true AS JSON = 'true'; -- invalid
DECLARE @false AS JSON = 'false'; -- invalid
DECLARE @number AS JSON = '1234.56'; -- invalid
DECLARE @string AS JSON = '"contoso"'; -- invalid
DECLARE @null AS JSON = 'null'; -- invalid

DECLARE @null AS JSON = NULL; -- valid
DECLARE @object AS JSON = '{}'; -- valid
DECLARE @array AS JSON = '[]'; -- valid

Dukungan fungsi

Semua fungsi JSON mendukung tipe data json tanpa memerlukan perubahan kode.

Untuk daftar lengkap fungsi JSON, lihat Fungsi JSON.

Indexes

Kolom json dapat berupa kolom yang disertakan dalam definisi indeks, atau muncul dalam WHERE klausa indeks yang terfilter. Kolom json tidak dapat digunakan sebagai kolom kunci dalam indeks standar.

Untuk informasi selengkapnya, lihat CREATE INDEX .

Di Azure SQL Database, Azure SQL Managed Instance, SQL Server 2025 (17.x), dan database SQL di Microsoft Fabric, Anda dapat membuat indeks JSON untuk mengoptimalkan kueri yang mengakses nilai dalam dokumen JSON.

Untuk informasi selengkapnya, lihat CREATE JSON INDEX .

Conversion

Konversi dari json ke char, nchar, varchar, dan nvarchar harus eksplisit. Gunakan CAST atau CONVERT.

Konversi dari char, nchar, varchar, nvarchar, dan vektor ke json dapat bersifat implisit atau eksplisit. Konversi dari json ke vektor juga dapat bersifat implisit atau eksplisit.

Konversi antara json dan semua jenis data lainnya tidak diperbolehkan.

Nilai yang Anda konversi menjadi json harus berupa objek JSON atau array JSON. Skalar JSON, seperti 1, "abc", true, atau null, menyebabkan kesalahan 13609. String kosong juga menyebabkan error 13609. Jika sebuah objek memiliki kunci duplikat, json mempertahankan nilai pertama dan membuang nilai lainnya. Tidak ada kesalahan yang terjadi.

Konversi dari tipe json ke string mengembalikan teks JSON tanpa spasi putih yang tidak signifikan. Jika panjang target terlalu pendek untuk teks JSON, terjadi kesalahan 13639. Nilainya tidak terpotong.

Jenis data json tidak dapat digunakan dengan jenis sql_variant atau ditetapkan ke variabel atau kolom sql_variant . Pembatasan ini mirip dengan tipe data berbasis CLR varchar(max), varbinary(max), nvarchar(max).

Anda dapat mengonversi kolom yang ada seperti varchar(max) ke json menggunakan ALTER TABLE. Mirip dengan jenis data xml , Anda tidak dapat mengonversi kolom json ke salah satu string atau jenis biner menggunakan ALTER TABLE.

Untuk informasi selengkapnya, lihat Konversi jenis data (Mesin Database).

Presisi numerik

Saat Anda mengonversi ke json dari char, nchar, varchar, atau nvarchar, teks JSON yang berisi nomor JSON dapat dibulatkan berdasarkan format angka.

Jika Anda perlu mempertahankan presisi, tentukan angka JSON sebagai nilai desimal. Demikian pula, jika Anda perlu mempertahankan representasi tekstual dokumen JSON, simpan dokumen JSON sebagai tipe data string karakter.

Compatibility

Anda dapat menggunakan tipe data json sebagai parameter atau tipe return dalam fungsi yang ditentukan pengguna, atau sebagai parameter dari prosedur tersimpan. Jenis json kompatibel dengan pemicu dan tampilan.

Saat ini, format native alat bcp mewakili data json sebagai varchar atau nvarchar. Anda harus menentukan file format untuk menunjuk kolom json .

Anda tidak dapat membuat tipe alias untuk tipe data json dengan CREATE TYPE. Perilaku ini sama dengan jenis data xml .

Menggunakan SELECT ... INTO dengan jenis data json membuat tabel dengan jenis json .

Limitations

CAST CONVERT dan mengembalikan tipe data JSON sesuai harapan.

Batasan driver

Prosedur tersimpan sistem sp_describe_first_result_set mengembalikan tipe data json dengan benar jika driver mendukung JSONSUPPORT ekstensi fitur TDS. Driver yang tidak mendukung ekstensi ini akan melihat varchar atau nvarchar sebagai gantinya.

SqlClient (>= 6.0) dan JDBC (>= 13.2.0) mendukung JSONSUPPORT. Sebagai contoh, versi terbaru SQL Server Management Studio (SSMS) menggunakan driver SqlClient terbaru dan melaporkan tipe json dengan benar dalam metadata set hasil.

  • Tanpa JSONSUPPORT, TDS >= 7.4 (dengan UTF-8) melaporkan varchar(max) dengan Latin1_General_100_BIN2_UTF8.
  • Tanpa JSONSUPPORT, TDS < 7.4 melaporkan nvarchar(max) dengan kolasi basis data.

Batasan ukuran

Batas ukuran data JSON dalam penyimpanan:

Bidang Batasan
Ukuran jenis data JSON (biner) Hingga 2 GB
Jumlah kunci unik Hingga 32.000
Per ukuran string kunci 7.998 byte
Ukuran nilai per string 536.870.911 byte
Jumlah properti dalam satu objek Hingga 65.535
Jumlah elemen dalam satu array Hingga 65.535
Jumlah tingkat berlapis dalam dokumen JSON 128

Konten terkait

  • Terakhir diperbarui pada