Glossary

Antfly Concepts#

Antfly Inference#

The model runtime built into Antfly. It runs embedding, chunking, reranking, extraction, transcription, and generation models from GGUF, safetensors, and ONNX artifacts on native CPU, Metal, and CUDA backends, plus experimental PJRT/XLA and WASM/WebGPU backends. Standalone serves it in-process under /ai/v1; antfly inference run runs it as a separate process that a database reaches through inference.api_url.

See: Antfly Inference | Local Model Compatibility

CDC & Foreign Sources#

Two ways to work with an external PostgreSQL table. CDC (replication_sources on a table) uses logical replication to stream inserts, updates, and deletes into canonical Antfly storage. Foreign sources (foreign_sources on a query) read or join the external table at request time without ingesting it, and support only filters, field selection, and paging.

See: Mirror a PostgreSQL Table | CDC design

Document Extraction#

The document_extraction asset producer downloads a document URL during enrichment and persists derived units such as PDF pages and chunks. PDF pages with no native text use OCR by default with the local antflydb/Florence-2-base model. Set ocr_fallback to false or ocr.enabled to false to opt out. This durable ingestion path is distinct from template helpers such as remoteMedia, which prepare media for inference without persisting page artifacts.

Enrichments, Artifacts & Asset Producers#

An enrichment is a named producer that generates and maintains artifacts, durable outputs attached to a document and exposed under _artifacts. Enrichment kinds are chunk, asset, and embedding. Summaries, extraction, OCR, transcription, and decisions are all asset artifacts made by an asset producer (copy, generator, extractor, decision, reader, transcriber, or document_extraction), and indexes can consume artifact streams as sources.

See: Artifact Indexes | Artifacts design | Enrichments design

Lake Tables#

In progress. Lake query mode serves Parquet datasets and Iceberg tables that stay in your object storage through the same relational row plans, pushing predicates and projections down into file reads instead of copying every row into Antfly. It ships with the SQL work tracked in #145.

See: Lake design | Remote table serving

Relational Tables#

A second table profile on the same engine. The schema is required and closed, and every declared scalar property becomes a typed column, so predicates, sorts, and aggregations run columnar. The relational index type adds composite ordered keys on these tables.

See: Relational mode design

remotePDF (deprecated)#

remotePDF is a deprecated Handlebars helper retained for compatibility. Use remoteMedia for template-time multimodal inference, or document_extraction when PDF pages and chunks should be durable and reprocessable.

SQL & pgwire#

In progress. SQL is lowered to Antfly's native typed plans, and an optional PostgreSQL wire-protocol (pgwire) listener lets psql-compatible clients connect. Tracked in #145.

See: SQL design | pgwire transport

sync_level#

How long a batch write waits before returning: propose (Raft proposal accepted, the default), write (durably applied to the local store), full_text (full-text index WAL written), enrichments (enrichments precomputed before commit; a synchronous producer failure rejects the write), or full_index (all index writes complete).

Templates#

Handlebars templates turn a document into the text or media that a model sees, for embedders, rerankers, and enrichments. Built-in helpers include scrubHtml, eq, media, remoteMedia (download a URL into a media part, such as an image), and remoteText (fetch a URL's text), with downloads guarded by host allowlists, private-IP blocking, and size limits.

See: Multimodal Embeddings | Handlebars

Transforms#

In-place document updates with MongoDB-style operators ($set, $setOnInsert, $unset, $inc, $push, $pull, $addToSet, $min, $max), sent in the transforms array of a batch. They apply atomically at the storage layer, which avoids read-modify-write races, but results are not validated against the table schema.

AI & Machine Learning#

Agent#

An autonomous AI system that can plan, reason, and take actions to accomplish goals. Antfly has three native agents: the Retrieval Agent (POST /agents/retrieval) for retrieval, tool selection, and generation; the Query Builder Agent (POST /agents/query-builder) for turning natural language into executable Antfly queries; and the Research Agent (POST /agents/research, with durable runs under /agents/research/jobs) for cited long-form reports. Agents may use tools and operate over multiple bounded steps, and A2A exposes them to other agents.

See: Write a Cited Research Report | ReAct: Synergizing Reasoning and Acting in Language Models

Chunking#

The process of splitting large documents into smaller pieces for indexing and retrieval, so each piece fits an embedding model's input. In Antfly a chunker is configured on an index or enrichment, not at query time. The default fixed model splits by token count (and by fixed windows for audio and images), and a source shared by several indexes is chunked at most once per write.

See: Chunking Strategies for LLM Applications

Embeddings#

Dense vector representations of text, images, or other data that capture semantic meaning. Similar concepts have similar embeddings (close in vector space). Managed index creation supports Antfly Inference, Ollama, OpenAI, OpenRouter, Cohere, Gemini, Vertex AI, and AWS Bedrock. Used by AKNN indexes for similarity search. See also Sparse Vectors & SPLADE.

See: Word2Vec | Sentence-BERT | MTEB Leaderboard

Evals#

Short for "evaluations" - systematic testing of AI system quality. Evals measure metrics like retrieval accuracy, answer relevance, and latency. They're essential for comparing different models, prompts, or configurations and ensuring system quality over time.

See: RAGAS: Evaluation framework for RAG | OpenAI Evals

Generators#

Models that produce text, images, or other content. In RAG pipelines, generators (typically LLMs) take retrieved context and user queries to produce final answers. Antfly's Retrieval Agent (POST /agents/retrieval) streams generated answers via Server-Sent Events.

Genkit#

An open-source framework for building AI-powered applications, with abstractions for LLMs, embeddings, and retrieval. Antfly ships a Genkit (Go) plugin, github.com/antflydb/antfly/go/pkg/genkit/antfly, that exposes an Antfly table and index as a Genkit retriever.

See: Antfly Genkit plugin | Genkit

Model (ML/AI)#

A trained machine learning system that performs specific tasks. In Antfly's context, this includes embedding models (convert data to vectors), reranker models (re-score search results), vision models (process images), and generator models (produce text). Models run locally on Antfly Inference from GGUF, safetensors, or ONNX artifacts on its native backends, or remotely through an API provider.

See: Hugging Face Model Hub

Multimodal#

Systems that work with multiple data types - text, images, audio, video. Antfly supports multimodal indexing and search, allowing you to search across different content types. Multimodal embeddings (like CLIP or Gemini) create unified vector representations across modalities.

See: CLIP: Learning Transferable Visual Models | Antfly Multimodal Guide

Multiturn Chat#

Conversational interactions spanning multiple exchanges where context is preserved across turns. Unlike single queries, multiturn chat requires managing conversation history, resolving references ("it", "that"), and maintaining coherent dialogue state.

NER (Named Entity Recognition)#

The task of identifying and classifying named entities (people, organizations, locations, dates, etc.) in text. NER can enhance search by extracting structured information from unstructured documents, enabling faceted search and knowledge graph construction.

See: spaCy NER | Stanford NER

Pruners#

A query processor that drops low-quality results by score. In Antfly the pruner runs once on the merged results, after fusion and any reranking and before offset/limit paging. Its options are min_score_ratio, max_score_gap_percent, min_absolute_score, std_dev_threshold, and require_multi_index. See also Rerankers.

RAG (Retrieval-Augmented Generation)#

A technique that combines search/retrieval with generative AI. Instead of relying solely on an LLM's training data, RAG retrieves relevant documents and provides them as context for generation. This produces more accurate, grounded, and up-to-date responses. In Antfly, RAG is the Retrieval Agent at POST /agents/retrieval, which streams its answer over Server-Sent Events.

See: Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks | RAG in the Quickstart

Rerankers#

Models that re-score and reorder search results for improved relevance. Unlike initial retrieval (which must be fast), rerankers can use more sophisticated cross-attention between query and document. Antfly supports rerankers as query processors that refine results from hybrid search, with antfly, cohere, and vertex providers. See also Late Interaction.

See: Cross-Encoders

Tokenizers#

Components that split text into tokens (subwords, words, or characters) for processing by ML models. Different models use different tokenization schemes (BPE, WordPiece, SentencePiece). Tokenizer choice affects vocabulary size, handling of rare words, and multilingual support.

See: Hugging Face Tokenizers | BPE Paper

Tool Use#

The ability of AI agents to invoke external functions or APIs to accomplish tasks. Tools extend an agent's capabilities beyond text generation - searching databases, executing code, calling APIs, or interacting with external systems.

See: Toolformer | Anthropic Tool Use

Search & Indexing#

Agentic Search#

Search that goes beyond simple query-response patterns. An agentic search system can reformulate queries, explore multiple search paths, synthesize information from different sources, and iteratively refine results to better answer user intent. See also Semantic Search.

AKNN (Approximate K-Nearest Neighbors)#

Algorithms that find the K most similar vectors to a query vector, trading perfect accuracy for dramatic speed improvements. Antfly's dense embeddings index uses AKNN for fast, memory-efficient vector search on embeddings.

Key techniques used in Antfly's AKNN implementation:

• HBC (Hierarchical Balanced Clustering): Vectors are organized into a tree of balanced clusters whose leaves are posting lists. A query runs a beam search down the centroid tree, scans the selected leaves, then exact-scores only the candidates whose quantization error bounds overlap the result cutoff. Large indexes route through a flat exact-centroid directory instead of the tree. The only public tuning knob is search_effort (0 to 1, default 0.5).
• RaBitQ: A quantization method with a theoretical error bound. Antfly stores each vector as a 1-bit-per-dimension code of its residual from the leaf centroid and keeps full-precision vectors for the final rerank.
• SPFresh: Antfly applies SPFresh-style maintenance policies to HBC, such as lazy centroid refresh and local posting split and merge, so routine inserts and deletes stay local and never trigger a full rebuild. It is not a separate index type.

Hardware acceleration via SIMD speeds up distance calculations.

See: FAISS | ANN Benchmarks | SPANN Paper | RaBitQ Paper | SPFresh Paper

Algebraic Index#

An index type that derives typed fields from the table schema and maintains declared exact aggregate recipes (aggregates) as materializations. Eligible queries reuse a complete materialization instead of scanning. The design treats aggregation as a fold over algebraic structures such as monoids, groups, and semirings.

See: Algebraic design

Facetting#

Organizing search results into categories (facets) based on document attributes. Facets let users filter results by category, date range, author, or other fields. In Antfly, facets come from a query's aggregations (terms, range, histogram, date histogram, and geo) over the full-text index. See Full-Text Search.

See: Faceted Search (Wikipedia)

Full-Text Search & BM25#

Full-text search indexes and queries the complete text content of documents. Unlike database queries on specific fields, full-text search handles natural language queries, typos, synonyms, and relevance ranking.

BM25 is the ranking function used for scoring documents based on term frequency and document length. BM25 improves on TF-IDF by accounting for term saturation and document length normalization.

Antfly's full-text index (zig/pkg/antfly-embedded/src/search) is implemented natively in Zig as a Lucene-style segment index, using an FST-based term dictionary and roaring-bitmap posting lists to provide BM25 ranking, language-aware tokenization, faceted search, and highlighting.

See: Introduction to Information Retrieval | Okapi BM25 (Wikipedia) | BM25 Paper

Graph Index#

An index type that stores typed, directed edges between documents, from document fields or from relation artifacts extracted by enrichments. Queries can traverse, list neighbors, find shortest paths, and match patterns; optional node summaries enable tree navigation in the Retrieval Agent.

See: Graph Navigation | Graph design

Hybrid Search#

Combining multiple search approaches - typically BM25 (keyword) and vector (semantic) search - to get the benefits of both. Keyword search excels at exact matches; vector search handles semantic similarity. Antfly merges results using RRF or RSF fusion.

See: Hybrid Search | Hybrid Search Explained

Indexing#

The process of analyzing documents and building data structures for efficient search. Indexes trade storage space and write-time processing for fast query performance. Antfly's index types are full_text (BM25), embeddings (dense or sparse vectors), graph, algebraic, and relational.

See: Document Engine

Late Interaction (ColBERT & MaxSim)#

A scoring method that keeps one vector per token for both query and document and sums, over query tokens, each token's best match in the document (MaxSim). In Antfly, late interaction is a reranking method: ColBERT-style models served by Antfly Inference rerank candidates. It is not an index type.

See: ColBERT: Efficient and Effective Passage Search

React Components#

@antfly/components is a React library for search interfaces on Antfly: QueryBox and autosuggest, facet filters, results and pagination, AnswerResults for streamed Retrieval Agent answers, and ChatBar for multiturn chat.

See: React Antfly

RRF (Reciprocal Rank Fusion)#

A fusion method that combines ranked lists from different retrieval systems by scoring each result 1/(k + rank). RRF is Antfly's default merge strategy for hybrid search. The constant k is rank_constant (default 60), and per-index weights scale each list's contribution.

See: Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods

RSF (Relative Score Fusion)#

A score fusion method that normalizes and combines actual scores (not just ranks) from different retrieval systems. RSF can better preserve score magnitude information compared to RRF but requires careful score normalization across different scoring functions. Antfly's RSF min/max-normalizes scores within window_size and applies the same per-index weights as RRF.

Semantic Search#

Search based on meaning rather than exact keyword matching. Semantic search uses embeddings to find conceptually similar content even when different words are used. "Car repair" can match documents about "automobile maintenance" through shared semantic meaning. Powers the vector component of hybrid search.

See: Semantic Search with Sentence-BERT

Sparse Vectors & SPLADE#

Vectors in which most dimensions are zero, each nonzero dimension a weighted vocabulary term. SPLADE models produce them from text, which gives learned keyword matching. An embeddings index with sparse: true stores them in an inverted index instead of the dense HBC index.

See: SPLADE Paper

Distributed Systems#

2PC (Two-Phase Commit)#

A distributed transaction protocol that ensures all participants in a transaction either commit or abort together. Antfly runs coordinator-driven 2PC over write intents with optimistic concurrency control (OCC): read versions are validated at commit, and a conflict returns 409. Clients use stateless POST /transactions/commit or server-managed sessions (/transactions/begin) with savepoints, and the protocol is model-checked in TLA+.

See: Transaction TLA+ spec | Two-Phase Commit (Wikipedia)

Autoscaling#

Automatically adjusting system resources based on load. When enabled (it is opt-in), Antfly's Kubernetes operator scales data nodes on CPU and memory utilization within configured minimum and maximum replica bounds, and inference pools scale through a Kubernetes HPA. Compare with Autosharding, which handles data growth.

See: Kubernetes HPA

Autosharding#

Automatically splitting data partitions (shards) when they grow too large and merging them when they shrink. Antfly splits and merges shards by size (max_shard_size_bytes, default 64 MiB) once you opt in by setting the node config key disable_shard_alloc: false; it defaults to true.

Hot Standby#

A Postgres-style high-availability mode: a single primary streams its WAL to read-only standbys (antfly standby), with replication slots for WAL retention and explicit promotion with fencing. It is an alternative to Raft quorums for read replicas, disaster recovery, and online upgrades. Point-in-time recovery is not supported; backups restore a selected backup snapshot.

See: Hot standby design

Raft & Multiraft#

Raft is a consensus algorithm that ensures multiple nodes agree on a sequence of operations, providing strong consistency in distributed systems. Raft uses leader election and log replication. Antfly implements its own Raft consensus natively in Zig (zig/lib/raft, zig/pkg/antfly/src/raft), architecturally inspired by etcd/raft's deterministic core and Dragonboat-style multi-group hosting. Node-to-node Raft traffic uses HTTP.

Multiraft extends this by using multiple independent Raft consensus groups. Unlike single-Raft systems where one group handles all data, Multiraft assigns separate Raft groups to different data partitions (shards). This enables parallel operations, fault isolation, and independent scaling. Antfly uses Multiraft with separate groups for metadata and each storage shard.

See: In Search of an Understandable Consensus Algorithm | Raft Visualization | etcd/raft | TiKV Multi-Raft

Sharding#

Horizontally partitioning data across multiple nodes or storage units. Antfly partitions each table into shards by key range; num_shards sets the initial count, and replication_factor (default 3, maximum 5) sets how many replicas each shard keeps. See also Autosharding.

See: Shard (Wikipedia)

Tables, Shards & Raft Groups#

A table is a named collection of documents with a schema and indexes, split into key-range shards. In a distributed deployment each shard is replicated by its own data Raft group, while a separate metadata group holds cluster topology, schemas, and table definitions. Lite storage has no Raft, and object tables allocate no data Raft groups.

See: Architecture

Deployment & Storage#

Antfly Lite (.aflite)#

Antfly's single-file storage engine: one portable .aflite file with one writable owner, opened directly by an embedded application or served by a standalone server, and managed with the antfly lite CLI. It uses its own page engine rather than the LSM tree.

See: Antfly Lite | Lite design

Deployment Modes#

Which processes run, chosen independently of the storage engine. embedded opens Antfly inside an application with no server; standalone runs one process that owns metadata, data, APIs, and inference; distributed splits metadata and data nodes for horizontal scale; and serverless (in progress) decouples compute from object storage.

See: Deployment and storage design

Document Storage#

Storing data as self-contained JSON documents rather than rows in tables. Documents can have flexible schemas and nested structures. Antfly stores documents with automatic indexing of fields.

Linear Merge#

A stateless way to sync sorted records from an external source. Antfly's linear merge (POST /db/v1/tables/{table}/merge) takes a sorted page of source records and performs a three-way sync over that key range: it inserts new keys, updates changed ones, and deletes Antfly keys missing from the page.

LSM Tree#

The log-structured merge tree behind the local storage engine (zig/pkg/antfly-embedded/src/storage/lsm_backend). Writes land in a WAL-backed memtable, then flush to immutable sorted runs (runs/<id>.tbl, often called SSTables) tracked by a manifest and compacted in the background. Each shard has its own storage instance; Antfly Lite uses its own engine instead.

See: LSM-Tree (Wikipedia)

Storage Engines#

Where durable state lives, chosen independently of the deployment mode. lite is a single .aflite file, local is a directory of LSM shard and metadata storage, and object keeps durable data in object storage.

See: Deployment and storage design

WAL (Write-Ahead Log)#

A durability mechanism where operations are written to a sequential log before being applied. If the system crashes, the WAL enables recovery by replaying logged operations. Antfly keeps a Raft log WAL and an LSM WAL for mutable state, and hot standby replicates by streaming the WAL to standbys.

See: Write-Ahead Logging (Wikipedia)

Technologies & Frameworks#

A2A (Agent2Agent)#

An open protocol for agents to discover and call each other. Antfly serves A2A at POST /a2a with an agent card at /.well-known/agent-card.json, advertising its native agents as skills.

See: A2A design | A2A Protocol

GGUF & safetensors#

Model weight file formats. GGUF is the single-file format from the llama.cpp/ggml ecosystem, often quantized; safetensors is Hugging Face's safe tensor serialization format. Antfly Inference runs both natively, alongside ONNX.

See: Model Downloads | GGUF | safetensors

JSON Schema#

A vocabulary for annotating and validating JSON documents. JSON Schema defines the structure, types, and constraints of JSON data. Antfly uses JSON Schema for table schemas with custom x-antfly-* extensions for indexing configuration.

See: JSON Schema | Understanding JSON Schema

MCP (Model Context Protocol)#

An open protocol that lets AI clients call tools exposed by a server. Antfly's MCP surface, over streamable HTTP, exposes exact table, index, document, and query operations; natural-language planning stays in the native agents.

See: n8n AI Agent over MCP | MCP design | Model Context Protocol

ONNX (Open Neural Network Exchange)#

A standard format for representing machine learning models. ONNX enables models trained in different frameworks (PyTorch, TensorFlow) to run in a common runtime. Antfly Inference parses .onnx graphs itself and executes them on its native kernels, with no external ONNX runtime, providing embedding, chunking, reranking, and generation without external API calls. Its experimental WASM/WebGPU browser backend also uses the native importer rather than ONNX Runtime Web.

See: ONNX

OpenAPI Specification#

A standard for describing REST APIs in a machine-readable format. Antfly's APIs are defined in OpenAPI under specs/openapi/. The Go, TypeScript, and Python SDKs are hand-written clients over generated code, and the Rust SDK is generated end to end.

See: SDKs | OpenAPI Specification

SIMD#

SIMD (Single Instruction, Multiple Data) is a CPU feature that processes multiple data elements in parallel with one instruction. Antfly uses Zig's portable @Vector SIMD, AVX2/AVX-512 kernels on x86, and NEON on ARM for fast vector distance calculations in AKNN search and for inference kernels.

See: Intel Intrinsics Guide | ARM NEON

TOON (Token-Oriented Object Notation)#

A compact encoding of JSON for LLM prompts that declares the fields of uniform arrays once and lists one row per line. The Retrieval Agent renders retrieved documents into its generation prompt as TOON by default, so more documents fit in the same context.

See: TOON format reference

XLA (Accelerated Linear Algebra)#

An open-source ML compiler, now developed under the OpenXLA project, that targets CPUs, GPUs, and TPUs through the PJRT runtime interface. Antfly Inference has an experimental PJRT/XLA backend.

See: OpenXLA

Testing & Verification#

TLA+#

A formal specification language for modeling concurrent and distributed systems and model-checking their invariants. Antfly's TLA+ specs cover the Raft, 2PC transaction, shard split, snapshot transfer, and LSM lifecycle protocols.

See: Antfly TLA+ specs | TLA+

VOPR#

Antfly's deterministic simulation testing platform. It runs unmodified production code on a virtual, fully controlled I/O layer, injects faults, and replays any failing history exactly from its seed. Scenarios cover metadata, transactions, Raft, storage, standby, backups, and a full cluster.

See: VOPR design

Other Concepts#

Scraping & Remote Content#

Extracting content from web pages or documents for indexing. Antfly supports automatic download and processing of content from URLs (http/https/s3/file) with built-in SSRF prevention and content validation for secure remote processing of images, PDFs, and HTML.