Need to incorporate JSON documents into existing Oracle database applications? The new native JSON datatype introduced in Oracle 21c makes it simple to store, access, traverse, and filter the complex data often found within JSON documents, often without any application code changes.

1. Going Native:
Leveraging the New
JSON Native Datatype
in Oracle 21c
Jim Czuprynski
@JimTheWhyGuy
Zero Defect Computing, Inc.

2. Who Am I, and What Am I Doing Here?
➢E-mail me at jim@jimthewhyguy.com
➢Follow me on Twitter (@JimTheWhyGuy)
➢Connect with me on LinkedIn (Jim Czuprynski)
Traveler & public speaker Summers:
Wisconsin
Winters:
Illinois
Cyclist
XC skier
Avid
amateur
bird
watcher
Oldest dude in
martial arts class

3. Jim Czuprynski
Liron Amitzi
https://www.beyondtechskills.com
The podcast that talks about everything tech – except tech.TM

4. Converged Database: A Vision for the Future, 21c and Beyond
Personal /
External
Datasets
Enterprise Applications
Data Integration
OAC, OML,
APEX, and
Graph Studio
Ad hoc,
Batch or
Scheduled
Business
Leaders
Analysts
Data
Scientists
Developers
OAC Dataflow,
Manual or ETL
Data Management
ADW
Business Analytics
ERP CRM HCM
Self-sufficient,
encrypted, secured
data storehouse
Self-service
analytics via ML
REST-Enabled
External APIs
IoT and
Edge
Computing
ATP
AJD AGD
Autonomous JSON Database
emerges as serious
contender versus MongoDB
Autonomous Database for
Graph Studio enables
analysis & visualization of
complex relationships
AutoML features make it simple
to apply the right algorithm(s)
with confidence

5. JSON Document Formatting and Components: A Refresher
{"type" : "FeatureCollection"
,"features" : [
{"type" : "Feature"
,"geometry" :
{"type" : "Point“
, "coordinates" : [-89.3106, 43.0653]
}
, "properties" : {
"Name" : "Blains Farm & Fleet"
, "Address" : "2202 SOUTH STOUGHTON ROAD"
, "City" : "MADISON”
, "State" : "WI"
, "ZIPCode" : "53716“
}
, "chargertypes": ["L2","L3"]
}
]
}
JSON
Document
(aka Object)
String : Value
pairs
GeoJSON
Array
Multiple String :
Value Pairs
Multiple Values in an Array
(~ a repeating group)

6. New in 21c: A Native JSON Datatype
CREATE TABLE bart.t_geojson(
gis_id NUMBER(06) NOT NULL
,gis_doc JSON
)
TABLESPACE json_data
STORAGE (INITIAL 8M NEXT 8M);
Here’s how simple it is
to designate the new
native JSON datatype
CREATE TABLE bart.t_notnative(
gis_id NUMBER(06) NOT NULL
,gis_doc BLOB
CONSTRAINT ensure_json
CHECK (gis_doc IS JSON)
)
LOB (gis_doc)
STORE AS (CACHE)
TABLESPACE json_data
STORAGE (INITIAL 8M NEXT 8M);
Compare it to this complex (but still-
valid!) syntax to create suitable
JSON storage in prior releases

7. Loading JSON Has Never Been This Easy
CREATE DIRECTORY XTJSON
AS '/u01/app/oracle/homes/OraDB21000_home1/XTFILES';
CREATE TABLE bart.xt_gis_docs(
gis_id VARCHAR2(06)
,gis_doc VARCHAR2(4000)
)
ORGANIZATION EXTERNAL (
TYPE ORACLE_LOADER
DEFAULT DIRECTORY XTJSON
ACCESS PARAMETERS (FIELDS TERMINATED BY '|')
LOCATION ('SampleGeoJSON.csv')
)
REJECT LIMIT 50000;
First, build an EXTERNAL
table referencing the
input file …

8. Loading JSON Has Never Been This Easy
CREATE DIRECTORY XTJSON
AS '/u01/app/oracle/homes/OraDB21000_home1/XTFILES';
CREATE TABLE bart.xt_gis_docs(
gis_id VARCHAR2(06)
,gis_doc VARCHAR2(4000)
)
ORGANIZATION EXTERNAL (
TYPE ORACLE_LOADER
DEFAULT DIRECTORY XTJSON
ACCESS PARAMETERS (FIELDS TERMINATED BY '|')
LOCATION ('SampleGeoJSON.csv')
)
REJECT LIMIT 50000;
First, build an EXTERNAL
table referencing the
input file …
TRUNCATE TABLE bart.t_geojson;
INSERT INTO bart.t_geojson(gis_id, gis_doc)
SELECT gis_id, gis_doc from bart.xt_gis_docs;
COMMIT;
… and then load the target
table via the standard INSERT
INTO … SELECT FROM method
Of course, loading via utilities like SQL*Loader is also fully supported!

9. Using New APEX Loading Capabilities for JSON Data Sources
New APEX loading
methods make
short work of
loading JSON
content

10. Using New APEX Loading Capabilities for JSON Data Sources
New APEX loading
methods make
short work of
loading JSON
content
Note the 21c Native JSON
column datatype is
automatically recognized

11. Feel the Need? The Need For Speed? 21c’s JSON Datatype is the Answer.
The new native JSON datatype is transferred between Oracle 21c client sessions and
the 21c database server without any textual conversion
• JSON encoding on ingest and text serialization on output are thus avoided
• This dramatically improves performance because it saves database CPU
The latest 21c client drivers are required to take advantage of these features!
• Otherwise, JSON datatype instances must first be converted to JSON text, which can dramatically
reduce the binary efficiencies of the JSON Native datatype
• The new 21c client are also capable of directly processing the binary JSON format (OSON) to
directly support JSON APIs
• The latest 21c client also supports the use of extended types
Note: SODA default collections built within an Oracle Database 21c must still use the 21c SODA
driver to leverage the native JSON type
Download the latest Oracle 21c Client drivers here

12. A New JSON Multi-Tool: JSON_TRANSFORM()
Check out a complete description of JSON_TRANSFORM() capabilities here
JSON_TRANSFORM()
Verb
Resulting Capability
INSERT Insert value of specified SQL expression at location targeted by specified path expression
APPEND Add value of specified SQL expression to targeted array
RENAME Rename field targeted by specified path expression to value of SQL expression
SET UPSERT data targeted by specified path expression to value of specified SQL expression
REPLACE Replace data defined by specified path expression with value of specified SQL expression
KEEP Remove all parts of input data not targeted by at least one of the specified path expressions
REMOVE Remove input data targeted by specified path expression

13. Updating JSON Key Values Directly With JSON_TRANSFORM
This statement will fix
Name values, but only
for selected entries
This UPSERT operation
didn’t require creating a
new copy of each JSON
document and then
essentially re-inserting the
updated document

14. JSON_TRANSFORM(): Some Other Examples
UPDATE bart.t_geojson
SET gi_doc =
JSON_TRANSFORM(gi_doc, SET '$.LastChangedOn' = SYSTIMESTAMP);
Add and populate a new column (LastChangedOn) to all JSON documents:
1
UPDATE bart.t_geojson
SET gis_doc =
JSON_TRANSFORM(gis_doc, APPEND '$.features.chargertypes' = 'Mr. Fusion');
Add a new element at the start of a specific JSON array:
2
UPDATE bart.t_geojson
SET gis_doc =
JSON_TRANSFORM(gis_doc, REMOVE '$.features.chargertypes');
Remove an existing element from an existing field for all JSON documents:
3

15. Differences between Native JSON vs. JSON_SCALAR() SQL Function
SELECT
JSON_VALUE(
JSON_SCALAR(CURRENT_TIMESTAMP), '$.timestamp()'
) AS "Extended TIMESTAMP"
FROM DUAL;
See this for a summary of Native JSON vs. JSON_SCALAR and JSON_SERIALIZE SQL functions
JSON_SCALAR() accepts
a SQL scalar value as
input and returns a
corresponding JSON
scalar value as a JSON
type instance
Extended TIMESTAMP
-------------------------------
12-JUN-22 04.50.04.138529000 PM
It therefore extends the
JSON native type for Oracle-
specific datatypes like DATE,
TIMESTAMP, and INTERVAL
YTM / DTS

16. Path Expression Item Methods With JSON_VALUE()
SELECT
gis_id
,JSON_VALUE(gis_doc,
'$.features.chargertypes[*].minString()’)
AS Lowest
,JSON_VALUE(gis_doc,
'$.features.chargertypes[*].maxString()’)
AS Highest
FROM bart.t_geojson;
Here’s an extensive list of the myriad conversion capabilities for JSON_VALUE()
JSON_VALUE() can
apply item methods
for data conversions
GIS_ID LOWEST HIGHEST
------ ---------- ----------
2714 L1 Mr. Fusion
2715 L1 Mr. Fusion
2716 L1 Mr. Fusion
2717 L1 Mr. Fusion
2718 L2 Mr. Fusion
. . .
In this example, it returns the minimum
and maximum string values within the
CHARGERTYPES item array

17. Multi-Value Functional Indexes: Benefits
{"type" : "FeatureCollection"
,"features" : [
{"type" : "Feature"
,"geometry" :
{"type" : "Point“
, "coordinates" : [-89.3106, 43.0653]
}
, "properties" : {
"Name" : "Blains Farm & Fleet"
, "Address" : "2202 SOUTH STOUGHTON ROAD"
, "City" : "MADISON”
, "State" : "WI"
, "ZIPCode" : "53716“
}
, "chargertypes": ["L2","L3"]
}
]
}
This CHARGERTYPES
JSON array may store
multiple different
values …
… but what if our query needs to
find only charging locations
offering L3 chargers?

18. Multi-Value Functional Indexes: Implementation
DROP INDEX bart.chargertypes_fk_idx;
CREATE MULTIVALUE INDEX bart.chargertypes_fk_idx
ON bart.t_geojson t
(t.gis_doc.features.chargertypes[*].string());
Not a problem in 21c! We can create a multi-value
index for that JSON array’s values
Note that various JSON datatype
expressions are supported as well

19. Multi-Value Indexes: Proof of Usage
SELECT
gis_id AS id
,TI.gis_doc.features.properties.City AS city
FROM bart.t_geojson TI
WHERE JSON_EXISTS(gis_doc,
'$.features.chargertypes[*]?(@.string() == "L3")');
Here’s a simple query to test
usage of the multi-value index
on values stored within the
CHARGERTYPES JSON array

20. Multi-Value Indexes: Proof of Usage
SELECT
gis_id AS id
,TI.gis_doc.features.properties.City AS city
FROM bart.t_geojson TI
WHERE JSON_EXISTS(gis_doc,
'$.features.chargertypes[*]?(@.string() == "L3")');
Here’s a simple query to test
usage of the multi-value index
on values stored within the
CHARGERTYPES JSON array
The RANGE SCAN (MULTI VALUE)
operation indicates the multi-value index
on CHARGERTYPES was definitely used

21. Storing, Indexing, and Using GeoJSON GIS Data
{"type" : "FeatureCollection"
,"features" : [
{"type" : "Feature"
,"geometry" :
{"type" : "Point“
, "coordinates" : [-89.3106, 43.0653]
}
, "properties" : {
"Name" : "Blains Farm & Fleet"
, "Address" : "2202 SOUTH STOUGHTON ROAD"
, "City" : "MADISON”
, "State" : "WI"
, "ZIPCode" : "53716“
}
, "chargertypes": ["L2","L3"]
}
]
}
This GEOMETRY JSON object contains a
GeoJSON longitude / latitude pair

22. Storing, Indexing, and Using GeoJSON GIS Data
{"type" : "FeatureCollection"
,"features" : [
{"type" : "Feature"
,"geometry" :
{"type" : "Point“
, "coordinates" : [-89.3106, 43.0653]
}
, "properties" : {
"Name" : "Blains Farm & Fleet"
, "Address" : "2202 SOUTH STOUGHTON ROAD"
, "City" : "MADISON”
, "State" : "WI"
, "ZIPCode" : "53716“
}
, "chargertypes": ["L2","L3"]
}
]
}
This GEOMETRY JSON object contains a
GeoJSON longitude / latitude pair
SELECT
JSON_VALUE(gis_doc, '$.features[0].geometry'
RETURNING SDO_GEOMETRY
ERROR ON ERROR) AS SDOGeometryObject
,TI.gis_doc.features.properties[0].City AS City
,TI.gis_doc.features.properties[0].ZIPCode AS "ZIP Code"
FROM bart.t_geojson TI;
21c lets us translate them
directly into an
SDO_GEOMETRY object for use
in mapping and geolocation

23. Building a New APEX App Using GeoJSON Data (1)
We’ll create a new APEX app …
1

24. Building a New APEX App Using GeoJSON Data (1)
We’ll create a new APEX app …
1
… from either an existing
template, or downloaded code
2

25. Building a New APEX App Using GeoJSON Data (2)
We’ll build the new app
from scratch …
3
… and name it appropriately
4

26. Building a New APEX App Using GeoJSON Data (3)
Next, we’ll add a page using the new
APEX 21.2 Native Map Region …
5
… to demonstrate GeoJSON
mapping capabilities
6

27. Building a New APEX App Using GeoJSON Data (4)
Here’s the resulting
APEX Native Map
Region, populated with
Longitude & Latitude
coordinates …
8

28. Building a New APEX App Using GeoJSON Data (4)
Here’s the resulting
APEX Native Map
Region, populated with
Longitude & Latitude
coordinates …
8
… and an Interactive Report
region with other data elements
relevant to each plotted location
9

29. Oh … One More Thing.
Document Databases are great, but ...
MongoDB has popularized document databases for developers with their free
to use community edition. MongoDB offers simple document database APIs;
however, it has limitations supporting multi-document ACID transactions
critical to enterprise applications. For developers, implementing basic SQL
engine functionality requires writing, testing and maintaining hundreds of
lines of application code, resulting in security vulnerabilities, increased
development time and maintenance.
- October 26, 2021: Kiran Makarla & Beda Hammerschmidt,
Oracle Database API for MongoDB with Oracle Autonomous Database
opens up an entirely new set of use cases for MongoDB applications

30. So, Your Data Is In MongoDB. And Your Point Is?
Establish security permissions
to access data within your
MongoDB database …
1
… create collections
and data within
MongoDB …
2
… and start accessing your
MongoDB data directly
from Oracle!
3

31. JSON: References and Further Reading
JSON DataType Support in Oracle 21c:
https://blogs.oracle.com/database/post/json-datatype-support-in-oracle-21c
Storing, Indexing, and Using GeoJSON Geographic Data:
https://docs.oracle.com/en/database/oracle/oracle-database/21/adjsn/using-GeoJSON-geographic-data.html
Autonomous JSON Database (AJD) and SODA Examples:
https://www.slideshare.net/jczuprynski/json-a-splash-of-soda-and-a-sql-chaser-realworld-use-cases-for-autonomous-json-database-ajd
OSON - A Deeper Look:
https://blogs.oracle.com/jsondb/osonformat
http://www.vldb.org/pvldb/vol13/p3059-liu.pdf