Функция JSON_QUERY() в Oracle

В Oracle Database, JSON_QUERY() функцията избира и връща една или повече стойности от JSON данни и връща тези стойности.

Можете да използвате функцията за извличане на фрагменти от JSON документ.

Синтаксис

Синтаксисът е така:

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 ]
  )

Къде:

expr е JSON документът, който искате да направите заявка
JSON_basic_path_expression е SQL/JSON пътят, който искате да върнете от този JSON документ. Функцията използва израза за път, за да оцени expr и намерете една или повече JSON стойности, които съответстват или удовлетворяват израза за пътя. Изразът на пътя трябва да е текстов литерал.
JSON_query_returning_clause определя типа данни и формата на низа от знаци, върнати от функцията.
JSON_query_wrapper_clause контролира дали функцията обвива върнатите стойности в обвивка на масив (квадратни скоби ([] )).
JSON_query_on_error_clause указва стойността, върната при възникване на определени грешки.
JSON_query_on_empty_clause посочва връщаната стойност, ако не бъде намерено съвпадение, когато данните в JSON се оценяват с помощта на израза за SQL/JSON пътя.

Вижте документацията на Oracle за подробно обяснение на незадължителните клаузи.

Пример

Ето пример, за да демонстрирате как JSON_QUERY() функция работи:

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

Резултат:

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

Използването на знака за долар само по себе си връща целия низ от JSON данни.

С обвивка

Можете да използвате WITH WRAPPER клауза за обвиване на резултата в обвивка на масив:

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

Резултат:

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

Трябва да посочите тази клауза, ако изразът за пътя съвпада с една скаларна стойност (стойност, която не е JSON обект или JSON масив) или множество стойности от всякакъв тип.

Например връщането на следната скаларна стойност трябва да се извърши с WITH WRAPPER клауза:

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

Резултат:

[2]

Пропускане на WITH WRAPPER клауза при връщане на скаларна стойност води до връщане на нулева стойност:

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

Резултат:

null

По подразбиране SQLcl и SQL*Plus връщат празно пространство всеки път, когато null възниква в резултат на SQL SELECT изявление.

Можете обаче да използвате SET NULL за да посочите различен низ, който да бъде върнат. Тук посочих, че низът null трябва да бъдат върнати.

С условна обвивка

Като алтернатива можете да използвате WITH CONDITIONAL WRAPPER клауза за включване на обвивката на масива само ако изразът за пътя съвпада с една скаларна стойност или множество стойности от всякакъв тип. Ако изразът на пътя съвпада с един JSON обект или JSON масив, тогава обвивката на масива се пропуска:

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;

Резултат:

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

В този случай само скаларната стойност има приложена обвивка на масива.

Само за да е ясно, ето го с безусловна обвивка:

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;

Резултат:

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

Този път и двата резултата имат приложена обвивка.

Обърнете внимание, че WITH UNCONDITIONAL WRAPPER е еквивалент на WITH WRAPPER .

Обработка на грешки

Има пет клаузи, които можете да използвате, за да посочите какво да върнете, когато възникнат определени видове грешки. Клаузите са:

NULL ON ERROR – Връща нула, когато възникне грешка. Това е по подразбиране.
ERROR ON ERROR – Връща съответната грешка на Oracle, когато възникне грешка.
EMPTY ON ERROR – Посочването на тази клауза е еквивалентно на посочване на EMPTY ARRAY ON ERROR .
EMPTY ARRAY ON ERROR – Връща празен JSON масив ([] ), когато възникне грешка.
EMPTY OBJECT ON ERROR – Връща празен JSON обект ({} ), когато възникне грешка.

Ето един пример:

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;

Резултат:

     r1    r2    r3 
_______ _____ _____ 
null    []    {}

Ето го с ERROR ON ERROR клауза:

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

Резултат:

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

Тези клаузи за грешка са за обработка на следните грешки:

Първият аргумент не е добре оформени JSON данни, използващи строг или слаб синтаксис на JSON.
Не е намерено съвпадение, когато данните в JSON се оценяват с помощта на израза за път на SQL/JSON. Можете да замените поведението за този тип грешка, като посочите JSON_query_on_empty_clause .
Типът данни за връщана стойност не е достатъчно голям, за да задържи низа от връщания символ
Функцията съответства на една скаларна стойност или множество стойности от всякакъв тип и клауза за обвиване не е посочена

Обработка на празни резултати

Можете също да използвате клауза, за да посочите върнатата стойност, ако не бъде намерено съвпадение. Тази клауза ви позволява да посочите различен резултат за този тип грешка от резултата, определен с клаузите за грешка.

Тези клаузи са:

NULL ON EMPTY – Връща нула, когато не е намерено съвпадение.
ERROR ON EMPTY – Връща съответната грешка на Oracle, когато не е намерено съвпадение.
EMPTY ON EMPTY – Посочването на тази клауза е еквивалентно на посочване на EMPTY ARRAY ON EMPTY .
EMPTY ARRAY ON EMPTY – Връща празен JSON масив ([] ), когато не е намерено съвпадение.
EMPTY OBJECT ON EMPTY – Връща празен JSON обект ({} ), когато не е намерено съвпадение.

Пример:

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

Резултат:

[]

Ако пропуснете тази клауза, тогава клаузата за грешка определя стойността, върната, когато не бъде намерено съвпадение.