17.7 ORACLE_BIGDATA Accessing JSON Documents File Type

See how to use a native JSON reader format (jsondoc) for documents stored in object storage or local directories.

Parent topic: ORACLE_BIGDATA Access Driver

17.7.1 Overview of JSON Document Support

The ORACLE_BIGDATA Access Driver supports the jsondoc native JSON reader format.

The ORACLE_BIGDATA Access Driver support for jsondoc enables seamless interaction with JSON documents stored in object storage or local directories. The JSON reader is designed to parse and query JSON data in various structures, including the following:

  • Line-delimited JSON documents
  • JSON arrays (with optional path specifications for nested arrays)
  • JSON documents with extended JSON (EJSON) annotations for specialized data types

This new capability provides the flexibility to handle complex JSON structures, and tp leverage Oracle Database's powerful JSON features for querying and analysis.

Parent topic: ORACLE_BIGDATA Accessing JSON Documents File Type

17.7.2 Access Parameters for JSON Document

Oracle supports ORACLE_BIGDATA access parameters that define the jsondoc file format and are used in the ACCESS PARAMETERS clause of the CREATE TABLE statement:

Table 17-8 JSON Document Access Parameters

Parameter Description Mandatory

com.oracle.bigdata.fileformat

Calls the new JSON Reader capabilities

Value: jsondoc

Yes

com.oracle.bigdata.json.ejson

Specifies whether to enable extended JSON

Valid values: true, false

Default: true

Optional

com.oracle.bigdata.json.path

A valid JSON path expression that defines the location from which ORACLE_BIGDATA can load documents.

Default: Read from the root of the document $.

Yes

Parent topic: ORACLE_BIGDATA Accessing JSON Documents File Type

17.7.3 Examples of JSONDOC Usage

The following examples demonstrate how to access JSON documents using ORACLE_BIGDATA with the jsondoc file type.

Parent topic: ORACLE_BIGDATA Accessing JSON Documents File Type

17.7.3.1 Querying Line-Delimited JSON Documents

The following is an example of a JSON file containing multiple line-delimited JSON documents, and the SQL statement using this file.

Example 17-26 Querying Line-Delimited JSON Documents

File: fruit.json

{"name": "apple", "count": 20} {"name": "orange", "count": 42} {"name": "pear", "count": 10}

SQL Statement: 

CREATE TABLE fruit (data JSON)

ORGANIZATION EXTERNAL

(TYPE ORACLE_BIGDATA ACCESS PARAMETERS

( com.oracle.bigdata.fileformat = jsondoc

   com.oracle.bigdata.credential.name = 'OCI_CRED' )

LOCATION ('https://<objectstorage-location>/fruit.json'));



SELECT f.data."name", f.data."count" FROM fruit f;

name            count
------------------------------
"apple"         20
"orange"        42
"pear"          10

Parent topic: Examples of JSONDOC Usage

17.7.3.2 Querying JSON Arrays

The following is an example of a JSON file containing a single array of JSON objects, and the SQL statement using this file.

Example 17-27 Querying JSON Arrays

File: fruit-array.json

[
   {
      "name" : "apple",
      "count": 20
   },
   {
      "name" : "orange",
      "count": 42
   },
   {
      "name" : "pear",
      "count": 10
   }
]

SQL Statement: 

CREATE TABLE fruit (data JSON) ORGANIZATION EXTERNAL (
  TYPE ORACLE_BIGDATA
  DEFAULT DIRECTORY default_dir
ACCESS PARAMETERS (
    com.oracle.bigdata.fileformat = jsondoc
    com.oracle.bigdata.json.path = $.[*]
    com.oracle.bigdata.credential.name = OCI_CRED
     )
  location ('https://<objectstorage-location>/fruit-array.json')
);
 
SQL> SELECT f.data."name", f.data."count"
     FROM fruit f;  
 
name            count
------------------------------
"apple"         20
"orange"        42
"pear"          10

Parent topic: Examples of JSONDOC Usage

17.7.3.3 Object wrapped JSON Arrays

The following is an example of JSON documents wrapped in an outer JSON document.

Example 17-28 Object wrapped JSON Arrays

To use this example, you provide a path (using com.oracle.bigdata.json.path) to the data that you want to load. The path must lead to an array. The rows are mapped as in the previous example.

Example data file: fruit-array.json

{
  "last_updated": 1434054678,
  "ttl": 0,
  "version": "1.0",
  "fruit": [
    {"name" : "apple", "count": 20 },
    {"name" : "orange", "count": 42 },
    {"name" : "pear", "count": 10 }
  ]
}

Save this file in the compatible object storage location for your configuration, and then create a table using the data:

CREATE TABLE fruit (data JSON) ORGANIZATION EXTERNAL (
  TYPE ORACLE_BIGDATA
  DEFAULT DIRECTORY default_dir
  ACCESS PARAMETERS
  (
    com.oracle.bigdata.fileformat = jsondoc
    com.oracle.bigdata.json.path = $.fruit[*]
    com.oracle.bigdata.credential.name = OCI_CRED
     )
  location ('https://objectstorage-location/fruit-wrapped.json')
);

A query statement should produce results as follows:


SELECT f.data."name", f.data."count"
     FROM fruit f;
 
name            count
------------------------------
"apple"        20
"orange"       42
"pear"         10

Parent topic: Examples of JSONDOC Usage

17.7.3.4 Extended JSON (EJSON) Support

The SQL type JSON is capable of representing extended JSON types such as TIMESTAMP, DOUBLE, FLOAT, and RAW.

Example 17-29 Extended JSON (EJSON) Support

. The JSON text can represent extended JSON types by using the extended JSON format. When set, these ejson annotations will be automatically converted to the corresponding types.

File: fruit-extended.json

{"name" : "apple", "count": 20, "modified":{"$date":"2020-06-29T11:53:05.439Z"} }
{"name" : "orange", "count": 42 }
{"name" : "pear", "count": 10 }

SQL Statement: 

CREATE TABLE fruit (data JSON) ORGANIZATION EXTERNAL (
  TYPE ORACLE_BIGDATA
  DEFAULT DIRECTORY default_dir
  ACCESS PARAMETERS
  (
    com.oracle.bigdata.fileformat = jsondoc
    com.oracle.bigdata.credential.name = oci_adwc4pm
  )
   location ('https://objectstorage-location/fruit-extended.json')
);
 
SELECT f.data."count", f.data."modified"
     FROM fruit f
     WHERE f.data."name" = "apple";
 
count       modified
------------------------------
20          2020-06

Parent topic: Examples of JSONDOC Usage

17.7.3.5 Single-JSON Document with Multiline Files

A single JSON document with multiline files can be mapped to a table, where each JSON file in the directory is mapped to a single row.

Example 17-30 Single-JSON document, multiline files

A single JSON document with multiline files is a directory containing JSON files where each JSON file (document) in the directory is mapped to a single row in the table. In this case, the directory is /data, with the following files:

File: data/apple.json

{
   "name" : "apple",
   "count": 42
}

File: data/orange.json

{
   "name" : "orange",
   "count": 5
}

File: data/pear.json

{
   "name" : "pear",
   "count": 12
}

SQL Statement: 

CREATE TABLE fruit (data JSON) ORGANIZATION EXTERNAL (
  TYPE ORACLE_BIGDATA
  DEFAULT DIRECTORY default_dir
  ACCESS PARAMETERS
  (com.oracle.bigdata.fileformat = jsondoc)
  location ('data/*.json')
);
 
SQL> SELECT f.data."name", f.data."count"
     FROM fruit f;  
 
name            count
------------------------------
"apple"         20
"orange"        42
"pear"          10

Parent topic: Examples of JSONDOC Usage