Glossary
This page explains the words the Barrel docs use, in alphabetical order. Each entry says what the thing is, why it matters to you, and where to read more. Other pages link here the first time they use a term, so you can come back whenever a word is unclear.
Active-active
Every copy of a database takes writes, and the copies converge when they replicate. You do not pick a primary: a laptop, a phone and two servers can all accept edits to the same document while apart. Concurrent edits are kept as a conflict instead of being lost. See Synchronization.
Attachment
A named binary file stored under a document's id, such as steps.md on
the support article kb-142. Attachments are not versioned: the last
write wins on its timestamp, and writing one does not change the
document's revision. They replicate on their own feed,
alongside documents. See Attachments.
barrel-lite
A TypeScript client that keeps a local copy of a database in the web browser and syncs it with a Barrel server. Your web app reads and writes locally, keeps working offline, and converges with the server when it reconnects. The browser may evict local data, so sync is what makes writes durable. See barrel-lite.
Barrel server
barrel_server puts a Barrel database on the network: REST/JSON over
HTTP, and an MCP endpoint for agents. Use it when clients are in
other languages, on other machines, or must be held to a
capability token. It holds no database logic of its
own and is not part of the default embedded build. See Run the REST
server.
BM25
A keyword ranking: it returns only the documents that contain the words of your query, ranked by how well they match. Use it when exact terms matter, such as an error code or a product name. Its score is the raw BM25 value and has no upper bound. See Vector, keyword and hybrid.
BQL
Barrel's query language, a dialect of PartiQL (SQL for JSON). One
SELECT statement can filter documents, run a vector or keyword search
and join the results back to their documents, or subscribe to live
updates. It compiles onto the same engine as the structured find/2
API. See Query with BQL.
Branch
A fork of a database, made in constant time whatever its size, because the branch shares its files on disk with its parent. The branch is a normal database: an agent or an experiment works on it alone, then you merge back what survived review. Concurrent edits on both sides become regular conflicts. See Branch, merge, recover.
Capability token
A secret string starting with bsp_ that gives its holder read,
write or admin rights on one space and nothing else. It is
shown once when you grant it; Barrel stores only its SHA-256 hash.
barrel_server checks it on every request, while inside your own Erlang
node it is advisory. See Spaces and capabilities.
Channel
A named set of path patterns, declared when you create a database, that selects a subset of documents to replicate. Barrel files matching writes into a per-channel feed as they happen, so a filtered pull reads only that feed instead of the whole history. Use it to send a phone only its tasks, for example. See Synchronization.
Checkpoint
A small local record, kept on both sides of a replication, of how far the last run got. The next run starts from there instead of from the beginning, so you can stop and restart replication at any time. A filtered replication keeps its own checkpoint. See Synchronization.
Conflict
Two copies edited the same document before they synced, so neither
version saw the other. Barrel keeps both as siblings, shows the same
winner on every copy, and lists the others in _conflicts until you
resolve them. Separately, a write with a stale _rev is refused with
{error, conflict}, so you never overwrite a change you did not read.
See Versions, conflicts, convergence.
Convergence
The guarantee that every copy of a database ends with the same versions, the same winner, the same body and the same deleted flag, whatever the order of writes and syncs. It is what lets you write anywhere and sync later without a coordinator. See Why it converges.
Document
A JSON object with an id, such as the support article kb-142. Every
write to it creates a new version, and every field in it is indexed, so
you can query any field without declaring an index. Top-level fields that
start with _ are reserved for Barrel. See The
record.
Embedded
Running Barrel inside your own Erlang or Elixir release, as a library, with no server and no network hop. You get the full API in process: documents, search, attachments, record mode and the timeline. Use it when your application owns the data. See Embed barrel in an Erlang app.
Embedding
The vector a model computes from a piece of text, so that texts with close meanings get close vectors. Barrel calls an embedding provider (a local model, an Ollama server or a cloud API) on every write and on every text query. Which provider you pick decides where your text goes. See Choose an embedding provider.
Handoff
A way for one agent to pass a task to another inside a space. It issues a capability token for the task; whoever accepts it first gets a session in the same space, and a second accept fails. Nothing is copied: the next agent reads the context where it is. See Spaces and capabilities.
Hybrid search
A search that runs a vector search (by meaning) and a BM25 search (by keyword), then fuses the two rankings into one. It finds documents that say the same thing in other words and still ranks exact terms well. The default fusion uses ranks, not raw scores. See Vector, keyword and hybrid.
MCP
The Model Context Protocol, a standard way for agent runtimes and IDEs
to call tools. Barrel server serves an MCP endpoint at
/mcp with tools for documents, BQL, search, the timeline, spaces and
contexts. Your agent talks to Barrel directly, held to the same
capability tokens as REST. See MCP endpoint.
Pin
A piece of context you attach to a session with
pin_context, such as a key fact the agent must keep in view. Pins are
stored as documents in the space and listed with list_pinned, so
anyone holding a token for the space can read them. See Spaces, sessions,
handoffs.
Point-in-time recovery
Reading a database as it was at a past instant, by creating a branch at that instant. You get yesterday's data next to today's, without restoring a backup over the live database. It works inside the retention window (30 days by default); older history is gone. See Backups and recovery.
Record
Everything Barrel keeps under one id: the document, its attachments and, in record mode, its vector. You read, write, replicate and delete them by that id, so they never drift apart. See The record.
Record mode
A database setting that tells Barrel which fields to embed, with which
provider and at which dimension. Barrel then computes the vector on every
write and drops it on delete, so search always matches the current
documents and you never call vector_add yourself. See Record
mode.
Replication
Copying versions from one database to another, in the same Erlang VM or over HTTP to a Barrel server. It runs once or continuously, resumes from its checkpoint, and can carry only a subset with a channel. Sending a version twice is safe. See Synchronization.
Revision
The _rev field Barrel adds when you read a document: the token of its
winning version, built from a clock and the id of the database that
wrote it. Send it back when you update the document; a missing or stale
_rev returns {error, conflict}. See The version
token.
Session
An agent's working context inside a space: its messages, key/value data and pins, stored as documents in the space. It expires after a period without activity (3600 seconds by default) unless you make it durable. Anyone holding a token for the space can read it. See Spaces and capabilities.
Space
A Barrel database that several agents share, each holding a
capability token for it. Its name is sp_ followed
by 16 characters, and a registry records who was granted what. Use one
space per piece of shared work, such as a joint research draft. See
Spaces and capabilities.
Vector
A list of numbers that stands for the meaning of a document's text, used to find documents by similarity. In record mode it follows the document: written with it, dropped with it. Vectors are not replicated; each copy computes its own. See Vector, keyword and hybrid.