Barrel
FR GitHub

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.

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.

Written for the site Edit this page View as Markdown

Up and down to moveEnter to open