Standalone (CLI)

MASH client is primarily used to administer the Ampool cluster i.e. Start/Stop Ampool Server & Locator instances, List, View cluster configuration & individual member metrics etc. Although it can also be used to create, populate and view the data from Ampool tables, primarily for development & troubleshooting purposes.

It is mandatory to connect w/ Ampool cluster before executing any store access commands. An existing MASH shell instance, through which Locator and Server is started, is implicitly connected to the Ampool Cluster. Although, if you start a new shell or restart an existing shell, you must explicitly connect to Ampool Cluster using it's locator details.

MASH commands are, typically, executed in an interatactive way (like any command-line-interface), where you type-in some command and results are displayed on the screen. It also provides a way to execute commands in non-interactive way (as a batch of commands via multiple -e options) from the system prompt. The commands are executed in the specified order and the results are displayed on the screen. The MASH prompt is not displayed, though, in such a way.

Note

Any command specified using, -e option requires connection to the Ampool cluster; therefore the first command must be a "connect" command.

For example to display all members, in non-interactive way using MASH, that are part of the cluter, we can execute the following command:

$>/<ampool-home>/bin/mash -e "connect --locator=localhost[10334]" -e "list members"

(1) Executing - connect --locator=localhost[10334]

Connecting to Locator at [host=localhost, port=10334] ..
Connecting to Manager at [host=192.168.65.1, port=1099] ..
Successfully connected to: [host=192.168.65.1, port=1099]


(2) Executing - list members

  Name   | Id
-------- | -------------------------------------------------
Locator1 | 192.168.65.1(Locator1:56049:locator)<ec><v0>:1024
Server1  | 192.168.65.1(Server1:56062)<ec><v1>:1025

1. Create, List & Describe Tables

There are three types of tables that are supported in Ampool. ORDERED_VERSIONED -- The contents of this type of table are ordered/sorted on the key. UNORDERED -- The contents of this type of table are partitioned based on hash-code of the key. * IMMUTABLE -- The contents of this type of table are immutable and ordered on the insertion-time (append only).

Once the MASH instance is connected to the cluster, you can use create table command to create the tables in Ampool. You can use appropriate options to create the table.

To create a table of ORDERED_VERSIONED type that stores binary data in all columns, you can use the following command.

mash>create table --name=T1 --type=ORDERED_VERSIONED --columns=ID,NAME,AGE,GENDER,DESIGNATION --disk-persistence=true --disk-write-policy=ASYNCHRONOUS --eviction-policy=OVERFLOW_TO_DISK --ncopies=0 --versions=1 --nbuckets=5
Successfully created the table: T1

In Ampool tables can be created with schema where each column can have a type associated with it. To create a table of IMMUTABLE type with column-type other than binary:

mash>create table --type=IMMUTABLE --name=T2 --schema-json='{"ID":"INT", "NAME":"STRING", "AGE":"INT", "GENDER":"STRING","DESIGNATION":"STRING"}'
Successfully created the table: T2

You can list all available tables in Ampool cluster using list tables command.

mash>list tables
Name | Type
---- | -----------------
T1   | Ordered Versioned
T2   | Immutable

Also, once the tables are created, you can view their configuration using describe table command.

mash>describe table --name=T1
.........................................................................................................
Name            : T1
Data Policy     : persistent partition
Hosting Members : server0

Non-Default Attributes Shared By Hosting Members

      Type       |        Name         | Value
---------------- | ------------------- | ------------------------------------------------------------
Table            | data-policy         | PERSISTENT_PARTITION
                 | disk-store-name     | AMPOOL_DEFAULT_DISK_STORE
                 | size                | 0
Eviction         | eviction-action     | overflow-to-disk
                 | eviction-algorithm  | lru-heap-percentage
Partition        | partition-resolver  | org.apache.geode.internal.cache.MTableRangePartitionResolver
                 | total-num-buckets   | 5
Table Attributes | table-type          | ORDERED_VERSIONED
                 | max-versions        | 1
                 | persistence-enabled | true
                 | disk-write-policy   | ASYNCHRONOUS
Table Schema     | ID                  | BINARY
                 | NAME                | BINARY
                 | AGE                 | BINARY
                 | GENDER              | BINARY
                 | DESIGNATION         | BINARY


mash>
mash>describe table --name=T1
............................................................
Name            : T2
Data Policy     : persistent partition
Hosting Members : server0

Non-Default Attributes Shared By Hosting Members

      Type       |           Name            | Value
---------------- | ------------------------- | -------------------------
Table            | data-policy               | PERSISTENT_PARTITION
                 | disk-store-name           | AMPOOL_DEFAULT_DISK_STORE
                 | size                      | 0
                 | entry-time-to-live.action | DESTROY
Eviction         | eviction-action           | overflow-to-tier
                 | eviction-algorithm        | lru-heap-percentage
Partition        | redundant-copies          | 1
                 | partition-resolver        | MPartitionResolver
Table Attributes | table-type                | IMMUTABLE
                 | block-size                | 1000
                 | number-of-blocks          | 0
                 | persistence-enabled       | true
                 | disk-write-policy         | ASYNCHRONOUS
Table Schema     | ID                        | INT
                 | NAME                      | STRING
                 | AGE                       | INT
                 | GENDER                    | STRING
                 | DESIGNATION               | STRING
                 | __INSERTION_TIMESTAMP__   | LONG
Tier Attributes  | tier1-store               | DefaultLocalORCStore
                 | tier1-partition-interval  | 10 minutes
                 | tier1-time-to-expire      | -

2. Insert Data

Once the tables are created, you can use the appropriate commands to insert the data into the tables. To insert the data into tables with ORDERED_VERSIONED and UNORDERED types you can use the command tput.

For the tables created with column-type as binary, you can use simple key=value pairs to insert the data into a table.

mash>tput --table=T1 --key=1 --value=ID=1,NAME=Andy,AGE=34,GENDER=M,DESIGNATION=PM
Put completed successfully

mash>tput --table=T1 --key=2 --value=ID=2,NAME=Deepa,AGE=26,GENDER=F,DESIGNATION=SE
Put completed successfully

mash>tput --table=T1 --key=3 --value=ID=3,NAME=Sri,AGE=32,GENDER=M,DESIGNATION=SSE
Put completed successfully

For the tables with non-binary column types, you have to use --value-json option and provide the input as a valid JSON with the column names and respective values. This option can be used for all types of tables.

The command tappend can be used to append the data in IMMUTABLE tables.

mash>tappend --table=T2 --value-json='{"ID":"1", "NAME":"Joey", "AGE":"33", "GENDER":"M","DESIGNATION":"ARCH"}'
Append completed successfully

mash>tappend --table=T2 --value-json='{"ID":"2", "NAME":"Monica", "AGE":"38", "GENDER":"F","DESIGNATION":"ARCH"}'
Append completed successfully

mash>tappend --table=T2 --value-json='{"ID":"3", "NAME":"Janice", "AGE":"29", "GENDER":"M","DESIGNATION":"HR"}'
Append completed successfully

3. Retrieve Data

There are two ways to retrieve data from tables with type ORDERED_VERSIONED and UNORDERED. These tables require you to provide the key when inserting the data; the same key can be used to retrieve the respective data using tget command.

mash>tget --table=T1 --key=1
KEY         : 1
ID          : [49]
NAME        : [65, 110, 100, 121]
AGE         : [51, 52]
GENDER      : [77]
DESIGNATION : [80, 77]
-------------------------------

mash>tget --table=T1 --key=2
KEY         : 2
ID          : [50]
NAME        : [68, 101, 101, 112, 97]
AGE         : [50, 54]
GENDER      : [70]
DESIGNATION : [83, 69]
------------------------------------

Alternatively, they also provide a scan operation that can help to retrieve you data from these tables. You can retrieve all contents of the table using tscan command.

mash>tscan --table=T1

Result     : true
startCount : 0
endCount   : 20
Rows       : 3

Result
----------------------------------------------------------------------------------------------------
RowID = [49] ID=[49], NAME=[65, 110, 100, 121], AGE=[51, 52], GENDER=[77], DESIGNATION=[80, 77]
RowID = [50] ID=[50], NAME=[68, 101, 101, 112, 97], AGE=[50, 54], GENDER=[70], DESIGNATION=[83, 69]
RowID = [51] ID=[51], NAME=[83, 114, 105], AGE=[51, 50], GENDER=[77], DESIGNATION=[83, 83, 69]

NEXT_STEP_NAME : END

The IMMUTABLE tables are append only tables and they support only scan operation.

mash>tscan --table=T2

Result     : true
startCount : 0
endCount   : 20
Rows       : 3

Result
----------------------------------------------------------------------------------------------
ID=1, NAME=Joey, AGE=33, GENDER=M, DESIGNATION=ARCH, __INSERTION_TIMESTAMP__=15805785261822
ID=3, NAME=Janice, AGE=29, GENDER=M, DESIGNATION=HR, __INSERTION_TIMESTAMP__=15818470798462
ID=2, NAME=Monica, AGE=38, GENDER=F, DESIGNATION=ARCH, __INSERTION_TIMESTAMP__=15812619779412

NEXT_STEP_NAME : END

Depending on the column types used at time of table creation the results are displayed as the respective objects or binary data. It is applicable to all types of tables.

Also, you can save the output of tscan command to a file by using the following command. This can be used for all types of tables.

mash>tscan --table=T2 --file=t.csv
Result  : true
Message : 3 rows inserted to t.csv


NEXT_STEP_NAME : END

4. Delete Tables

To delete the tables you can use the command delete table along with the respective table-name.

mash>delete table --name=T1
Successfully deleted the table: "T1"

mash>delete table --name=T2
Successfully deleted the table: "T2"