Havenask on a single container: the ha3_runtime path from table to query

What the README claims, and for whom

Havenask is described as a large-scale distributed information search system used inside Alibaba Group for Taobao, Tmall, Cainiao, Amap, Ele.me and global services. The stated capability envelope is hundreds of billions of records with millions of QPS and millions of TPS, queries in milliseconds and data updates in seconds. Those are vendor claims about a production environment you do not have; treat them as positioning, not as a benchmark.

The audience is teams who want to own their search index. The engine is written in C++ and the README attributes performance and memory behaviour to that choice. It offers SQL as the query surface, a plugin mechanism for business-specific logic, and a graphical development path for iterating on algorithms. It also mentions vector retrieval through plugins for multimodal search, and an `llm/` directory for document question answering built with a large language model.

Licensing is Apache-2.0, which is the friendliest of the common choices for a commercial deployment and carries the usual obligation to keep the licence text and notices.

Two images decide whether you compile anything

Docker images are published for the amd64 platform only, and the split between them is the first decision. `ha3_runtime` holds the engine executables so a search service starts without a compilation step. `ha3_dev` adds the dependency libraries and headers needed to build the source, and the README points at the QuickStart page in the wiki for how to compile there.

The resource floors are explicit. Runtime wants more than 2 CPU cores, more than 4G of memory and more than 20G of disk. Development raises memory to more than 10G and disk to more than 50G. Docker has to be installed and running, and single-machine local mode expects that the machine can ssh to itself without a passphrase, which the wiki covers under Local Mode.

The repository itself is a bazel monorepo: `WORKSPACE`, `BUILD`, `build.sh`, `.bazelrc`, and directories for `aios/`, `integration_test/`, `third_party/` and `package/`. That shape is a reasonable read on how the project is developed, and a warning about how you consume it.

Bringing up a container in three commands

The startup path is short enough to follow exactly. First fetch the helper and the runtime image, then run the helper with your container name and the image reference:

wget https://github.com/alibaba/havenask/releases/download/v1.2.0/create_container.sh
docker pull registry.cn-hangzhou.aliyuncs.com/havenask/ha3_runtime:latest
./create_container.sh <CONTAINER_NAME> registry.cn-hangzhou.aliyuncs.com/havenask/ha3_runtime:latest

The script URL is pinned to the v1.2.0 release while the image tag is `:latest`, so the script and the image can drift apart over time. If a later run behaves differently from the wiki, that mismatch is the first thing to check.

Inside the container, everything is driven by two tools. `hape` manages the service lifecycle:

./<CONTAINER_NAME>/sshme
/ha3_install/hape start havenask

And the table is defined by a schema file that the create command reads:

/ha3_install/hape create table -t in0 -s /ha3_install/example/cases/normal/in0_schema.json -p 1

The `-t` flag names the table, `-s` points at the schema JSON and `-p 1` sets the partition count in this example.

Writing and reading through sql_query.py

Data goes in and comes out through the same script, which is the clearest sign that SQL really is the interface rather than a wrapper around something else. The README inserts one row:

/ha3_install/sql_query.py --query "insert into in0 (createtime,hits,id,title,subject)values(1,2,4,'test', 'test')"

and reads it back:

/ha3_install/sql_query.py --query "select * from in0"

A first session should end with that select returning the row just inserted. If it returns nothing, the useful first checks are whether `hape start havenask` actually started the service and whether the table was created against the schema you expected.

What the README does not document is where the runtime image is published outside Aliyun's registry, how upgrades move data between versions, or what a rollback looks like after a schema change. Those gaps are worth resolving against the wiki before anything production-shaped goes on this engine.

Where it is the wrong tool

Several boundaries follow from the README and the repository layout. There is no single-node story for a laptop with 4G of spare memory, and local mode has an ssh prerequisite that is awkward inside some container and CI environments. There is no documented rollback procedure. And the plugin mechanism, while presented as an extension point, means custom relevance logic is C++ or plugin work rather than configuration.

The branch history is a separate hazard. The README notes that the new and old main branches differ significantly and that code synced across branches can fail to build, with older trees kept at tags `1.1.0`, `1.0.0`, `1.0.0-beta` and `main-stable-0.4`. Anyone carrying a patch will hit that.

Compared with putting the same documents into an inverted index you manage yourself, Havenask trades operational simplicity for scale headroom and a query language that most analysts already know. For a corpus that fits comfortably on one machine, that trade rarely pays.

Editorial conclusion

Adopt Havenask if your workload needs a self hosted search index with SQL querying and you have the hardware and the patience for a C++ engine that ships as a bazel monorepo rather than a tidy package, because the runtime image gets you to a working table and query without a compiler. Do not adopt it on the strength of the throughput figures in the README, which describe Alibaba internal scale, not a measurement you can reproduce. Before anything else, run the v1.2.0 create_container.sh path on a machine matching the stated requirements of more than 2 CPU cores, more than 4G of memory and more than 20G of disk, and confirm the passphrase-free localhost ssh that local mode requires.

Frequently asked questions

Official sources

1. alibaba/havenask on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases