MapR 5.1 is at End of Life (EOL) and no longer supported. Please see the latest documentation. This documentation is not being updated.

Home
5.1 DB & Streams
This section covers the MapR-DB, MapR-Streams, and MapR-Gateways features. Each feature may contain both administrator and developer topics.
MapR-DB
MapR-DB as a Document Database
MapR-DB supports OJAI documents as a native data store. OJAI documents are stored in a compact binary format, not as plain ASCII text.
Creating, Reading, Updating, and Deleting Documents and Tables with the MapR-DB JSON Java API Library
The basic tasks that you can perform with the API library involve the Admin, Document, DocumentMutation, QueryCondition, Table, and TableDescriptor interfaces.
Updating and Deleting Documents and Tables with the MapR-DB JSON Java API Library
This API comes with a large variety of methods for updating OJAI documents and JSON tables. This section lists examples, provides code samples, and links to sections of the Javadoc, where you can see all of the methods for performing such updates.
Table.insertOrReplace()
Inserts a document into a table or, if the ID of the document matches the ID of a document already in the table, replaces the document that is in the table.

MapR 5.1 Documentation

5.1 DB & Streams
This section covers the MapR-DB, MapR-Streams, and MapR-Gateways features. Each feature may contain both administrator and developer topics.
- MapR-DB
  - Architecture of MapR-DB
    MapR-DB's architecture gives it a large of advantages over other NoSQL databases.
  - Performance Enhancements for SSD Based MapR-DB Deployments
  - MapR-DB as a Document Database
    MapR-DB supports OJAI documents as a native data store. OJAI documents are stored in a compact binary format, not as plain ASCII text.
    - OJAI Documents
      An OJAI document is a tree of fields. Each field has a type and a value, and also has either a name or an array index. Field names are strings. The root of each document is a map.
    - JSON Tables
      Documents are stored in JSON tables, which are tables in which every row is an OJAI document.
    - Creating, Reading, Updating, and Deleting Documents and Tables with the MapR-DB JSON Java API Library
      The basic tasks that you can perform with the API library involve the Admin, Document, DocumentMutation, QueryCondition, Table, and TableDescriptor interfaces.
      - Creating JSON Tables with the MapR-DB OJAI Java API Library
        Create a JSON table by calling an Admin object's createTable() method, passing as an argument the path that you want to use for the new table.
      - Creating Documents with the MapR-DB JSON Java API Library
        You create and manipulate OJAI documents as Document objects.
      - Querying Documents with the MapR-DB JSON Java API Library
        Use the find() and findById() methods of a Table object to query the documents in the JSON table that the Table object represents.
      - Updating and Deleting Documents and Tables with the MapR-DB JSON Java API Library
        This API comes with a large variety of methods for updating OJAI documents and JSON tables. This section lists examples, provides code samples, and links to sections of the Javadoc, where you can see all of the methods for performing such updates.
        DocumentMutation.append()
        Appends a string value to a string or an array item to an array.
        Table.checkAndDelete()
        Deletes a document, if that document satisfies the conditions that are specified in a QueryCondition object.
        Table.checkAndMutate()
        Applies changes from a DocumentMutation object to a document, if the document satisfies conditions that are specified in a QueryCondition object.
        Table.checkAndReplace()
        Replaces a document, if the document to replace satisfies conditions that are in a QueryCondition object.
        DocumentMutation.delete()
        Deletes the field at the specified path.
        Table.delete()
        Deletes the specified document from a table.
        DocumentMutation.increment()
        Increments the value of a numeric field by the amount of the specified value.
        Table.increment()
        Increments the value of a numeric field by the amount of the specified value.
        Table.insert()
        Inserts a document into a table.
        Table.insertOrReplace()
        Inserts a document into a table or, if the ID of the document matches the ID of a document already in the table, replaces the document that is in the table.
        DocumentMutation.merge()
        Merges a document with a nested document that is in an existing document.
        Table.replace()
        Replaces a document in a table with the specified document.
        Document.set()
        Inserts a field into an existing document or changes the value of a field in an existing document.
        DocumentMutation.set()
        Either creates a field in a document and gives the field the specified value, or replaces the value of a field that already exists in a document.
        DocumentMutation.setNull()
        Either creates a new field in a document and gives the field a null value, or replaces the value of an existing field with a null value.
        DocumentMutation.setOrReplace()
        Either creates a field in a document and gives the field the specified value, or replaces the value of a field that already exists in a document.
        DocumentMutation.setOrReplaceNull()
        Either creates a new field in a document and gives the field a null value, or replaces the value of an existing field with a null value.
        Table.update()
        Applies to an OJAI document the updates that are contained in a DocumentMutation object.
    - Listing Tables with the MapR-DB JSON Java API Library
      List the JSON tables that are in a folder by calling an Admin object's listTables() method, passing as an argument the path of the folder.
    - Altering JSON Tables with the MapR-DB OJAI Java API Library
      Change the values of table attributes by using a TableDescriptor object and then passing that object to the Admin interface's altertable() method.
    - Deleting JSON Tables with the MapR-DB OJAI Java API Library
      Delete a JSON table by calling an Admin object's deleteTable() method, passing as an argument the path of the table to delete.
    - Compiling and Running Applications that Access JSON Tables and Documents
      You can compile applications that use the MapR-DB JSON API by using the required JAR file from the MapR Maven repository or from the MapR installation. Run applications with the mapr command.
    - Tuning Parameters for Client Applications That Access MapR-DB JSON Tables
      Though tuning client applications is generally not necessary, MapR does offer tuning parameters to change the behavior of client-side caching.
    - Loading Documents into JSON Tables
      There are three command-line utilities for loading documents into JSON tables: mapr copytable, mapr importtable (which works in conjunction with the mapr exporttable utility), and mapr importJSON
    - MapR-DB JSON MapReduce API Library
      This API library extends the Apache Hadoop MapReduce framework, so that you can write your own MapReduce applications to write data from one JSON table to another.
    - Column Families in JSON Tables
      JSON tables store data in column families, which are collections of fields that are stored together on disk.
    - Granting or Denying Access to Fields with Access-Control Expressions
      By using access-control expressions (ACEs), you can grant or deny access to fields and column families that are in JSON tables.
    - Getting Started with MapR-DB JSON and OJAI
  - MapR-DB as a Wide-Column Database
- MapR Streams
  MapR Streams brings integrated publish/subscribe messaging to the MapR Converged Data Platform.
- MapR Gateways
  A MapR gateway mediates one-way communication between a source MapR cluster and a destination cluster. MapR-DB binary tables and MapR Streams streams can be replicated.

Table.insertOrReplace()

Inserts a document into a table or, if the ID of the document matches the ID of a document already in the table, replaces the document that is in the table.

Operations Performed

Verifies whether a document with the specified ID already exists.

If a document with the ID already exists, replaces the existing document.
If a document with the ID does not exist, inserts the document.

Example

Original document with ID "movie000001"

{
	"_id" : "movie0000001",
	"title" : "Placeholder doc"
}

Example code

  public Document buildDocument() {
    return MapRDB.newDocument()
        .setId("movie0000001")
        .set("title", "OJAI -- The Documentary")
        .set("studio", "MapR Technologies, Inc.")
        .set("release_date", Values.parseDate("2015-09-29"))
        .set("trailers.teaser", "https://10.10.21.90/trailers/teaser")
        .set("trailers.theatrical", "https://10.10.21.90/trailers/theatrical")
        .setArray("characters", ImmutableList.of("Heroic Developer", "Evil Release Manager", "Mad Development Manager"))
        .set("box_office_gross", 1000000000L);
  }


public void insertOrReplaceDocument(String tablePath, String _id, Document document) {
    try(Table table = MapRDB.getTable(tablePath)) {
      table.insertOrReplace(_id, document);
    }
  }

Parameter	Description
`_id`	The value of the document's `_id` field.
`tablePath`	The path of the table in the MapR file system. See Table Paths.

New document with ID "movie000001"

{
	"_id" : "movie0000001",
	"title" : "OJAI -- The Documentary",
	"studio" : "MapR Technologies, Inc.",
	"release_date" : "2015-09-29",
	"trailers" : {
		"teaser" : "https://10.10.21.90/trailers/teaser",
		"theatrical" : "https://10.10.21.90/trailers/theatrical"
	},
	"characters" : [
		"Heroic Developer", 
           "Evil Release Manager", 
           "Mad Development Manager"
	],
	"box_office_gross" : 1000000000L
}

Permissions Required

The readAce and writeAce permissions on the volumes where the JSON tables that contain the documents are located. For information about how to set permissions on volumes, see Setting/Modifying Whole Volume ACEs.
readperm and writeperm on the column families in the row.

Link to Javadoc