JSON Documents

A JSON document is a tree of fields. Each field has a name, type, and value. In the case of an array type, the array field name and array index identify individual elements in the array. Field names are strings. The root of each document is a map. The advantages of JSON documents include the data types it supports and its schema flexibility. HPE Ezmeral Data Fabric Database provides tools that enable you to operate on JSON documents.

An online retailer of sports equipment might have this JSON document for storing data about a set of bicycle pedals:

{
    "_id" : "2DT3201",
    "product_ID" : "2DT3201",
    "name" : " Allegro SPD-SL 6800",
    "brand" : "Careen",
    "category" : "Pedals",
    "type" : "Components",
    "price" : 112.99,
    "features" : [
        "Low-profile design",
        "Floating SH11 cleats included"
    ],
    "specifications" : {
        "weight_per_pair" : "260g",
        "color" : "black"
    }
}

Data Types

HPE Ezmeral Data Fabric Database JSON documents support a richer set of data types beyond what JSON supports. JSON documents can have scalar data, nested documents, and arrays. HPE Ezmeral Data Fabric Database JSON stores the data in a format that maintains the types. To access JSON documents, you can use the OJAI API. The API exposes data types in a manner specific to the programming language of the API. JSON Document Data Types describes each category of types in relation to the sample JSON document shown earlier.

Comparing and Sorting Data Types

Comparisons and sorts of data types differ depending on whether the types are comparable or not. See Using Comparable JSON Document Data Types in Comparisons and Sorts and Using Non-comparable JSON Document Data Types in Comparisons and Sorts to learn which types fall into each category and to understand their behavior.

Schema Flexibility

The structure of each document, called the document's schema, is easy to change. Simply add new fields. For example, if the online retailer wants to allow customers to review products, it is simple to add the reviews to any document for a product.

In this example, highlighted in bold, the comments are added as an array with two nested documents:

{     
    "_id" : "2DT3201",
    "product_ID" : "2DT3201",       
    "name" : " Allegro SPD-SL 6800",
    "brand" : "Careen",
    "category" : "Pedals",
    "type" : "Components",
    "price" : 112.99,
    "features" : [
        "Low-profile design",
        "Floating SH11 cleats included"
    ],
    "specifications" : {
        "weight_per_pair" : "260g",
        "color" : "black"
    },
    "comments" : [
        {
            "username" : "hlmencken",
            "comment" : "Best money I ever spent!"
        },
        {
            "username" : "vwoolf",
            "comment" : "What hlmencken said!"
        }
    ]
}

Identifying Document Fields

To learn about how to access JSON document fields, see JSON Document Field Paths. The material includes examples that use the JSON document shown earlier.

Querying Document Fields

HPE Ezmeral Data Fabric Database allows you to specify query conditions in a JSON format using syntax supported by the OJAI API. See OJAI Query Condition Syntax for details.

JSON Document Size

The default maximum size of a JSON document is 32 MB. This size includes the field values in the document, as well as the names, types, and other field metadata. You can configure this size by running the command described at Configuring Maximum Row Sizes Using the CLI.

Tools for Working with JSON Documents

These are the tools you can use to create, read, update, and delete JSON documents in HPE Ezmeral Data Fabric Database:

HPE Ezmeral Data Fabric Database Shell

This shell is a light-weight tool for administering, manipulating, and querying JSON tables and documents. Learn more about it at HPE Ezmeral Data Fabric Database Shell (JSON Tables).

OJAI API

The OJAI API provides an interface for creating, reading, updating, and deleting JSON documents.

HPE Ezmeral Data Fabric Database JSON supports the OJAI API in the following languages:

  • Java
  • Node.js
  • Python
  • C#
  • Go

To learn about how to create, update, and delete JSON documents, see Managing JSON Documents. To learn about how to query JSON documents, see Querying in OJAI Applications.

For information that is specific to each language, see the following:

See Java OJAI Client API for the complete API.

See Using the Node.js OJAI Client for an introduction to this client.

See Node.js OJAI Client API for the complete API.

See Using the Python OJAI Client for an introduction to this client.

See Python OJAI Client API for the complete API.

See Using the C# OJAI Client for an introduction to this client.

See C# OJAI Client API for the complete API.

See Using the Go OJAI Client for an introduction to this client.

See Go OJAI Client API for the complete API.

HPE Ezmeral Data Fabric Database JSON REST API

The REST API enables you to use HTTP calls to perform basic operations on HPE Ezmeral Data Fabric Database JSON tables. Learn more about it at Using the HPE Ezmeral Data Fabric Database JSON REST API.