Public API reference¶

Documentation home · Cookbook · Known limitations

This reference describes the current high-level implementation, not every legacy module or full Java API parity. Types shown are runtime result shapes; the source has some incomplete annotations/docstrings. All contextual examples assume the named objects already exist.

Imports and naming¶

from hbasedriver.client.client import Client
from hbasedriver.common.table_name import TableName
from hbasedriver.hbase_constants import HConstants
from hbasedriver.operations.get import Get
from hbasedriver.operations.put import Put
from hbasedriver.operations.delete import Delete
from hbasedriver.operations.scan import Scan
from hbasedriver.operations.column_family_builder import ColumnFamilyDescriptorBuilder

name = TableName.value_of(b"default", b"users")
family_schema = ColumnFamilyDescriptorBuilder(b"cf").build()

TableName takes namespace and qualifier, not one combined name. Use the common TableName consistently for administration. Row keys, families, qualifiers, and values in operation objects are bytes. Text requires explicit encoding.

Client¶

Client(conf: dict) connects during construction. Configure HConstants.ZOOKEEPER_QUORUM explicitly. See configuration for defaults and network requirements.

Method	Return / role
`get_table(ns, tb)`	Table; namespace may be None for default
`get_admin()`	Admin
`get_buffered_mutator(ns, tb, params=None)`	BufferedMutator with an internally created Table
`locate_region(table_name, row)`	Host/port pair; not a RegionLocator object
`close()`	Requests cleanup
`__enter__ / __exit__`	Context-manager support

Prefer the Admin facade for schema operations. There is no public get_region_locator() on this Client. Closing the factory-created mutator does not close its Table; for clear ownership, construct BufferedMutator(table, params) yourself.

Table and Row¶

Method	Return
`put(put)`	bool
`get(get)`	Row or None
`delete(delete)`	bool
`exists(get)`	bool; changes the Get's existence-only flag
`exists_all(gets)`	`dict[bytes, bool]`
`scan(scan)` / `get_scanner(scan)`	ResultScanner
`scan_page(scan, page_size)`	`tuple[list[Row], bytes or None]`
`batch_get(batch_get)`	`dict[bytes, Row or None]`
`batch_put(batch_put)`	`list[bool]`
`batch(batch_size=1000)`	Batch context
`increment(increment)`	One decoded int, not a mapping of all columns
`check_and_put(check_and_put)`	bool: whether condition passed
`check_and_delete(rowkey, check_family, check_qualifier, check_value, delete, compare_op="EQUAL")`	bool
`append(append)`	Row or None
`mutate_row(row_mutations)`	bool
`get_pool_stats()`	Diagnostic dictionary
`invalidate_cache()`	Clears Table's Region cache only
`close()`	Cleanup request, also affects attached shared connection state

Row.rowkey is bytes; Row.kv is dict[bytes, dict[bytes, bytes]]; row.get(family, qualifier) returns bytes or None. Rows do not expose complete version history or timestamps.

row = table.get(Get(b"user:001").add_column(b"cf", b"name"))
if row is not None:
    value = row.get(b"cf", b"name")
    if value is not None:
        print(value.decode("utf-8"))

Distinguish None from b"". See data model for encoding and counters.

Put and Get¶

Put(rowkey).add_column(family, qualifier, value, ts=None) is chainable.
Get(rowkey).add_column(family, qualifier) and add_family(family) are chainable.
Get.read_versions(n) and Get.set_filter(filter) return None.
Get.set_time_range(min_ts, max_ts) and set_time_stamp(ts) exist but finite time bounds currently fail in the RPC path.
Get.set_filter() stores a filter that the current Get request does not send.
Setting multiple versions does not change Row's flattened result representation.

Do not infer fluent chaining from a method's name. Do not rely on time/filter/version semantics without the limitations.

Delete¶

Delete(rowkey) with no added columns deletes the whole row. These methods are chainable:

Method	Intent
`add_column(family, qualifier, ts=None)`	One version of a cell
`add_columns(family, qualifier, ts)`	Versions through the supplied timestamp; ts is required
`add_family(family, ts=None)`	Family delete marker
`add_family_version(family, ts=None)`	Family-version delete marker

Timestamps are HBase millisecond timestamps. These are destructive operations; establish retention/version expectations with your actual table schema.

Scan and ResultScanner¶

Constructor: Scan(start_row=b"", end_row=b""). Both bounds default to inclusive. Supported construction patterns:

scan = (
    Scan(start_row=b"user:")
    .with_end_row(b"user;", inclusive=False)
    .add_family(b"cf")
)

Method	Notes
`with_start_row(key, inclusive=True)`	Use False when resuming after a row
`with_end_row(key, inclusive=True)`	Use False for a half-open interval
`add_family(family)`	Select all qualifiers in a family
`set_filter(filter)`	Server-side Scan filter
`add_column(family, qualifier)`	Present, but bytes qualifier serialization currently fails
`set_limit(n)`	Present, but not a global cap in Table/ResultScanner
`set_time_range(min_stamp, max_stamp)`	Bounds currently omitted from protobuf
`setCaching(n)`, `setBatch(n)`, `setMaxResultSize(n)`	Java-style settings; not guarantees of Java execution behavior
`setReversed(flag)`, `setAllowPartialResults(flag)`	Require separate topology/wide-row validation

ResultScanner is iterable; next(scanner) returns one Row and eventually raises StopIteration. scanner.next_batch(n) returns up to n rows, then an empty list at exhaustion; calling it on a closed scanner raises StopIteration. Close the scanner after early termination.

scan_page() returns the last key for every nonempty page. A resume key is not proof of a next page. See advanced usage.

Filters¶

Import filters from hbasedriver.filter. Common constructors:

PrefixFilter(prefix)
QualifierFilter(compare_operator, comparator)
ColumnPrefixFilter(prefix)
SingleColumnValueFilter(column_family, column_qualifier, compare_operator, comparator, filter_if_missing=False, latest_version_only=False)
FilterList(operator=None, filters=None)
BinaryComparator(value)

Use CompareOperator.EQUAL for equality and FilterList.Operator.MUST_PASS_ALL / MUST_PASS_ONE for AND/OR. Set SingleColumnValueFilter options in the constructor. A working composition is in the cookbook.

Batch APIs¶

from hbasedriver.operations.batch import BatchGet, BatchPut

writes = BatchPut()
writes.add_put(Put(b"batch:1").add_column(b"cf", b"value", b"A"))
statuses = table.batch_put(writes)

reads = BatchGet([b"batch:1", b"absent"])
reads.add_column(b"cf", b"value")  # Do not chain: returns None.
results = table.batch_get(reads)
for key, row in results.items():
    print(key, None if row is None else row.kv)

BatchPut also has add_puts(list_of_puts). BatchGet has add_family, set_max_versions, set_time_range, and set_check_existence_only; underlying Get limitations still apply. Dictionary results cannot preserve repeated input keys.

The convenience Batch accepts flat family-qualified names:

with table.batch(batch_size=100) as batch:
    batch.put(b"batch:2", {b"cf:value": b"B"})
    batch.delete(b"batch:old", columns=[b"cf:value"])

These APIs use sequential requests. Batch may flush before the context ends; an exception does not roll back prior writes or make cross-row ordering transactional.

Atomic operations¶

from hbasedriver.operations.increment import Increment, CheckAndPut
from hbasedriver.operations.append import Append
from hbasedriver.operations.row_mutations import RowMutations

count = table.increment(Increment(b"counter:1").add_column(b"cf", b"count", 1))
claim = CheckAndPut(b"job:1")
claim.set_check(b"cf", b"state", None)  # None means absent, not empty bytes.
claim.set_put(Put(b"job:1").add_column(b"cf", b"state", b"claimed"))
accepted = table.check_and_put(claim)

Increment's add_column(family, qualifier, amount=1) accepts an int. Its set_return_results(flag) controls returned results; the Table wrapper returns only one decoded value (or 0 when no result is available), so use one counter when the return value matters.

Append's add_column(family, qualifier, value, ts=None) appends bytes; set_return_results(flag) controls whether a Row is requested. RowMutations(rowkey).add(mutation) validates the row key and accepts Put, Delete, Increment, or Append. The documentation recipe validates Put+Delete, not every possible combination. Never blindly replay a non-idempotent mutation after an unknown result.

The public conditional-delete call is the Table method shown above; do not assume a separate operation object with a Java constructor. Keep the Delete and condition on the same row.

BufferedMutator¶

Import BufferedMutator, BufferedMutatorParams, and optionally ExceptionListener from hbasedriver.client.buffered_mutator.

Constructor: BufferedMutator(table, params=None). Params takes no arguments; defaults:

Attribute	Default	Unit
`write_buffer_size`	2 × 1024 × 1024	estimated bytes; mutator enforces at least 64 KiB
`write_buffer_periodic_flush`	3000	milliseconds; 0 disables background flush
`max_key_value_size`	-1	bytes; negative disables the check

Methods: mutate(Put_or_Delete), mutate_all(mutations), flush(), close(), get_write_buffer_size(), set_write_buffer_size(size), get_current_buffer_size(), get_current_buffer_size_mutations(), set_exception_listener(listener), and get_exception_listener().

The listener's on_exception(mutation, exc) returns a bool; True continues processing rather than retrying the failed mutation. Background errors can surface on a later operation. Do not use a listener to silently discard write errors. Closing flushes pending work but does not close the supplied Table. See buffering and failures.

Administration¶

Use client.get_admin() and common TableName objects.

Group	Methods
Tables	`create_table(table_name, column_families, split_keys=None)`, `disable_table(table_name, timeout=60)`, `enable_table(table_name, timeout=60)`, `delete_table(table_name)`
Inspection	`table_exists`, `is_table_enabled`, `is_table_disabled`, `describe_table`, `list_tables(pattern=".*", include_sys_tables=False)`
Families	`add_column_family`, `modify_column_family`, `delete_column_family`
Namespaces	`create_namespace`, `delete_namespace`, `list_namespaces`
Snapshots	`create_snapshot`, `list_snapshots`, `snapshot_exists`, `delete_snapshot`, `restore_snapshot`, `clone_snapshot`
Regions	`split_region`, `merge_regions`, `assign_region`, `unassign_region`
Cluster	`get_cluster_status`, `list_region_servers`, `balance`, `set_balancer`, `is_balancer_enabled`

truncate_table() is destructive delete/recreate with incomplete split/metadata preservation. Snapshot and Region requests can be asynchronous. See administration guide for return values, prerequisites, safe lifecycle, and verification boundaries.

list_tables() and describe_table() return protobuf GetTableDescriptorsResponse objects. Iterate response.table_schema; for a single described table, inspect the first entry after checking the sequence is nonempty. Column families are on that entry's column_families, not directly on the response.

Errors and cleanup¶

Do not assume every low-level failure is translated into the high-level exception hierarchy. Protobuf errors, network exceptions, and server RemoteException instances may propagate. Context managers request cleanup but do not provide rollback or a guarantee that every low-level resource is released. See troubleshooting before choosing retry behavior.