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. MapR-DB 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

MapR-DB JSON documents support a richer set of data types beyond what JSON supports. JSON documents can have scalar data, nested documents, and arrays. MapR-DB 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 noncomparable. See Using Comparable JSON Document Data Types in Comparisons and Sorts and Using Noncomparable 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

MapR-DB 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 MapR-DB:

MapR-DB Shell

This shell is a light-weight tool for administering, manipulating, and querying JSON tables and documents. Learn more about it at MapR-DB Shell (JSON Tables).

OJAI API

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

MapR-DB JSON supports the OJAI API in Java.

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.

See Java OJAI Client API for the complete Java OJAI API.

MapR-DB JSON REST API

The REST API enables you to use HTTP calls to perform basic operations on MapR-DB JSON tables. Learn more about it at Using the MapR-DB JSON REST API.