DEV Community

Cover image for Full-Text and Vector Search for Scanned PDFs with HexDB
Matthew Martin
Matthew Martin

Posted on AI-assisted

Full-Text and Vector Search for Scanned PDFs with HexDB

I write database software and record music with my band Ashes Gone, so here's a search problem I'd actually care about. Somewhere in a folder of scanned studio notes is the sheet that says, “Mute the room microphones for the final chorus.” I can remember that decision months later. There's no chance I'm going to remember scan_0042.pdf.

In HexDB 2.5, I can upload that PDF and find it by typing room microphones. If all I remember is we wanted the drums to sound drier at the end, I can search for that, too. The first lookup uses optical character recognition (OCR) and a full-text index. The second uses a vector index on the words extracted from the very same file.

HexDB is an open-source, encrypted document database written in Rust. It stores JSON records and binary files. When I introduced HexDB on DEV, it could already search text embedded in a PDF. Version 2.5.1 added Tesseract OCR for pages that arrive as images. Here's how to try both kinds of search on the current release, 2.5.9.

Give the database a page to read

Use a phone or scanner to make a one-page PDF of a printed note. For this example, put “Mute the room microphones for the final chorus. Keep the close drum mics up.” on the page and save it as scan_0042.pdf. A PDF where you can't select the words is ideal. If your scanner adds its own text layer, the search still works, but HexDB may read that layer directly.

Start a local HexDB instance using the Docker quick start. Use the full image, ghcr.io/dreaminhex/hexdb:2.5.9, which includes Tesseract and English language data. Sign in as the local administrator at http://localhost:7700/ui/, create an API key on the Account page, and set HEXDB_TOKEN to that key in your shell.

HexDB calls a collection a tessellation. Creating one with kind: files gives it a text index that already covers filenames, folders, tags, descriptions, and extracted metadata. Run these commands in Bash with a recent version of curl.

base=http://localhost:7700
auth="Authorization: Bearer ${HEXDB_TOKEN:?Set HEXDB_TOKEN to your local API key}"

curl -fsS -H "$auth" "$base/tessellations" \
  --json '{"name":"studio","kind":"files"}'

curl -fsS -H "$auth" -T scan_0042.pdf \
  "$base/studio/_files/sessions/scan_0042.pdf"
Enter fullscreen mode Exit fullscreen mode

The upload creates a file record. A background worker reads the PDF and, for a scan, puts the recognized words in meta.text. By default, HexDB tries OCR on PDFs with fewer than 200 characters of embedded text and reads up to the first 20 pages. That limit matters if the sentence you're hunting for is on page 21. You can change it with files.ocr_pages.

Find the words and see where they came from

curl -fsS -H "$auth" "$base/studio/_query" --json '{
  "filter": {"$text": "room microphones"},
  "fields": ["name", "path", "meta.text", "meta.ocr"]
}'
Enter fullscreen mode Exit fullscreen mode

Once extraction finishes, the result should include scan_0042.pdf. Both search terms must appear in the indexed content. Returning meta.text lets you read what HexDB recognized, and meta.ocr identifies the engine and pages processed when OCR ran. If you query immediately after uploading and get no match, check the file record's extract.status. It moves from pending to done.

At this point you already have a searchable archive. Tesseract runs locally, and this keyword lookup needs no model or embedding provider.

Search by meaning within a folder

Now imagine a few months have passed. You remember how you wanted the drums to sound, but “room microphones” has escaped you. This is where I'd add vector search.

Configure an embeddings provider on the lattice, then create the following index. I've selected only meta.text as its source. HexDB sends the extracted words to the provider you choose. A local embedding model is an option when the session notes need to stay on your own hardware.

curl -fsS -H "$auth" "$base/tessellations/studio/indexes" --json '{
  "kind": "vector",
  "fields": ["embedding"],
  "source": ["meta.text"]
}'
Enter fullscreen mode Exit fullscreen mode

Creating the index queues existing records that need embeddings, including the sheet you already uploaded. For a more interesting test, upload a second sheet about guitar tuning to the same folder. Once both have embeddings, ask for the three closest matches.

curl -fsS -H "$auth" "$base/studio/_query" --json '{
  "filter": {"path": {"$startsWith": "/sessions/"}},
  "near": {
    "field": "embedding",
    "text": "a drier drum sound at the end of the song",
    "k": 3
  },
  "fields": ["name", "path", "meta.text"]
}'
Enter fullscreen mode Exit fullscreen mode

Each match has a similarity score. Does the drum sheet rank above the guitar sheet, even though the query never mentions microphones? You can inspect the returned text and judge the result yourself. The folder filter narrows the question, and HexDB applies the caller's read permissions and row filters to the query.

The same search is available to a read-only MCP client. One addition in 2.5 is the Oracle, an optional HexDB node that handles AI requests. It can wait on a model while a storage node looks up the notes using the requesting musician's permissions. That lets me give AI traffic its own machine without handing an agent an administrator key or copying the studio archive onto that machine.

What changed in HexDB 2.5.9?

Once those files are in the database, ordinary database questions are fair game. For example, this SQL query lists the session sheets that Tesseract actually processed.

SELECT name, meta.ocr.pages
FROM studio
WHERE meta.ocr.engine = 'tesseract'
ORDER BY name
Enter fullscreen mode Exit fullscreen mode

In 2.5.9, SQL reads only the fields a statement uses. Here the engine can leave the extracted text and embedding out of the read. That makes a difference when you want a two-column report over thousands of records carrying pages of text.

There's also a change for anyone feeding a second system from HexDB. Say a stream plugin maintains a separate catalog and stays offline longer than HexDB retains its change history. In 2.5.9 the plugin pauses in needs_resync. An administrator can have it send a snapshot of the current documents before it resumes, or explicitly choose to resume from now. A current snapshot can rebuild a catalog. It can't tell you every edit that happened while the plugin was away, which is why I want that decision visible to the operator.

The test I'd give HexDB is simple. Pick two files from your own domain, rename them both to something useless, and search for a detail you remember. Then try asking in words that never appear on either page. If the wrong file wins, I'd like to hear what you searched for and what you expected to find.

HexDB website · Source and quick start · File storage and search manual · 2.5.9 release notes

Top comments (0)