org.apache.hadoop.hbase.client
Class HBaseAdmin

java.lang.Object
  extended by org.apache.hadoop.hbase.client.HBaseAdmin
All Implemented Interfaces:
Abortable

public class HBaseAdmin
extends Object
implements Abortable

Provides an interface to manage HBase database table metadata + general administrative functions. Use HBaseAdmin to create, drop, list, enable and disable tables. Use it also to add and drop table column families.

See HTable to add, update, and delete data from an individual table.

Currently HBaseAdmin instances are not expected to be long-lived. For example, an HBaseAdmin instance will not ride over a Master restart.


Constructor Summary
HBaseAdmin(org.apache.hadoop.conf.Configuration c)
          Constructor
 
Method Summary
 void abort(String why, Throwable e)
          Abort the server or client.
 void addColumn(byte[] tableName, HColumnDescriptor column)
          Add a column to an existing table.
 void addColumn(String tableName, HColumnDescriptor column)
          Add a column to an existing table.
 void assign(byte[] regionName, boolean force)
           
 boolean balancer()
          Invoke the balancer.
 boolean balanceSwitch(boolean b)
          Turn the load balancer on or off.
static void checkHBaseAvailable(org.apache.hadoop.conf.Configuration conf)
          Check to see if HBase is running.
 void closeRegion(byte[] regionname, String hostAndPort)
          Close a region.
 void closeRegion(HServerAddress hsa, HRegionInfo hri)
           
 void closeRegion(String regionname, String hostAndPort)
          Close a region.
 void compact(byte[] tableNameOrRegionName)
          Compact a table or an individual region.
 void compact(String tableNameOrRegionName)
          Compact a table or an individual region.
 void createTable(HTableDescriptor desc)
          Creates a new table.
 void createTable(HTableDescriptor desc, byte[][] splitKeys)
          Creates a new table with an initial set of empty regions defined by the specified split keys.
 void createTable(HTableDescriptor desc, byte[] startKey, byte[] endKey, int numRegions)
          Creates a new table with the specified number of regions.
 void createTableAsync(HTableDescriptor desc, byte[][] splitKeys)
          Creates a new table but does not block and wait for it to come online.
 void deleteColumn(byte[] tableName, byte[] columnName)
          Delete a column from a table.
 void deleteColumn(String tableName, String columnName)
          Delete a column from a table.
 void deleteTable(byte[] tableName)
          Deletes a table.
 void deleteTable(String tableName)
          Deletes a table.
 void disableTable(byte[] tableName)
          Disable table and wait on completion.
 void disableTable(String tableName)
           
 void disableTableAsync(byte[] tableName)
          Starts the disable of a table.
 void disableTableAsync(String tableName)
           
 void enableTable(byte[] tableName)
          Enable a table.
 void enableTable(String tableName)
           
 void enableTableAsync(byte[] tableName)
          Brings a table on-line (enables it).
 void enableTableAsync(String tableName)
           
 void flush(byte[] tableNameOrRegionName)
          Flush a table or an individual region.
 void flush(String tableNameOrRegionName)
          Flush a table or an individual region.
 ClusterStatus getClusterStatus()
           
 org.apache.hadoop.conf.Configuration getConfiguration()
           
 HConnection getConnection()
           
 HMasterInterface getMaster()
          Get a connection to the currently set master.
 HTableDescriptor getTableDescriptor(byte[] tableName)
          Method for getting the tableDescriptor
 boolean isMasterRunning()
           
 boolean isTableAvailable(byte[] tableName)
           
 boolean isTableAvailable(String tableName)
           
 boolean isTableDisabled(byte[] tableName)
           
 boolean isTableDisabled(String tableName)
           
 boolean isTableEnabled(byte[] tableName)
           
 boolean isTableEnabled(String tableName)
           
 HTableDescriptor[] listTables()
          List all the userspace tables.
 void majorCompact(byte[] tableNameOrRegionName)
          Major compact a table or an individual region.
 void majorCompact(String tableNameOrRegionName)
          Major compact a table or an individual region.
 void modifyColumn(byte[] tableName, byte[] columnName, HColumnDescriptor descriptor)
          Deprecated. The columnName is redundant. Use modifyColumn(byte[], HColumnDescriptor)
 void modifyColumn(byte[] tableName, HColumnDescriptor descriptor)
          Modify an existing column family on a table.
 void modifyColumn(String tableName, HColumnDescriptor descriptor)
          Modify an existing column family on a table.
 void modifyColumn(String tableName, String columnName, HColumnDescriptor descriptor)
          Deprecated. The columnName is redundant. Use addColumn(String, HColumnDescriptor)
 void modifyTable(byte[] tableName, HTableDescriptor htd)
          Modify an existing table, more IRB friendly version.
 void move(byte[] encodedRegionName, byte[] destServerName)
          Move the region r to dest.
 void shutdown()
          Shuts down the HBase cluster
 void split(byte[] tableNameOrRegionName)
          Split a table or an individual region.
 void split(byte[] tableNameOrRegionName, byte[] splitPoint)
          Split a table or an individual region.
 void split(String tableNameOrRegionName)
          Split a table or an individual region.
 void stopMaster()
          Shuts down the current HBase master only.
 void stopRegionServer(HServerAddress hsa)
          Stop the designated regionserver.
 boolean tableExists(byte[] tableName)
           
 boolean tableExists(String tableName)
           
 void unassign(byte[] regionName, boolean force)
          Unassign a region from current hosting regionserver.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HBaseAdmin

public HBaseAdmin(org.apache.hadoop.conf.Configuration c)
           throws MasterNotRunningException,
                  ZooKeeperConnectionException
Constructor

Parameters:
c - Configuration object
Throws:
MasterNotRunningException - if the master is not running
ZooKeeperConnectionException - if unable to connect to zookeeper
Method Detail

abort

public void abort(String why,
                  Throwable e)
Description copied from interface: Abortable
Abort the server or client.

Specified by:
abort in interface Abortable
Parameters:
why - Why we're aborting.
e - Throwable that caused abort. Can be null.

getConnection

public HConnection getConnection()
Returns:
HConnection used by this object.

getMaster

public HMasterInterface getMaster()
                           throws MasterNotRunningException,
                                  ZooKeeperConnectionException
Get a connection to the currently set master.

Returns:
proxy connection to master server for this instance
Throws:
MasterNotRunningException - if the master is not running
ZooKeeperConnectionException - if unable to connect to zookeeper

isMasterRunning

public boolean isMasterRunning()
                        throws MasterNotRunningException,
                               ZooKeeperConnectionException
Returns:
- true if the master server is running
Throws:
ZooKeeperConnectionException
MasterNotRunningException

tableExists

public boolean tableExists(String tableName)
                    throws IOException
Parameters:
tableName - Table to check.
Returns:
True if table exists already.
Throws:
IOException

tableExists

public boolean tableExists(byte[] tableName)
                    throws IOException
Parameters:
tableName - Table to check.
Returns:
True if table exists already.
Throws:
IOException

listTables

public HTableDescriptor[] listTables()
                              throws IOException
List all the userspace tables. In other words, scan the META table. If we wanted this to be really fast, we could implement a special catalog table that just contains table names and their descriptors. Right now, it only exists as part of the META table's region info.

Returns:
- returns an array of HTableDescriptors
Throws:
IOException - if a remote or network exception occurs

getTableDescriptor

public HTableDescriptor getTableDescriptor(byte[] tableName)
                                    throws IOException
Method for getting the tableDescriptor

Parameters:
tableName - as a byte []
Returns:
the tableDescriptor
Throws:
IOException - if a remote or network exception occurs

createTable

public void createTable(HTableDescriptor desc)
                 throws IOException
Creates a new table. Synchronous operation.

Parameters:
desc - table descriptor for table
Throws:
IllegalArgumentException - if the table name is reserved
MasterNotRunningException - if master is not running
TableExistsException - if table already exists (If concurrent threads, the table may have been created between test-for-existence and attempt-at-creation).
IOException - if a remote or network exception occurs

createTable

public void createTable(HTableDescriptor desc,
                        byte[] startKey,
                        byte[] endKey,
                        int numRegions)
                 throws IOException
Creates a new table with the specified number of regions. The start key specified will become the end key of the first region of the table, and the end key specified will become the start key of the last region of the table (the first region has a null start key and the last region has a null end key). BigInteger math will be used to divide the key range specified into enough segments to make the required number of total regions. Synchronous operation.

Parameters:
desc - table descriptor for table
startKey - beginning of key range
endKey - end of key range
numRegions - the total number of regions to create
Throws:
IllegalArgumentException - if the table name is reserved
MasterNotRunningException - if master is not running
TableExistsException - if table already exists (If concurrent threads, the table may have been created between test-for-existence and attempt-at-creation).
IOException

createTable

public void createTable(HTableDescriptor desc,
                        byte[][] splitKeys)
                 throws IOException
Creates a new table with an initial set of empty regions defined by the specified split keys. The total number of regions created will be the number of split keys plus one (the first region has a null start key and the last region has a null end key). Synchronous operation.

Parameters:
desc - table descriptor for table
splitKeys - array of split keys for the initial regions of the table
Throws:
IllegalArgumentException - if the table name is reserved
MasterNotRunningException - if master is not running
TableExistsException - if table already exists (If concurrent threads, the table may have been created between test-for-existence and attempt-at-creation).
IOException

createTableAsync

public void createTableAsync(HTableDescriptor desc,
                             byte[][] splitKeys)
                      throws IOException
Creates a new table but does not block and wait for it to come online. Asynchronous operation.

Parameters:
desc - table descriptor for table
Throws:
IllegalArgumentException - Bad table name.
MasterNotRunningException - if master is not running
TableExistsException - if table already exists (If concurrent threads, the table may have been created between test-for-existence and attempt-at-creation).
IOException

deleteTable

public void deleteTable(String tableName)
                 throws IOException
Deletes a table. Synchronous operation.

Parameters:
tableName - name of table to delete
Throws:
IOException - if a remote or network exception occurs

deleteTable

public void deleteTable(byte[] tableName)
                 throws IOException
Deletes a table. Synchronous operation.

Parameters:
tableName - name of table to delete
Throws:
IOException - if a remote or network exception occurs

enableTable

public void enableTable(String tableName)
                 throws IOException
Throws:
IOException

enableTable

public void enableTable(byte[] tableName)
                 throws IOException
Enable a table. May timeout. Use enableTableAsync(byte[]) and isTableEnabled(byte[]) instead.

Parameters:
tableName - name of the table
Throws:
IOException - if a remote or network exception occurs
See Also:
isTableEnabled(byte[]), disableTable(byte[]), enableTableAsync(byte[])

enableTableAsync

public void enableTableAsync(String tableName)
                      throws IOException
Throws:
IOException

enableTableAsync

public void enableTableAsync(byte[] tableName)
                      throws IOException
Brings a table on-line (enables it). Method returns immediately though enable of table may take some time to complete, especially if the table is large (All regions are opened as part of enabling process). Check isTableEnabled(byte[]) to learn when table is fully online. If table is taking too long to online, check server logs.

Parameters:
tableName -
Throws:
IOException
Since:
0.90.0

disableTableAsync

public void disableTableAsync(String tableName)
                       throws IOException
Throws:
IOException

disableTableAsync

public void disableTableAsync(byte[] tableName)
                       throws IOException
Starts the disable of a table. If it is being served, the master will tell the servers to stop serving it. This method returns immediately. The disable of a table can take some time if the table is large (all regions are closed as part of table disable operation). Call isTableDisabled(byte[]) to check for when disable completes. If table is taking too long to online, check server logs.

Parameters:
tableName - name of table
Throws:
IOException - if a remote or network exception occurs
Since:
0.90.0
See Also:
isTableDisabled(byte[]), isTableEnabled(byte[])

disableTable

public void disableTable(String tableName)
                  throws IOException
Throws:
IOException

disableTable

public void disableTable(byte[] tableName)
                  throws IOException
Disable table and wait on completion. May timeout eventually. Use disableTableAsync(byte[]) and isTableDisabled(String) instead.

Parameters:
tableName -
Throws:
IOException

isTableEnabled

public boolean isTableEnabled(String tableName)
                       throws IOException
Parameters:
tableName - name of table to check
Returns:
true if table is on-line
Throws:
IOException - if a remote or network exception occurs

isTableEnabled

public boolean isTableEnabled(byte[] tableName)
                       throws IOException
Parameters:
tableName - name of table to check
Returns:
true if table is on-line
Throws:
IOException - if a remote or network exception occurs

isTableDisabled

public boolean isTableDisabled(String tableName)
                        throws IOException
Parameters:
tableName - name of table to check
Returns:
true if table is off-line
Throws:
IOException - if a remote or network exception occurs

isTableDisabled

public boolean isTableDisabled(byte[] tableName)
                        throws IOException
Parameters:
tableName - name of table to check
Returns:
true if table is off-line
Throws:
IOException - if a remote or network exception occurs

isTableAvailable

public boolean isTableAvailable(byte[] tableName)
                         throws IOException
Parameters:
tableName - name of table to check
Returns:
true if all regions of the table are available
Throws:
IOException - if a remote or network exception occurs

isTableAvailable

public boolean isTableAvailable(String tableName)
                         throws IOException
Parameters:
tableName - name of table to check
Returns:
true if all regions of the table are available
Throws:
IOException - if a remote or network exception occurs

addColumn

public void addColumn(String tableName,
                      HColumnDescriptor column)
               throws IOException
Add a column to an existing table. Asynchronous operation.

Parameters:
tableName - name of the table to add column to
column - column descriptor of column to be added
Throws:
IOException - if a remote or network exception occurs

addColumn

public void addColumn(byte[] tableName,
                      HColumnDescriptor column)
               throws IOException
Add a column to an existing table. Asynchronous operation.

Parameters:
tableName - name of the table to add column to
column - column descriptor of column to be added
Throws:
IOException - if a remote or network exception occurs

deleteColumn

public void deleteColumn(String tableName,
                         String columnName)
                  throws IOException
Delete a column from a table. Asynchronous operation.

Parameters:
tableName - name of table
columnName - name of column to be deleted
Throws:
IOException - if a remote or network exception occurs

deleteColumn

public void deleteColumn(byte[] tableName,
                         byte[] columnName)
                  throws IOException
Delete a column from a table. Asynchronous operation.

Parameters:
tableName - name of table
columnName - name of column to be deleted
Throws:
IOException - if a remote or network exception occurs

modifyColumn

public void modifyColumn(String tableName,
                         String columnName,
                         HColumnDescriptor descriptor)
                  throws IOException
Deprecated. The columnName is redundant. Use addColumn(String, HColumnDescriptor)

Modify an existing column family on a table. Asynchronous operation.

Parameters:
tableName - name of table
columnName - name of column to be modified
descriptor - new column descriptor to use
Throws:
IOException - if a remote or network exception occurs

modifyColumn

public void modifyColumn(String tableName,
                         HColumnDescriptor descriptor)
                  throws IOException
Modify an existing column family on a table. Asynchronous operation.

Parameters:
tableName - name of table
descriptor - new column descriptor to use
Throws:
IOException - if a remote or network exception occurs

modifyColumn

public void modifyColumn(byte[] tableName,
                         byte[] columnName,
                         HColumnDescriptor descriptor)
                  throws IOException
Deprecated. The columnName is redundant. Use modifyColumn(byte[], HColumnDescriptor)

Modify an existing column family on a table. Asynchronous operation.

Parameters:
tableName - name of table
columnName - name of column to be modified
descriptor - new column descriptor to use
Throws:
IOException - if a remote or network exception occurs

modifyColumn

public void modifyColumn(byte[] tableName,
                         HColumnDescriptor descriptor)
                  throws IOException
Modify an existing column family on a table. Asynchronous operation.

Parameters:
tableName - name of table
descriptor - new column descriptor to use
Throws:
IOException - if a remote or network exception occurs

closeRegion

public void closeRegion(String regionname,
                        String hostAndPort)
                 throws IOException
Close a region. For expert-admins. Runs close on the regionserver. The master will not be informed of the close.

Parameters:
regionname - region name to close
hostAndPort - If supplied, we'll use this location rather than the one currently in .META.
Throws:
IOException - if a remote or network exception occurs

closeRegion

public void closeRegion(byte[] regionname,
                        String hostAndPort)
                 throws IOException
Close a region. For expert-admins Runs close on the regionserver. The master will not be informed of the close.

Parameters:
regionname - region name to close
hostAndPort - If supplied, we'll use this location rather than the one currently in .META.
Throws:
IOException - if a remote or network exception occurs

closeRegion

public void closeRegion(HServerAddress hsa,
                        HRegionInfo hri)
                 throws IOException
Throws:
IOException

flush

public void flush(String tableNameOrRegionName)
           throws IOException,
                  InterruptedException
Flush a table or an individual region. Asynchronous operation.

Parameters:
tableNameOrRegionName - table or region to flush
Throws:
IOException - if a remote or network exception occurs
InterruptedException

flush

public void flush(byte[] tableNameOrRegionName)
           throws IOException,
                  InterruptedException
Flush a table or an individual region. Asynchronous operation.

Parameters:
tableNameOrRegionName - table or region to flush
Throws:
IOException - if a remote or network exception occurs
InterruptedException

compact

public void compact(String tableNameOrRegionName)
             throws IOException,
                    InterruptedException
Compact a table or an individual region. Asynchronous operation.

Parameters:
tableNameOrRegionName - table or region to compact
Throws:
IOException - if a remote or network exception occurs
InterruptedException

compact

public void compact(byte[] tableNameOrRegionName)
             throws IOException,
                    InterruptedException
Compact a table or an individual region. Asynchronous operation.

Parameters:
tableNameOrRegionName - table or region to compact
Throws:
IOException - if a remote or network exception occurs
InterruptedException

majorCompact

public void majorCompact(String tableNameOrRegionName)
                  throws IOException,
                         InterruptedException
Major compact a table or an individual region. Asynchronous operation.

Parameters:
tableNameOrRegionName - table or region to major compact
Throws:
IOException - if a remote or network exception occurs
InterruptedException

majorCompact

public void majorCompact(byte[] tableNameOrRegionName)
                  throws IOException,
                         InterruptedException
Major compact a table or an individual region. Asynchronous operation.

Parameters:
tableNameOrRegionName - table or region to major compact
Throws:
IOException - if a remote or network exception occurs
InterruptedException

move

public void move(byte[] encodedRegionName,
                 byte[] destServerName)
          throws UnknownRegionException,
                 MasterNotRunningException,
                 ZooKeeperConnectionException
Move the region r to dest.

Parameters:
encodedRegionName - The encoded region name; i.e. the hash that makes up the region name suffix: e.g. if regionname is TestTable,0094429456,1289497600452.527db22f95c8a9e0116f0cc13c680396., then the encoded region name is: 527db22f95c8a9e0116f0cc13c680396.
destServerName - The servername of the destination regionserver. If passed the empty byte array we'll assign to a random server. A server name is made of host, port and startcode. Here is an example: host187.example.com,60020,1289493121758.
Throws:
UnknownRegionException - Thrown if we can't find a region named encodedRegionName
ZooKeeperConnectionException
MasterNotRunningException

assign

public void assign(byte[] regionName,
                   boolean force)
            throws MasterNotRunningException,
                   ZooKeeperConnectionException,
                   IOException
Parameters:
regionName - Region name to assign.
force - True to force assign.
Throws:
MasterNotRunningException
ZooKeeperConnectionException
IOException

unassign

public void unassign(byte[] regionName,
                     boolean force)
              throws MasterNotRunningException,
                     ZooKeeperConnectionException,
                     IOException
Unassign a region from current hosting regionserver. Region will then be assigned to a regionserver chosen at random. Region could be reassigned back to the same server. Use move(byte[], byte[]) if you want to control the region movement.

Parameters:
regionName - Region to unassign. Will clear any existing RegionPlan if one found.
force - If true, force unassign (Will remove region from regions-in-transition too if present).
Throws:
MasterNotRunningException
ZooKeeperConnectionException
IOException

balanceSwitch

public boolean balanceSwitch(boolean b)
                      throws MasterNotRunningException,
                             ZooKeeperConnectionException
Turn the load balancer on or off.

Parameters:
b - If true, enable balancer. If false, disable balancer.
Returns:
Previous balancer value
Throws:
MasterNotRunningException
ZooKeeperConnectionException

balancer

public boolean balancer()
                 throws MasterNotRunningException,
                        ZooKeeperConnectionException
Invoke the balancer. Will run the balancer and if regions to move, it will go ahead and do the reassignments. Can NOT run for various reasons. Check logs.

Returns:
True if balancer ran, false otherwise.
Throws:
MasterNotRunningException
ZooKeeperConnectionException

split

public void split(String tableNameOrRegionName)
           throws IOException,
                  InterruptedException
Split a table or an individual region. Asynchronous operation.

Parameters:
tableNameOrRegionName - table or region to split
Throws:
IOException - if a remote or network exception occurs
InterruptedException

split

public void split(byte[] tableNameOrRegionName)
           throws IOException,
                  InterruptedException
Split a table or an individual region. Implicitly finds an optimal split point. Asynchronous operation.

Parameters:
tableNameOrRegionName - table to region to split
Throws:
IOException - if a remote or network exception occurs
InterruptedException

split

public void split(byte[] tableNameOrRegionName,
                  byte[] splitPoint)
           throws IOException,
                  InterruptedException
Split a table or an individual region. Asynchronous operation.

Parameters:
tableNameOrRegionName - table to region to split
splitPoint - the explicit position to split on
Throws:
IOException - if a remote or network exception occurs
InterruptedException - interrupt exception occurred

modifyTable

public void modifyTable(byte[] tableName,
                        HTableDescriptor htd)
                 throws IOException
Modify an existing table, more IRB friendly version. Asynchronous operation. This means that it may be a while before your schema change is updated across all of the table.

Parameters:
tableName - name of table.
htd - modified description of the table
Throws:
IOException - if a remote or network exception occurs

shutdown

public void shutdown()
              throws IOException
Shuts down the HBase cluster

Throws:
IOException - if a remote or network exception occurs

stopMaster

public void stopMaster()
                throws IOException
Shuts down the current HBase master only. Does not shutdown the cluster.

Throws:
IOException - if a remote or network exception occurs
See Also:
shutdown()

stopRegionServer

public void stopRegionServer(HServerAddress hsa)
                      throws IOException
Stop the designated regionserver.

Throws:
IOException - if a remote or network exception occurs

getClusterStatus

public ClusterStatus getClusterStatus()
                               throws IOException
Returns:
cluster status
Throws:
IOException - if a remote or network exception occurs

getConfiguration

public org.apache.hadoop.conf.Configuration getConfiguration()
Returns:
Configuration used by the instance.

checkHBaseAvailable

public static void checkHBaseAvailable(org.apache.hadoop.conf.Configuration conf)
                                throws MasterNotRunningException,
                                       ZooKeeperConnectionException
Check to see if HBase is running. Throw an exception if not.

Parameters:
conf - system configuration
Throws:
MasterNotRunningException - if the master is not running
ZooKeeperConnectionException - if unable to connect to zookeeper


Copyright © 2011 The Apache Software Foundation. All Rights Reserved.