Introduction

How Spool's parts fit together, who it is for, and what each page of these docs covers.

Spool pulls records out of text and rows, decides which are the same real-world thing, and gives each thing an ID that stays the same as more arrive. Working out which records are the same thing is called entity resolution, or record linkage. Spool does that, takes records from text as well as from tables, and keeps the IDs.

How the parts fit

Spool is one server. It is written in Rust and keeps its data in one file of DuckDB, a database that runs inside the server's process. It is driven by a project, which is a directory of YAML and SQL files that you keep in Git.

  1. A project is a directory. Sources, features, rules and extractors are files, and a file's path is its name. Project structure
  2. Records come from rows or from text. A row of a source becomes a record. A document is stored, and an extractor finds the places where it names a thing: each place becomes a record. An extractor is a pattern that Spool runs itself, or your own code in Python or TypeScript, which the server runs as a child process. A record is never changed, and loading it twice does nothing. Records and sources, Extraction
  3. Records are compared by features. Each source's columns are mapped onto the features of an entity type, such as company, that you declare. Entity types and features
  4. Rules judge pairs. A match compares what is new with what is known and records a judgement for each pair: match or no_match. A rule is a SQL condition over two records. Matching
  5. Judgements become identities. New records join an identity or start one. A match never merges or splits identities that exist. Every change is an entry in a log, with an author and a reason, and can be undone. Identities
  6. What cannot be decided waits. A record that fits two identities, and an identity that may have come apart, are left for a person or an agent. Review
  7. Other systems store the ID. They look it up by a row's source and key, and follow the log to learn of merges and splits. Using the IDs

There are four ways in, and they reach the same server:

ForPage
The command lineLoading, extracting, matching, showing and explainingCommand line
The HTTP APIEverything. The other three call itHTTP API
The MCP endpoint at /mcpAn agent that loads, looks things up and correctsMCP
The studio, in a browserLooking, reviewing, merging, splitting and undoingGetting started

Who it is for

  • You maintain a list of companies, people or products that several sources feed, and other systems refer to them by ID.
  • Some of what you know about them is in text: notes, articles, emails.
  • You want to read why two records were matched, and take a wrong match back without rebuilding everything.
  • You want matching rules reviewed like code, in files, with a history.
  • You have people or agents making corrections, and need every correction attributed and reversible.
  • You have thousands to a few million records, and one machine is enough.

If that is not you, Limits says what Spool is not meant for, and Compared with other tools says what to use.

The pages

Start

  • Getting started: install it, load rows, match them, extract records from a note. Five minutes.
  • Limits: what it is not meant for, what stable IDs cost, what it does not do yet, how large it has been run.
  • Compared with other tools: Splink, dedupe, Zingg, Senzing, nomenklatura, GoldenMatch, and a GROUP BY.

Concepts. Each page starts from the sample project and can be run by itself.

Use

Reference

Where it stands

Spool's first commit was on 14 November 2026. It is version 0.1.0, under the MIT licence, and formats and the API can still change.

Every command on these pages is run by a script, site/scripts/check-samples.ts, against a build of the source, and the output shown is compared with what was printed. It is run by hand before a page changes.

The source is at github.com/alexpatow/spool.