Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 36 ยท Shell and Basic Operations

Shell: Creating and Altering Tables

Use the HBase shell to create tables with column families and options, list and describe them, alter their schema, disable and enable them, and drop them safely.

The HBase shell is a JRuby-based interactive console. It is the fastest way to explore a cluster, test a schema idea or fix a production problem at 3 a.m. You start it with bin/hbase shell, and every command is a Ruby method call, which is why strings are quoted and options use => hashes.

All shell listings in this lesson are read-only, because the site has no HBase server. Outputs include timing lines that change on every run, so we describe results in words. The stand-in at the end is a small Java program that mimics table administration rules (families, enable/disable, drop) so you can practise the logic.

Getting around

Terminal
help                 # list all command groups
help 'create'        # detailed help for one command
version              # HBase version
status               # servers, regions, load (try 'status', 'simple', 'detailed')
whoami               # current user
list                 # names of all tables
exit

Commands that return data print a final line such as Took 0.0231 seconds. In a script you can run the shell non-interactively with echo "list" | hbase shell -n, or hbase shell script.rb.

Creating tables

The simplest form lists the table name and one or more column family names:

Terminal
create 'users', 'info'
create 'orders', 'details', 'items'

For per-family settings use a hash with NAME:

Terminal
create 'metrics',
  {NAME => 'm', VERSIONS => 3, TTL => 604800, COMPRESSION => 'SNAPPY', BLOOMFILTER => 'ROW'},
  {NAME => 'meta', VERSIONS => 1}

Common family options:

Option Meaning
VERSIONS Max versions kept per cell (default 1)
TTL Cell lifetime in seconds (default forever)
COMPRESSION NONE, SNAPPY, LZ4, GZ, ZSTD (the codec must be installed)
BLOOMFILTER NONE, ROW, ROWCOL
BLOCKSIZE HFile block size in bytes (default 65536)
IN_MEMORY true gives blocks higher cache priority
DATA_BLOCK_ENCODING NONE, PREFIX, DIFF, FAST_DIFF, ROW_INDEX_V1
MIN_VERSIONS Versions to keep even after TTL expiry

Table-wide options and pre-splitting go in the same command:

Terminal
create 'events', 'd', SPLITS => ['2', '4', '6', '8']
create 'logs', {NAME => 'l', TTL => 2592000}, {NUMREGIONS => 10, SPLITALGO => 'HexStringSplit'}

A table name may contain letters, digits, underscores, hyphens and dots. To put it in a namespace, write namespace:table, for example shop:users (see Namespaces, TTL and Snapshots).

Looking at tables

Terminal
list                       # all tables
list 'user.*'              # tables matching a regular expression
exists 'users'             # true or false
describe 'users'           # families and their settings
is_enabled 'users'

describe prints the table state (ENABLED) and one block per family with every option. It is the quickest way to confirm that VERSIONS and TTL are what you meant.

Altering a table

alter changes a table's schema. HBase 2.x applies it to an enabled table online (the hbase.online.schema.update.enable setting is true by default), and regions reopen with the new settings in the background.

Terminal
alter 'users', NAME => 'info', VERSIONS => 5       # change a family option
alter 'users', NAME => 'prefs'                     # add a new family
alter 'users', NAME => 'prefs', METHOD => 'delete' # remove a family and its data
alter 'users', MAX_FILESIZE => '21474836480'       # table-level attribute (20 GB)

Two warnings. Removing a family deletes its data when files are next rewritten. And some changes (for example enabling compression) only affect new HFiles; older files change when compaction rewrites them.

Disable, enable, drop

You cannot drop an enabled table. The shell makes you say so twice:

Terminal
disable 'users'
drop 'users'

disable takes the table offline: its regions are closed and no reads or writes succeed. enable brings it back. disable_all 'test.*' and drop_all 'test.*' do the same for regular expressions (the shell asks for confirmation). Other commands:

Terminal
truncate 'users'              # disable, drop and recreate with the same splits... (data removed)
truncate_preserve 'users'     # same, but keeps the existing region boundaries

truncate removes every row. Prefer truncate_preserve on a pre-split table, otherwise you lose the split points and start with one region again.

A mini-model of table administration

The stand-in below is plain Java, not HBase. It enforces the same rules the shell enforces: a family must be given, a table must be disabled before it is dropped, and writes to a disabled table fail.

Java Stand-in: table administration rules

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Reading a describe output

When you run describe, look for these things, in this order: the table is ENABLED, every family has the VERSIONS and TTL you intend, compression is set on large families, and BLOOMFILTER matches your read pattern. The second stand-in checks a schema against simple rules, the way a review checklist or a CI test might.

Java Stand-in: linting a table schema

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What must you do before dropping a table?

    An enabled table cannot be dropped. disable closes its regions, then drop removes it.
  2. 2. Which command adds a new column family to an existing table?

    alter with a NAME that does not yet exist adds that family. create on an existing table fails.
  3. 3. What is the advantage of truncate_preserve over truncate?

    truncate drops and recreates the table with a single region; truncate_preserve keeps the boundaries of a pre-split table.
  4. 4. What does METHOD => 'delete' in alter do?

    It is the way to remove a family; the data of that family goes with it.

Summary

  • The shell is JRuby: quoted strings, => hashes, one command per line; use help 'cmd'.
  • create takes a table name plus families or {NAME => ..., option => ...} hashes, optionally with SPLITS or NUMREGIONS.
  • list, exists, describe and is_enabled inspect tables.
  • alter changes or adds families online; METHOD => 'delete' removes one and its data.
  • Disable before drop; use truncate_preserve to keep pre-split regions.

Next: Shell: Put, Get and Delete