README for
1. MapRDB Shell
2. MapRDB Tools

=======================================
1.        MapR-DB Shell               *
=======================================

The maprdb shell is the mainly for use during proof of concept and internally
for dev/qa debugging or as a support tool for Ojai (aka JSON) tables in
MapRDB. It provides basic admin API's and simple CRUD operations as of today.

To run the shell, do the following command:
maprdb shell

The command processing infrastructure is based on https://github.com/spring-projects/spring-shell whose user documentation is here http://docs.spring.io/spring-shell/docs/current/reference/.

Some infrastructure points to note:
- ! can be used to run bash commands from within shell
- tabbing shows potential completions
- there is persistent history for all commands (upto 3000)
- Ctrl-R can be used to search the history

A. ADMIN commands:
------------------
1. create <tableName>
'tableName' can be simple end table name or the full path of the table in MapR cluster.
More parameters will be added in order of priority before GA release.
Ex: create jsonShellTable
    create /user/abcUser/jsonShellTable

2. drop <tableName>
Delete the table and its contents.
Ex: drop jsonShellTable

3. exists <tableName>
Prints true if the table exists.
Ex: exists jsonShellTable

4. desc <tableName>
Describes the properties of a table.
Ex: desc jsonShellTable
{"Path": "/jsonShellTable", "InsertionOrder": true, "BulkLoad": false, "AutoSplit": true, "SplitSize": 4096, "Families": [{"Id": 1, "Name": "default", "JsonFieldPath": "", "TTL": 0, "InMemory": false, "Compression": "LZ4"}]}

5. pwd
Prints the absolute path of the current working directory.

6. ls
Lists files and folders in current working directory.

7. jsonoptions
Sets the Json output options to the screen/shell. Currently provides pretty
printing of json document and removal of data type tags in output.
Ex:
maprdb:> jsonoptions --pretty true
maprdb:> jsonoptions --withTags false

8. exit
exit or quit to return out of the maprdb shell.

B. CRUD commands:
-----------------

1. Insert or replace into table
insert <tableName> --id <row key> --value <json string>

Ex:
maprdb:> insert jsonShellTable --id key10 --value '{"a":10,"b":{"c":5},"d":[1,11],"e":"str"}}'

Look at Section D.1 for info on the expected format for input json string value.

2. Get a row
findbyid <tableName> --id <rowkey>

Note: The --args input is needed for now as the shell infrastructure needs
      a key/value for everytihng after first parameter (tableName here). This
      might get removed when we get a chance to clone and fix it up in local
      github.

fields can be single element too.

Ex:
maprdb:> findbyid jsonShellTable --id key10
{"_id":"key10","a":10,"b":{"c":5},"d":[1,11],"e":"str"}

fields and condition are work in progress.

3. Scan all rows in a table (find)
find <tableName>
This prints the id and the corresponding document per line for all rows in the table.

Takes optional parameters to restrict the key range search and also limit the
number of rows returned.

Ex:
find jsonShellTable
find jsonShellTable -fromid a -toid q -limit 1000

4. Delete a row
delete <tableName> --id <rowkey> 
Ex:
maprdb:> delete jsonShellTable --id key11

5. Update a row
update <tableName> --id <rowkey> --value <json doc of new/updated key values>

Adds non-existing ones and updates existing ones from the value's list into the
rowkey's document.

Ex:
update jsonShellTable --id key111 --value '{"a":5, "b" : "abc"}'

The value field parsing in work in progress. Only single level fields are allowed in value for now.

C. TODO list:
-------------
1. update might not work for all inputs yet. Please ensure there is
   no 'ERROR' reported on screen. It is WIP.
2. Condition related language grammar for find/findbyid.
3. upsert should be able to (bulk) read from a file and insert into table and
   similarly find/findbyid should be given option to write output to a file.

D. Known "issues"
-----------------
1. 'help find' shows both names, but not actual help
maprdb:> help find
* findbyid - Get a single document from the table.
* find - Scan the table for its documents.
Doesn't show parameters for a find. 'help findbyid' works fine. Might need to modify spring-shell code to detect substrings.

2. checkAndReplace/Mutate/Delete will not be supported.

E. Examples:
------------
List of sample commands are in src/fs/client/dbclient-parent/shell/src/test/java/com/mapr/db/shell/tests/testCmds.txt.


====================================
2.        MapR-DB Tools            *
====================================
Provides the following tools, which can be run using 'maprdb <toolname>'
followed by their parameters:
  copytable           Copy table to another
  difftables          Compare tables
  formatresult        Decode the documents from sequence files generate by difftables / export command
  export              Export table to files
  import              Import files with JSON in SequenceFile format to table
  importJSON          Import files with JSON text to table

These are all same as their corresponding HBase counterpart tools.

For example:
#> maprdb copytable
Usage: CopyTable [Options] -src <source table path> -dst <destination table path>
Options:
[-startRow <start key>]
[-stopRow <end key>]
[-columns cf1[:col1],...]
[-bulkload <true|false> (default: true)]
[-mapreduce <true|false> (default: true)]
[-numthreads <number of threads> (default: 16)
