HBase tutorial for beginners   December 22nd, 2008

This post is old. Most of the code does not compile at the moment!

First of all, HBase is a column oriented database. However, you have to forget everything you have learned about tables, columns and rows in the RDBMS world. The data in an HBase instance is layed out more like a hashtable, and the data is immutable. Whenever you update the data, you are actually just creating a new version of it.

This tutorial will be very hands-on, with not too much explanation. There are a number of articles where the column oriented databases are described in details. Check out my delicious tag for some good ones, for instance jimbojw.com’s excellent introduction

I used Apple OSX 10.5.6 in this tutorial, I am not sure if this will work on windows and linux.

The goal for this tutorial is to create a model for a blog with integration from a java program.

Get started

  • Download from the latest stable release from apache. I went with the hbase-0.18.1 release.
  • Unpack it, for instance to ~/hbase
  • Edit ~/hbase/conf/hbase-env.sh and set the correct JAVA_HOME variable.
  • Start hbase by running ~/hbase/bin/start-hbase.sh

Create a table

  • Start the hbase shell by running ~/hbase/bin/hbase shell
  • Run create ‘blogposts’, ‘post’, ‘image’ in the shell

Now you have a table called blogposts, with a post, and a image family. These families are “static” like the columns in the RDBMS world.

Add some data to the table

Run the following commands in the shell:

  • put ‘blogposts’, ‘post1′, ‘post:title’, ‘Hello World’
  • put ‘blogposts’, ‘post1′, ‘post:author’, ‘The Author’
  • put ‘blogposts’, ‘post1′, ‘post:body’, ‘This is a blog post’
  • put ‘blogposts’, ‘post1′, ‘image:header’, ‘image1.jpg’
  • put ‘blogposts’, ‘post1′, ‘image:bodyimage’, ‘image2.jpg’

Look at the data

Run get ‘blogposts’, ‘post1′ in the shell. This should output something like this.

image:bodyimage timestamp=1229953133260, value=image2.jpg
image:header timestamp=1229953110419, value=image1.jpg
post:author timestamp=1229953071910, value=The Author
post:body timestamp=1229953072029, value=This is a blog post
post:title timestamp=1229953071791, value=Hello World

Summary part1

So, what have we accomplished so far? We have created a table and added one ‘record’ to it. This record consists of the blogpost itself, and the images attached to it. So, how do we retrieve those data from a java application?

Integrate with HBase from Java

In order to integrate with HBase you will need the following jar files in your classpath:

  • commons-logging-1.0.4.jar
  • hadoop-0.18.1-core.jar
  • hbase-0.18.1.jar
  • log4j-1.2.13.jar

All these are found within ~/hbase/lib and ~/hbase

Ok. Here’s the java code:

import org.apache.hadoop.hbase.client.HTable;
import org.apache.hadoop.hbase.HBaseConfiguration;
import org.apache.hadoop.hbase.io.RowResult;

import java.util.HashMap;
import java.util.Map;
import java.io.IOException;

public class HBaseConnector {

public static Map retrievePost(String postId) throws IOException {
HTable table = new HTable(new HBaseConfiguration(), "blogposts");
Map post = new HashMap();

RowResult result = table.getRow(postId);

for (byte[] column : result.keySet()) {
post.put(new String(column), new String(result.get(column).getValue()));
return post;

public static void main(String[] args) throws IOException {
Map blogpost = HBaseConnector.retrievePost("post1");

This code should print out ‘Hello World’ and ‘The Author’.

Happy coding, check out HBase’s javadoc for more examples.

Please leave feedback in the comments.