Overview of JSON Data Guide

24.1 Overview of JSON Data Guide

A data guide is a summary of the structural and type information contained in a set of JSON documents. It records metadata about the fields used in those documents.

For example, for the JSON object presented in Example 1-1, a data guide specifies that the document has, among other things, an object ShippingInstructions with fields name, Address, and Phone, of types string, object, and array, respectively. The structure of object Address is recorded similarly, as are the types of the elements in array Phone.

JSON data-guide information can be saved persistently as part of a JSON search index infrastructure. This information is then updated automatically as new JSON content is added. You specify this optional data-guide support when you create a JSON search index.

You can use a data guide:

As a basis for developing applications that involve data mining, business intelligence, or other analysis of JSON documents.
As a basis for providing user assistance about requested JSON information, including search.
To check or manipulate new JSON documents before adding them to a document set (for example: validate, type-check, or exclude certain fields).

For such purposes you can:

Query a data guide directly for information about the document set, such as field lengths or which fields occur with at least a certain frequency.
Create views, or add virtual columns, that project particular JSON fields of interest, based on their significance according to a data guide.

Note:

The advantages of virtual columns over a view are that you can build an index on a virtual column and you can obtain statistics on it for the optimizer.
The number of virtual columns per table is limited by the value of initialization parameter MAX_COLUMNS. By default that value is STANDARD, which means 1000 columns maximum. See MAX_COLUMNS in Oracle Database Reference.

Note:

A data guide serves as a guide to the structure of an existing set of JSON documents. To validate JSON data, use a JSON schema. A data guide created with either FORMAT_SCHEMA or FORMAT_HIERARCHICAL is a JSON schema, but only a data guide created with FORMAT_SCHEMA is useful for validating.

The following data-guide capabilities apply:

Note:

Path length: 4000 bytes. A path longer than 4000 bytes is ignored by a data guide.
Number of children under a parent node: 5000. A node that has more than 5000 children is ignored by a data guide.
Field value length: 32767 bytes. If a JSON field has a value longer than 32767 bytes then the data guide reports the length as 32767.
Data-guide behavior is undefined for data that contains zero-length (empty) object field name ("").