Skip to content

Getting started

Documentation index · 中文使用手册

1. Install

A virtual environment is optional. Install into your existing Python environment:

python -m pip install hbase-driver
python -c "from hbasedriver.client.client import Client; print('import OK')"

If you prefer dependency isolation, create and activate a venv before installation. Use Python 3.10+; the project's verified development runtime is Python 3.11. kazoo and protobuf are runtime dependencies installed by pip. The import check does not contact a cluster.

For the source checkout used by these docs:

git clone https://github.com/innovationb1ue/hbase-driver.git
cd hbase-driver
python -m pip install -e .

See configuration for network requirements and limitations before connecting to a production cluster.

2. Choose the correct ZooKeeper address

  • Local HBase: usually 127.0.0.1:2181.
  • This project's hbase_dev container: hbase-zk:2181.
  • Remote cluster: addresses supplied by the cluster administrator, such as zk1:2181,zk2:2181.

ZooKeeper is only the discovery endpoint. The client must also resolve and reach the Master and RegionServer hostnames it returns. Forwarding port 2181 alone is not sufficient.

The examples read HBASE_ZK explicitly; the driver itself does not automatically read that environment variable.

3. Run the safe end-to-end example

Copy the script from the complete example into a local file named docs_quickstart.py. From the directory where you saved it:

# Inside the project's development container, HBASE_ZK is already configured.
python docs_quickstart.py

Or save that local scratch file in the checkout, start the existing project containers, and run there (keep the scratch file untracked):

docker compose up -d
docker compose exec -T dev python docs_quickstart.py

The example creates a unique default:docs_demo_* table with a cf family. It demonstrates text, Get/Put/Delete, filters, batch operations, counters, conditional writes, and buffered writes. It verifies results and removes only its own table in finally after successful creation. It never deletes a pre-existing table. Importing the script does not run it. JSON, pagination, Append, and RowMutations are covered by the cookbook.

Expected final output starts with Core examples passed; removed default:docs_demo_ followed by the unique name. A successful import alone is not this integration check. If creation times out, inspect the printed table name before cleanup: the server may have created it despite the error.

4. Connect to an existing table

Precondition: default:mytable exists, is enabled, and contains a cf family. This example writes one test row and leaves it in the table.

import os

from hbasedriver.client.client import Client
from hbasedriver.operations.get import Get
from hbasedriver.operations.put import Put

config = {"hbase.zookeeper.quorum": os.getenv("HBASE_ZK", "127.0.0.1:2181")}
with Client(config) as client:
    with client.get_table(b"default", b"mytable") as table:
        table.put(Put(b"user:1001").add_column(b"cf", b"name", "张三".encode("utf-8")))
        row = table.get(Get(b"user:1001").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"))

Get returns None when no cells match. A present row can still lack the requested column. b"" is a value, not the same as None.

5. Learn the next operation

  • Need to create a table? Read administration.
  • Need a page of results or a prefix query? Use cookbook examples, not SQL OFFSET pagination.
  • Need a full signature or return type? See API reference.
  • Need to stop containers started for testing? Run docker compose stop; do not remove volumes unless you intentionally want to erase cluster data.