Applies To
All Users Gen 1 Exadata Cloud at Customer (Oracle Exadata Database Cloud Machine) - Version N/A and later
Oracle Cloud Infrastructure - Database Service - Version N/A and later
Oracle Database Backup Service - Version N/A and later
Oracle Database Cloud Exadata Service - Version N/A and later
Oracle Database Cloud Schema Service - Version N/A and later
Oracle Database Cloud Service - Version N/A and later
Oracle Database Exadata Express Cloud Service - Version N/A and later
Summary
This Document contains Frequently Asked Questions in relation to the use of JSON (JavaScript Object Notation) in the XDB component of the Oracle database.
Details
Q. What is JSON?
A. JSON stands for JavaScript Object Notation. Even though JSON is based on a subset of the JavaScript Programming Language, it's a language-independent data format and like XML its relatively easy for humans to read and write, and easy for software to parse and generate. It is often used for serializing structured data and exchanging it over a network, typically between a server and web applications. Its widely used in web browsers and web servers.
Q. When is JSON fully supported in the Oracle database?
A. Starting in 12.1.0.2, Oracle added support for storing, querying and indexing JavaScript Object Notation (JSON) data to Oracle Database and allows the database to enforce that JSON stored in the Oracle Database conforms to the JSON rules. This feature also allows JSON data to be queried using a PATH based notation and adds new operators that allow JSON PATH based queries to be integrated into SQL operations.
Companies are adopting JSON as a way of storing unstructured and semi-structured data. As the volume of JSON data increases, it becomes necessary to be able to store and query this data in a way that provides similar levels of security, reliability and availability as are provided for relational data. This feature allows information represented as JSON data to be treated inside the Oracle database.
Q. What are some of the similarities between JSON and XML Database (XDB)?
A. The following a similarities:
(i) Both use a simple text format meaning they are both easy to read and understand
(ii) Both be used to exchange data accross different applications.
(iii) Both are case sensitive.
(iv) JSON and XDB can be stored, indexed, and queried queried in the database without the need for a schema that defines the data.
Q. What are some of the differences between JSON and XML Database (XDB)?
A. Some differences include:
(i) JSON has become more common with Web based services specifically with Ajax-enabled application accessing RESTful Web Services. It can be useful in that it can be easily implemented into HTML to accomodate Ajax.
(ii) Different syntax between JSON and XML.
(iii) JSON has no datatype, whereas XML is optimized to use XMLType datatype.
(iv) JSON provides for easier data access and doesn't have as many constraints when accessing data content. XML is more verbose in that it has properties like namespaces and attributes which is more precise in determing further information about the data content.
(v) The order of the members of a JavaScript object literal is insignificant. In general, order matters within an XML document.
Q. Explain the concepts of JSON Path Language?
A. The entire document is referenced by . All JSON path expressions start with a '' symbol. Key names are separated by a '.' (period). A JSON path expression can address four items:
(i) The entire object
(ii) A scalar value
(iii) An array
(iv) A specific object
These concepts can be most easily shown via a JSON object:
{ "PONumber" : 1600,
"Reference" : "ABULL-20140421",
"Requestor" : "Alexis Bull",
"User" : "ABULL",
"CostCenter" : "A50",
"ShippingInstructions" : { "name" : "Alexis Bull",
"Address": { "street" : "200 Sporting Green",
"city" : "South San Francisco",
"state" : "CA",
"zipCode" : 99236,
"country" : "United States of America" },
"Phone" : [ { "type" : "Office", "number" : "909-555-7307" },
{ "type" : "Mobile", "number" : "415-555-1234" } ] },
"Special Instructions" : null,
"AllowPartialShipment" : false,
"LineItems" : [ { "ItemNumber" : 1,
"Part" : { "Description" : "One Magic Christmas",
"UnitPrice" : 19.95,
"UPCCode" : 13131092899 },
"Quantity" : 9.0 },
{ "ItemNumber" : 2,
"Part" : { "Description" : "Lethal Weapon",
"UnitPrice" : 19.95,
"UPCCode" : 85391628927 },
"Quantity" : 5.0 } ] }
JSON Path Expression Type Contents
$.Reference String "ABULL-20120421"
$.ShippingInstructions.Address.zipCode Number 99236
$.ShippingInstructions.Address Object { "street": "200 Sporting Green", "city": "South San Francisco", "state": "CA", "zipCode": 99236, "country": "United States of America" }
$LineItems Array [ { "ItemNumber" : 1, "Part" : { "Description" : "One Magic Christmas", "UnitPrice" : 19.95, "UPCCode" : 13131092899 }, "Quantity" : 9 },
{ "ItemNumber" : 2, "Part" : { "Description" : "Lethal Weapon", "UnitPrice" : 19.95, "UPCCode" : 85391628927 }, "Quantity" : 5 } ]
Q. How can you load a JSON document into the database?
A. There are several ways:
(i) Create a relational table with a JSON column, and add an is json check constraint to ensure that the column contains only well-formed JSON data. Then, you can insert the JSON document itself:
SQL> CREATE TABLE j_purchaseorder
2 (id RAW (16) NOT NULL,
3 date_loaded TIMESTAMP WITH TIME ZONE,
4 po_document CLOB
5 CONSTRAINT ensure_json CHECK (po_document IS JSON));
Table created.
SQL> INSERT INTO j_purchaseorder
2 VALUES
3 (SYS_GUID(),
4 SYSTIMESTAMP,
5 '{"PONumber" : 1600,
6 "Reference" : "ABULL-20140421",
7 "Requestor" : "Alexis Bull",
8 "User" : "ABULL",
9 "CostCenter" : "A50",
10 "ShippingInstructions" : {"name" : "Alexis Bull",
...
18 "Special Instructions" : null,
19 "AllowPartialShipment" : false,
20 "LineItems" : [{"ItemNumber" : 1,
...
29 "Quantity" : 5.0}]}');
1 row created.
SQL> COMMIT;
Commit complete.
(ii) You can load JSON dump file into the database which is created from a typical NOSQL class of database using External Tables as shown in the below example. It should be noted that versions prior to 21c, there is no dedicated JSON data type. It should be noted, there is no dedicated JSON data type. JSON documents are stored in the database using standard Oracle data types such as VARCHAR2, RAW, CLOB and BLOB. In order to ensure that the content of the column is valid JSON, a new constraint IS JSON, is provided that can be applied to a column. This constraint returns TRUE if the content of the column is well formatted JSON and FALSE otherwise.
SQL> CREATE OR REPLACE DIRECTORY order_entry_dir AS '<ORACLE_HOME>/demo/schema/order_entry';
Directory created.
SQL> CREATE OR REPLACE DIRECTORY loader_output_dir AS '/tmp';
Directory created.
SQL> CREATE TABLE DUMP_FILE_CONTENTS(
2 json_document CLOB
3 )
4 ORGANIZATION EXTERNAL
5 ( TYPE ORACLE_LOADER
6 DEFAULT DIRECTORY order_entry_dir
7 ACCESS PARAMETERS
8 ( RECORDS DELIMITED BY 0x'0A'
9 BADFILE loader_output_dir: 'JSON_DUMPFILE_CONTENTS.bad'
10 LOGFILE loader_output_dir: 'JSON_DUMPFILE_CONTENTS.log'
11 FIELDS
12 ( json_document CHAR(5000) ))
13 LOCATION
14 ( order_entry_dir:'PurchaseOrders.dmp' )
15 )
16 PARALLEL
17 REJECT LIMIT UNLIMITED;
Table created.
SQL> INSERT INTO j_purchaseorder
2 SELECT SYS_GUID(), SYSTIMESTAMP, json_document
3 FROM dump_file_contents
4 WHERE json_document IS JSON;
10000 rows created.
SQL> COMMIT;
Commit complete.
(iii) Starting with 21c version, you can use a dedicated JSON data type. Please refer to the following documentation:
Oracle® Database Learning Database New Features Release 21c
2 Application Development
JSON Document Store
https://docs.oracle.com/en/database/oracle/oracle-database/21/nfcon/application-development.html#GUID-A44ED5C3-5419-49D5-B5D9-263B53F51C4D
Q. How can you query JSON data?
A. There are several ways to access JSON data.
(i) JSON Simple Dot-Notation (SDN) which returns string "1600".
SQL> SELECT po.po_document.PONumber FROM json.j_purchaseorder po;
PONUMBER
1600
(ii) JSON_VALUE operator can only extract scalar values from an JSON document using JSON Path expressions and to filter a result set based on the content of a JSON document. The example below returns string "1600".
SQL> SELECT json_value(po_document, '$.PONumber') FROM json.j_purchaseorder;
JSON_VALUE(PO_DOCUMENT,'$.PONUMBER')
1600
(iii) JSON_QUERY operator can return only an object or an array. The example below returns the JSON object of ShippingInstructions which is delimited by curly braces '{' and '}'.
SQL> SELECT json_query(po_document, '$.ShippingInstructions') FROM json.j_purchaseorder;
JSON_QUERY(PO_DOCUMENT,'$.SHIPPINGINSTRUCTIONS')
{"name":"Alexis Bull","Address":{"street":"200 Sporting Green","city":"South San
Francisco","state":"CA","zipCode":99236,"country":"United States of America"},"
Phone":[{"type":"Office","number":"909-555-7307"},{"type":"Mobile","number":"415
-555-1234"}]}
SQL> -- Pretty-print
SQL> SELECT json_query(po_document, '$.ShippingInstructions' RETURNING VARCHAR2(450) PRETTY)
2 FROM json.j_purchaseorder;
JSON_QUERY(PO_DOCUMENT,'$.SHIPPINGINSTRUCTIONS'RETURNINGVARCHAR2(450)PRETTY)
{
"name" : "Alexis Bull",
"Address" :
{
"street" : "200 Sporting Green",
"city" : "South San Francisco",
"state" : "CA",
"zipCode" : 99236,
"country" : "United States of America"
},
"Phone" :
{ "type" : "Office", "number" : "909-555-7307" }, { "type" : "Mobile", "number" : "415-555-1234" }
}
(iv) JSON_TABLE is used in the FROM clause of a SQL statement. It enables the creation of an inline relational view of JSON content. The JSON_TABLE operator uses a set of JSON path expressions to map content from a JSON document into columns in the view. As seen below, it shows scalar values PO_NUMBER and REFERENCE. It shows to expose the contents of an array as a set of rows the array must be processed using the NESTED PATH syntax. When a JSON_TABLE operator contains a NESTED_PATH clause it will output one row for each member of the array (namely Zipcode and Country referenced by the deepest NESTED_PATH clause.
SQL> SELECT d.*
2 FROM json.j_purchaseorder p,
3 JSON_TABLE( p.PO_DOCUMENT , '$'
4 COLUMNS(
5 PO_NUMBER NUMBER(10) PATH '$.PONumber',
6 REFERENCE VARCHAR2(30 CHAR) PATH '$.Reference',
7 NESTED PATH '$.ShippingInstructions.Address'
8 columns(
9 ZIPCODE NUMBER(16) PATH '$.zipCode',
10 COUNTRY VARCHAR2(32 CHAR) PATH '$.country')
11 )) D
12 WHERE po_number = 1600;
PO_NUMBER REFERENCE ZIPCODE COUNTRY
1600 ABULL-20140421 99236 United States of America
Q. Is there a way to search an entire JSON document?
A. Document-level indexing is based on Oracle's full-text indexing technology. Currently the JSON document index is capable of optimizing JSON_EXISTS operations and certain classes of JSON_VALUE operations. This can be done using the following steps:
(i) Create the full Oracle Text index using the syntax:
SQL> CREATE INDEX po_document_index
2 ON j_purchaseorder(po_document)
3 INDEXTYPE IS CTXSYS.CONTEXT
4 PARAMETERS ('SECTION GROUP CTXSYS.JSON_SECTION_GROUP SYNC (ON COMMIT)');
Index created
(ii) Performs a query based on the city key and gives the total cost:
SQL> SELECT SUM(quantity * unitprice) TOTAL_COST
2 FROM json.j_purchaseorder,
3 JSON_TABLE(po_document , '$.LineItems[*]'
4 COLUMNS(
5 QUANTITY NUMBER(12,4) PATH '$.Quantity',
6 UNITPRICE NUMBER(14,2) PATH '$.Part.UnitPrice')
7 )
8 WHERE JSON_VALUE(po_document ,'$.ShippingInstructions.Address.city') = 'South San Francisco';
TOTAL_COST
279.3
SQL> -- The JSON_VALUE operation is optimized by the use of the PO_DOCUMENT_INDEX text index
SQL> set autotrace traceonly explain
SQL> /
Execution Plan
Plan hash value: 3681081768
| Id | Operation | Name | Rows | Bytes | Cost (%CPU)| Time |
| 0 | SELECT STATEMENT | | 1 | 2018 | 34 (0)| 00:00:01 |
| 1 | SORT AGGREGATE | | 1 | 2018 | | |
| 2 | NESTED LOOPS | | 1 | 2018 | 34 (0)| 00:00:01 |
|* 3 | TABLE ACCESS BY INDEX ROWID| J_PURCHASEORDER | 1 | 2014 | 5 (0)| 00:00:01 |
|* 4 | DOMAIN INDEX | PO_DOCUMENT_INDEX | | | 4 (0)| 00:00:01 |
| 5 | JSONTABLE EVALUATION | | | | | |
Predicate Information (identified by operation id):
3 - filter(JSON_VALUE("PO_DOCUMENT" FORMAT JSON , '$.ShippingInstructions.Address.city'
RETURNING VARCHAR2(4000) NULL ON ERROR)='South San Francisco')
4 - access("CTXSYS"."CONTAINS"("J_PURCHASEORDER"."PO_DOCUMENT",'{South San Francisco}
INPATH(/ShippingInstructions/Address/city)')>0)
(iii) Performs a full-text query using the sql condition JSON_TEXTCONTAINS to find purchase-order documents that contain the keyword "Magic" in any of the line-item part desciptions.
SQL> SELECT po_document
2 FROM json.j_purchaseorder
3 WHERE JSON_TEXTCONTAINS(po_document, '$.LineItems.Part.Description', 'Magic');
PO_DOCUMENT
{"PONumber":1600,"Reference":"ABULL-20140421","Requestor":"Alexis Bull","User":"
...
ions":null,"AllowPartialShipment":true,"LineItems":[{"ItemNumber":1,"Part":{"Des
cription":"One Magic Christmas" ,"UnitPrice":19.95,"UPCCode":13131092899},"Quanti
ty":9.0},{"ItemNumber":2,"Part":{"Description":"Lethal Weapon","UnitPrice":19.95
,"UPCCode":85391628927},"Quantity":5.0}]}
SQL> set autotrace traceonly explain
SQL> /
Execution Plan
Plan hash value: 1033699331
| Id | Operation | Name | Rows | Bytes | Cost (%CPU)| Time |
| 0 | SELECT STATEMENT | | 1 | 2014 | 5 (0)| 00:00:01 |
| 1 | TABLE ACCESS BY INDEX ROWID| J_PURCHASEORDER | 1 | 2014 | 5 (0)| 00:00:01 |
|* 2 | DOMAIN INDEX | PO_DOCUMENT_INDEX | | | 4 (0)| 00:00:01 |
Predicate Information (identified by operation id):
2 - access("CTXSYS"."CONTAINS"("J_PURCHASEORDER"."PO_DOCUMENT",'{Magic}
INPATH(/LineItems/Part/Description)')>0)
Q. Is it possible to use JSON function like JSON_TABLE on XML data?
A. It is not supported to use JSON functions over XML data. You will need to convert your XML data to JSON or use XML XQuery operators.
Q. When are JSON generation functions available for use?
A. SQL/JSON functions JSON_OBJECT, JSON_ARRAY, JSON_OBJECTAGG, and JSON_ARRAYAGG are available from 12.2.0.1 onwards. Please reference URL for further details:
Q. Is there further documentation about JSON features and functionality?
A. Yes, the following are good references to JSON:
12.1.0.2 JSON in Oracle db: http://docs.oracle.com/database/121/ADXDB/json.htm#ADXDB6247
An Introduction to JSON: http://www.oracle.com/technetwork/articles/entarch/introduction-json-097942.html
SQL/JSON standard: http://www.json.org and http://www.ecma-international.org
DDLs and queries used in the examples shown in this note are in the attached JSONDemo.zip file.
Q. What is there Information about best practises, known issues, install verification and demo scripts, documentation references and JSON blogs.
A. Please refer to the following document:
(Doc ID KB130824) Primary Note for Oracle JSON DB
Q. What patches need to be installed to have the latest set of JSON Database fixes?
A. Please refer to the following document:
(Doc ID KB98717) JSON Database Patch Bundle Details
Q. Where can I find Information about specific 19c JSON issues?
A. Please refer to the following documents:
(Doc ID KB99151) Enabling JSON Check Constraints Takes Forever When Having More Than 2 Mill Rows
(Doc ID KB123046) ORA-40474: INVALID UTF-8 BYTE SEQUENCE IN JSON DATA
Q. Where is there information about New Features for JSON on 18c and 19c?
A. You can access New Features via the following:
18c: (Doc ID KB112366) New Features in 18.1 JSON Database