Home

Prerequisite software

Java 1.6, Maven 3

Build

1. Checkout the root cellmate tree including both cellmate-core and accumulo-cellmate.
2. Build from the root cellmate project using mvn clean install
3. This will create the jars cellmate-core-0.1.jar and accumulo-cellmate-0.1.jar and install to your local maven repository.
4. Copies of these jars are located in cellmate-core/target and accumulo-cellmate/target.
5. Cellmate requires guava-13.0.1.jar and log4j.1.2.15.jar be on your project classpath.

Getting Started

Let's start with a simple query.

You'll need to define an AccumuloParameters object with the proper settings. For a simple case lets take user, password, column families with qualifiers. The Builder pattern helps enforce immutability for the parameters of this particular query.

AccumuloParameters.Builder builder = new AccumuloParameters.Builder()
.setUser("root")
.setPassword("password")
.setTable("people")
.setColumns(new String[]{"info:name"}); 
AccumuloParameters parameters = builder.build();

We will be querying our test table 'people' for the qualifier 'name' in the column family 'info'. We supply the user 'root' and the default password 'password'. (Note you can omit the qualifier portion to the right of the ':' if you wish to capture everything in the column family).

In order to query our Accumulo table, we need to make an instance of AccumuloDBResultReader. The constructor only needs an instance name for the connection and a comma-delimited list of zookeeper hosts. There are other constructors, but for now this will suffice.

Now we setup the reader instance passing it the name of our Accumulo instance and a comma-delimited list of zookeeper hosts.

String instanceName = "testing"
String zookeepers = "localhost:2181"
AccumuloDBResultReader reader = new AccumuloDBResultReader(instanceName, zookeepers);

This reader can be reused throughout an application for any Accumulo scan.

Now we're ready to pass our parameters object to the reader and receive a list of CellGroup objects.

List<CellGroup<SecurityStringValueCell>> groups =  reader.read(parameters,  AccumuloCellTransformers.stringValueQualtoLabel());

The class AccumuloCellTransformers offers several useful CellTransformer implementations for use with Accumulo. The call to stringValueQualtoLabel() produces a CellTransformer that stores the qualifier of each key in a cell label, and the value bytes for that qualifier as the cell value. Even though the SecurityStringValueCell can hold additional information for column-family, column-visibility, and timestamp information, we omit that for this example.

The different cells produced are arranged in one or more cell groups. This particular transformer arranges cells in a distinct group per unique rowID seen across the scan. The rowID for each cell group is reflected in the group tag, which can be dereferenced using getTag() on the cell group. Different transformers may produce cell groups using any arbitrary logic.

We're left with a collection of cell groups, one per each rowID, that list each qualifier and value String found for that rowID.

Now we're interested in reading some of this content out.

Let's look across every cell group and look for a single cell with the qualifier 'name', which we expect to come back from the column family 'info' during our scan. Print the value of name for each group to stdout. Output any errors to stderr.

SingleMultiValueCellExtractor extractor = new SingleMultiValueCellExtractor();
for(CellGroup group : groups) {
    try {
         String value = extractor.getStringValueByLabel(group.getInternalList(), "name"); 
         System.out.println("cell group " + group.getTag());
         System.out.println("cell with label \'name\' has value " + value);
    } catch (CellExtractionException e) {
         System.err.println("error reading contents of cell group " + group.getTag()");
    } 
}

For this example we use the class SingleMultiValueCellExtractor to parse the cell value from our list expecting a single cell with the label 'name'. Should that method find multiple cells with that label, or the cell with the label has a null value, it will throw an error. The single-multi extractor contains a number of useful methods for extracting lists and scalar cell values from cell groups.

And that's it!. It's that easy to get started with the components in Cellmate. See below for additional code examples.

More Examples

[Making cells from Accumulo using CellTransformer](wiki/CellTransformer-Examples)

[Cell extraction basics](wiki/Extractor-Examples)

[Using AccumuloParameters](wiki/AccumuloParameters-Examples)

[Domain object example](wiki/Domain-Object-sample-generation)

[Extraction error explaination](wiki/Common-Extraction-Errors)

### Complete API reference ### Javadocs API