Fungsi JSON_QUERY() di Oracle

Di Oracle Database, JSON_QUERY() fungsi memilih dan mengembalikan satu atau lebih nilai dari data JSON dan mengembalikan nilai tersebut.

Anda dapat menggunakan fungsi tersebut untuk mengambil fragmen dokumen JSON.

Sintaks

Sintaksnya seperti ini:

JSON_QUERY
  ( expr [ FORMAT JSON ], JSON_basic_path_expression
    [ JSON_query_returning_clause ] [ JSON_query_wrapper_clause ]
    [ JSON_query_on_error_clause ] [ JSON_query_on_empty_clause ]
  )

Dimana:

expr adalah dokumen JSON yang ingin Anda kueri
JSON_basic_path_expression adalah jalur SQL/JSON yang ingin Anda kembalikan dari dokumen JSON itu. Fungsi menggunakan ekspresi jalur untuk mengevaluasi expr dan temukan satu atau beberapa nilai JSON yang cocok, atau memenuhi, ekspresi jalur. Ekspresi jalur harus berupa teks literal.
JSON_query_returning_clause menentukan tipe data dan format string karakter yang dikembalikan oleh fungsi.
JSON_query_wrapper_clause mengontrol apakah fungsi membungkus nilai yang dikembalikan dalam pembungkus array (tanda kurung siku ([] )).
JSON_query_on_error_clause menentukan nilai yang dikembalikan ketika kesalahan tertentu terjadi.
JSON_query_on_empty_clause menentukan nilai yang ditampilkan jika tidak ada kecocokan yang ditemukan saat data JSON dievaluasi menggunakan ekspresi jalur SQL/JSON.

Lihat dokumentasi Oracle untuk penjelasan rinci tentang klausa opsional.

Contoh

Berikut adalah contoh untuk mendemonstrasikan bagaimana JSON_QUERY() fungsi berfungsi:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$')
FROM DUAL;

Hasil:

{"a":1,"b":2,"c":3}

Menggunakan tanda dolar dengan sendirinya mengembalikan seluruh string data JSON.

Dengan Pembungkus

Anda dapat menggunakan WITH WRAPPER klausa untuk membungkus hasil dalam pembungkus array:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH WRAPPER)
FROM DUAL;

Hasil:

[{"a":1,"b":2,"c":3}]

Anda harus menentukan klausa ini jika ekspresi jalur cocok dengan nilai skalar tunggal (nilai yang bukan objek JSON atau larik JSON) atau beberapa nilai jenis apa pun.

Misalnya, mengembalikan nilai skalar berikut harus dilakukan dengan WITH WRAPPER klausa:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH WRAPPER)
FROM DUAL;

Hasil:

[2]

Menghilangkan WITH WRAPPER klausa saat mengembalikan nilai skalar menghasilkan nilai nol yang dikembalikan:

SET NULL 'null';
SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$.b')
FROM DUAL;

Hasil:

null

Secara default, SQLcl dan SQL*Plus mengembalikan ruang kosong setiap kali null terjadi sebagai akibat dari SQL SELECT penyataan.

Namun, Anda dapat menggunakan SET NULL untuk menentukan string berbeda yang akan dikembalikan. Di sini saya menetapkan bahwa string null harus dikembalikan.

Dengan Pembungkus Bersyarat

Atau, Anda dapat menggunakan WITH CONDITIONAL WRAPPER klausa untuk menyertakan pembungkus array hanya jika ekspresi jalur cocok dengan nilai skalar tunggal atau beberapa nilai dari jenis apa pun. Jika ekspresi jalur cocok dengan objek JSON tunggal atau larik JSON, maka pembungkus larik dihilangkan:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH CONDITIONAL WRAPPER) AS "r1",
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH CONDITIONAL WRAPPER) AS "r2"
FROM DUAL;

Hasil:

                    r1     r2 
______________________ ______ 
{"a":1,"b":2,"c":3}    [2]

Dalam hal ini, hanya nilai skalar yang menerapkan pembungkus array.

Untuk memperjelas, ini dia dengan pembungkus tanpa syarat:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH UNCONDITIONAL WRAPPER) AS "r1",
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH UNCONDITIONAL WRAPPER) AS "r2"
FROM DUAL;

Hasil:

                      r1     r2 
________________________ ______ 
[{"a":1,"b":2,"c":3}]    [2]

Kali ini kedua hasil menerapkan pembungkus.

Perhatikan bahwa WITH UNCONDITIONAL WRAPPER setara dengan WITH WRAPPER .

Penanganan Kesalahan

Ada lima klausa yang dapat Anda gunakan untuk menentukan apa yang harus dikembalikan setiap kali jenis kesalahan tertentu terjadi. Klausanya adalah:

NULL ON ERROR – Mengembalikan null ketika terjadi kesalahan. Ini adalah default.
ERROR ON ERROR – Mengembalikan kesalahan Oracle yang sesuai saat terjadi kesalahan.
EMPTY ON ERROR – Menentukan klausa ini sama dengan menetapkan EMPTY ARRAY ON ERROR .
EMPTY ARRAY ON ERROR – Mengembalikan array JSON kosong ([] ) saat terjadi kesalahan.
EMPTY OBJECT ON ERROR – Mengembalikan objek JSON kosong ({} ) saat terjadi kesalahan.

Ini contohnya:

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' NULL ON ERROR) AS "r1",
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY ON ERROR) AS "r2",
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY OBJECT ON ERROR) AS "r3"
FROM DUAL;

Hasil:

     r1    r2    r3 
_______ _____ _____ 
null    []    {}

Ini dia dengan ERROR ON ERROR klausa:

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' ERROR ON ERROR)
FROM DUAL;

Hasil:

Error report -
ORA-40462: JSON_VALUE evaluated to no value

Klausa kesalahan ini untuk menangani kesalahan berikut:

Argumen pertama bukanlah data JSON yang terbentuk dengan baik menggunakan sintaks JSON yang ketat atau longgar
Tidak ada kecocokan yang ditemukan saat data JSON dievaluasi menggunakan ekspresi jalur SQL/JSON. Anda dapat mengganti perilaku untuk jenis kesalahan ini dengan menentukan JSON_query_on_empty_clause .
Tipe data nilai kembalian tidak cukup besar untuk menampung string karakter kembali
Fungsi ini cocok dengan satu nilai skalar atau, beberapa nilai dari jenis apa pun, dan klausa pembungkus tidak ditentukan

Menangani Hasil Kosong

Anda juga dapat menggunakan klausa untuk menentukan nilai yang dikembalikan jika tidak ditemukan kecocokan. Klausa ini memungkinkan Anda untuk menentukan hasil yang berbeda untuk jenis kesalahan ini daripada hasil yang ditentukan dengan klausa kesalahan.

Klausa tersebut adalah:

NULL ON EMPTY – Mengembalikan null saat tidak ditemukan kecocokan.
ERROR ON EMPTY – Mengembalikan kesalahan Oracle yang sesuai saat tidak ditemukan kecocokan.
EMPTY ON EMPTY – Menentukan klausa ini sama dengan menetapkan EMPTY ARRAY ON EMPTY .
EMPTY ARRAY ON EMPTY – Mengembalikan array JSON kosong ([] ) ketika tidak ada kecocokan yang ditemukan.
EMPTY OBJECT ON EMPTY – Mengembalikan objek JSON kosong ({} ) ketika tidak ada kecocokan yang ditemukan.

Contoh:

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY ON EMPTY)
FROM DUAL;

Hasil:

[]

Jika Anda menghilangkan klausa ini, maka klausa kesalahan menentukan nilai yang dikembalikan ketika tidak ada kecocokan yang ditemukan.