antfly

Hybrid search — full-text (BM25), dense vectors (RaBitQ-compressed with SPFresh-style updates), and sparse vectors (SPLADE), fused with reciprocal rank or relative score fusion in one query

Automatically checked · GitHub checked 2026-11-14

antfly

Overview

Antfly

Antfly is an open-source search-and-inference database written in Zig. One engine carries full-text (BM25), dense, and sparse vector indexes plus graph traversal over the same table, and the models that chunk, embed, rerank, transcribe, OCR, and extract run inside the process. Embeddings, chunks, entities, and graph edges are generated automatically as you write data, and built-in RAG agents tie it together. The same engine runs as a single .aflite file, a single node with a hot standby, a multi-Raft cluster, or serverless over object storage.

Quickstart

Recording source · Recording instructions

Quick Start

# Install the CLI (macOS and Linux), then start a single node with built-in ML inference
curl -fsSL https://releases.antfly.io/antfly/latest/install.sh | sh
antfly standalone

# Or with Homebrew (macOS or Linux)
brew install antflydb/taps/antfly

# Or build from source
make build && ./antfly standalone

# Or run with Docker
docker run -p 127.0.0.1:8080:8080 ghcr.io/antflydb/antfly:latest standalone --host 0.0.0.0

For production, configure and verify the process open-file limit (recommended: 65,536; supported minimum: 256).

These quickstarts run without authentication and are intended for local development. Keep Docker ports bound to loopback. Before allowing remote access, enable authentication and provision a unique admin password, then configure TLS at a reverse proxy.

That gives you the Antfarm dashboard at http://localhost:8080 — playgrounds for search, RAG, knowledge graphs, embeddings, reranking, and more.

See the quickstart guide for a full walkthrough.

One CLI, an embeddable library

The antfly CLI runs the server, manages local database files, and runs inference:

antfly standalone
antfly lite init app.aflite
antfly lite query app.aflite --file query.json
antfly inference pull <model>
antfly inference chat <model>
antfly inference run

Antfly Lite embeds the same database and inference engine through libantfly, Zig, Go, Python, Rust, TypeScript, or browser WASM. Language packages retain the antfly-embedded / @antfly/embedded names to distinguish in-process bindings from the HTTP SDKs. They do not install CLI commands.

The antfly-embedded native archive contains libantfly, include/antfly.h, relocatable lib/pkgconfig/libantfly.pc metadata, runtime assets, and notices. It contains no executable. Go, Rust, and C consumers can link this library; Python and npm platform packages bundle it. Install the CLI separately to use antfly lite or antfly inference.

Build both surfaces, or just the library, from source:

cd zig
zig build release                         # antfly + libantfly
./zig-out/bin/antfly lite init app.aflite
zig build --build-file embedded.build.zig libantfly  # library without server sources

Zig applications can also fetch the independent antfly-embedded-source_<version>.tar.gz package; see the Zig package guide. Select only assets listed for the release you install: earlier archives retain their recorded layouts. See LICENSING.md for third-party notices and source ownership.

Features

  • Hybrid search — full-text (BM25), dense vectors (RaBitQ-compressed with SPFresh-style updates), and sparse vectors (SPLADE), fused with reciprocal rank or relative score fusion in one query
  • Full-text search — Lucene-style segments with highlighting, geo, regex, wildcard, and fuzzy queries, plus English and ten Snowball stemmer languages
  • RAG agents — built-in retrieval-augmented generation with streaming, multi-turn chat, tool calling (graph traversal, plus web search through an Exa connection), confidence scoring, and TOON document rendering to cut prompt tokens
  • Query-builder agent — turns a natural-language question into a structured Antfly query
  • Graph indexes — automatic relationship extraction and graph traversal over your data
  • Multimodal — index and search images, audio, and video in one vector space with EmbeddingGemma 2
  • Reranking — cross-encoder and late-interaction (ColBERT, ColQwen2) reranking with score-based pruning to cut the noise
  • Aggregations — stats, terms facets, histogram, date histogram, range, and geo-distance aggregations for analytics
  • Transactions — ACID transactions at the shard level with distributed coordination
  • Document TTL — automatic document expiration so you don't have to clean up yourself
  • PostgreSQL CDC — mirror a Postgres table into Antfly over logical replication, every insert, update, and delete included
  • CLI — one antfly binary for the server, tables, queries, backups, auth, and the model registry (antfly inference pull owner/model)
  • Secrets — reference credentials as ${secret:...} keystore entries or env vars instead of putting them in config
  • Object storage — the serverless engine (in progress) keeps artifacts, manifests, WAL, and catalog state in S3-compatible storage (S3, MinIO, R2) or Google Cloud Storage
  • CPU, Metal, and CUDA — native kernels for inference and vector search: SIMD on x86 and ARM, Metal on Apple silicon, and CUDA with kernels generated at build time and shipped as fatbins, plus an opt-in runtime kernel JIT for Metal and CUDA (ANTFLY_INFERENCE_KERNEL_JIT_MODE, off by default)
  • Distributed — multi-Raft consensus, key-range sharding and replication, online shard splits (automatic size-based split and merge is opt-in), cross-shard transactions, horizontal scaling
  • Runs anywhere — Antfly Lite as a single .aflite file, a single node with a hot standby, a Raft cluster, or serverless over object storage (in progress)
  • Embeddable — a C API (libantfly), embedded bindings for Go, Python, Rust, and TypeScript, and an in-browser WASM build so the engine runs in-process, in unit tests, or on the edge
  • Extensions — run your own code inside the engine with the Wasmtime extension runtime
  • Enrichment pipelines — configurable pipelines per index for embeddings, summaries, graph edges, and custom computed fields
  • Bring your own models — Ollama, OpenAI, OpenRouter, Cohere, Bedrock, Gemini, Vertex AI, or run models locally with Antfly inference (GGUF, safetensors, and ONNX)
  • Fine-tuning — LoRA, QLoRA, SFT, DPO, GRPO and more with recipes for Gemma 4, GLiNER2, ColQwen2, LayoutLMv3, rerankers, and chunkers
  • Auth — built-in user management with API keys, basic auth, and bearer tokens
  • Backup & restore — portable backups to local disk, S3, or Google Cloud Storage
  • Self-hosting examples — deploy with Docker Compose or Kubernetes manifests
  • MCP and A2A protocols — protocol adapters let agents and LLMs use Antfly directly, and an n8n guide wires it into workflows
  • Relational tables — storage_mode: relational tables with typed packed rows, relational indexes, row query and mutate APIs, databases, a system catalog, and tablespaces
  • Antfarm — web dashboard with playgrounds for search, RAG, chat, knowledge graphs, embeddings, reranking, chunking, extraction, OCR, transcription, and evals
  • SQL and the Postgres wire protocol — SQL lowered to native typed plans and an opt-in psql-compatible server with transactions, prepared statements, and cursors
  • Lake tables — query read-only Parquet and Iceberg data in object storage in place, with search indexes stored alongside it

Documentation

antfly.io/docs, or the source under docs/. Good starting points:

Prefer not to run it yourself? Antfly Cloud is the hosted option.

SDKs & Client Libraries

LanguagePackageSource
Gogithub.com/antflydb/antfly/go/pkg/sdkgo/pkg/sdk
TypeScript@antfly/sdkts/packages/sdk
Pythonantfly-sdk (import antfly)py/packages/sdk
Rustantfly-sdkrs/crates/sdk
React@antfly/componentsts/packages/components
PostgreSQLantfly-postgres (SQL: antfly_postgres)rs/crates/postgres

antfly-postgres — PostgreSQL Extension

antfly-postgres brings Antfly search into Postgres. The Cargo package is antfly-postgres; the PostgreSQL extension and query-builder schema are antfly_postgres. Enable the extension, create an index, and use the @@@ operator:

CREATE EXTENSION antfly_postgres;

CREATE INDEX idx_content ON docs USING antfly (content)
  WITH (url = 'http://localhost:8080/db/v1/', collection = 'my_docs');

SELECT * FROM docs WHERE content @@@ 'fix my computer';

React Components

@antfly/components gives you drop-in React components for search UIs — QueryBox, Autosuggest, Facet, ActiveFilters, Results, Pagination, AnswerResults, AnswerFeedback, ChatBar, and ChatMessages, plus streaming hooks like useAnswerStream, useChatStream, useCitations, and useSearchHistory.

Inference Runtime

Antfly inference handles the ML side: embeddings, chunking, reranking, classification, NER, OCR, transcription, generation, and more. The runtime runs in-process through libantfly, through antfly inference commands, or as an inference service with antfly inference run. Standalone database mode includes inference.

Libraries & Tools

PackageWhat it doesSource
docsafIngest content from the filesystem, web crawls and sitemaps, git repos, S3, and Google Drivego/pkg/docsaf
Genkit pluginFirebase Genkit integration for retrieval and docstorego/pkg/genkit/antfly
Native memoryEvidence-backed temporal agent memory over HTTP, MCP and embedded APIsDesign and contracts
embeddedGo, Python, Rust, and TypeScript bindings for local databases and inference over the C ABIgo/pkg/embedded, py/packages/embedded, rs/crates/embedded, ts/packages/embedded

Architecture

The distributed database server uses a multi-Raft design with separate consensus groups:

  • Metadata raft — table schemas, shard assignments, cluster topology
  • Storage rafts — one per shard, handling data, indexes, and queries

The runtime includes our own Raft, LSM, WAL, full-text search, HTTP/2 and HTTP/3, and inference implementations. The repository also maintains a standalone Zig LMDB-compatible B+tree and a vendored C LMDB oracle for compatibility testing; neither is a production storage backend. Bundled and adapted third-party code retains its original licenses; see THIRD_PARTY_NOTICES.md. Our Snowball fork generates the checked-in stemmer tables. The engine runs under a deterministic VOPR simulation harness that injects storage, network, concurrency, and clock faults, in the style of TigerBeetle.

End-to-end chaos tests — inspired by Jepsen — cover node crashes, leader failures, shard splits under load, and cluster scaling. These tests run real multi-node clusters and inject faults to verify that Raft consensus, transactions, and replication behave correctly under failure.

Critical distributed protocols are formally specified, model-checked, and trace-validated with TLA+ under zig/specs/tla:

Community

Join the Discord for support, discussion, and updates.

Interested in contributing? See CONTRIBUTING.md.

License

All first-party Antfly code, including the database server, distributed and serverless runtime, embedded engine, inference, CLI, SDKs, and bindings, is Apache-2.0. Third-party components retain their original licenses. See LICENSING.md and THIRD_PARTY_NOTICES.md.