Get started

One static binary, no dependencies. This page goes from download to a durable, searchable collection: install the server, add your data, and search it by meaning, keyword, or both. Running it for real is the operations guide, which covers services, scaling, and per-collection buckets.

Install

On macOS and Linux, the install script detects your platform, verifies the release checksum, and puts all six binaries on your PATH:

curl -fsSL https://get.polign.com | sh

On macOS, Homebrew works too and keeps the binaries updated:

brew install polign/tap/polign

For manual or pinned installs, each release archive ships static binaries for linux/darwin (amd64/arm64) with S3, GCS, and Azure Blob support built in. Download from the releases page, unpack, run:

tar -xzf polign_db_darwin_arm64.tar.gz

# for development: in-memory, zero config, write and query immediately
./polign-server

Running the server with persistent storage

Running the polign-server should give you an HTTP API on port 23000 and a gRPC API on port 23001. The archive also contains polign, a CLI that talks to http://localhost:23000 by default (point it elsewhere with -url or $POLIGN_URL), see the CLI reference for details.

If you prefer working from code, the Python SDK covers the same operations. Using it from Python below shows it in action.

export AWS_ACCESS_KEY_ID=AKIA... AWS_SECRET_ACCESS_KEY=... AWS_REGION=us-east-1
aws s3 mb s3://my-bkt --region us-east-1   # create the bucket once

./polign-server -store s3://my-bkt/polign

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
gcloud storage buckets create gs://my-bkt   # create the bucket once

./polign-server -store gcs://my-bkt/polign

az storage container create --account-name myaccount --name my-ctr   # create the container once

./polign-server -store az://myaccount/my-ctr/polign

./polign-server -store fs:/var/lib/polign

-store turns on the full data plane inside that one process: a durable write-ahead log in the bucket (.wal/, appended before every ack), persistence, bucket-backed serving with fresh reads, a bounded local disk cache, and the background maintenance that keeps big collections memory-efficient. The API is identical with or without it, so upgrading later is adding the flag.

Running it as a systemd service, exposing it beyond localhost with TLS, and pinning release versions are covered in Operate in production.

Terminology

polign_db has a small vocabulary.

Add your data

Each record is three things: an id you choose, the vector from your embedding model, and optional metadata. Writing a record whose id already exists overwrites it.

# one record: id "guide-1" in the collection "articles"
polign put articles guide-1 \
  -values 0.12,-0.03,0.98 \
  -meta title="Getting started" -meta url=/blog/start \
  -meta text="How to get started with..."

Real vectors are long, so pass a file instead: -values @embedding.json reads a JSON array, and -values - reads one from stdin, so you can pipe your embedding script straight in. The first write creates the collection and fixes its dimension: write a 768-number vector first, and every later vector must also have 768 numbers.

Everything the CLI does is plain HTTP underneath (the endpoints are in the HTTP API reference). Over HTTP, metadata values can be typed — strings, numbers, booleans — and batch requests take up to 5,000 vectors each. Reads render metadata values as strings unless the request opts in with "typed_metadata": true (or ?typed=true on GET).

# the same put, as raw HTTP — note the typed values
curl -X PUT localhost:23000/v1/collections/articles/vectors/guide-1 \
  -d '{"values": [0.12, -0.03, 0.98], "metadata": {"title": "Getting started", "score": 0.85, "published": true}}'

# batch upsert — validated as a whole before anything is applied
curl -X POST localhost:23000/v1/collections/articles/vectors:batch \
  -d '{"vectors":[
    {"id":"guide-2","values":[...],"metadata":{"title":"Filters"}},
    {"id":"guide-3","values":[...],"metadata":{"title":"Hybrid search"}}
  ]}'

Search

All searching is one command: polign search. What you give it decides which kind of search you get.

Search by meaning

Embed your question with the same model you used for your documents, and pass the resulting vector as -values. -k is how many results you want back:

polign search articles -values @query.json -k 5

ID       DISTANCE  SCORE  METADATA
guide-1  0.0014    -      {"title":"Getting started","url":"/blog/start",…}
guide-3  0.0102    -      {"title":"Hybrid search"}

Hits come back closest-first, each with its id, distance, and metadata, so the title and URL you stored earlier arrive with the result, ready to display.

Search by keyword

Give it -text instead of -values and you get classic keyword search (BM25, the ranking used by traditional search engines). No embedding model involved, so exact words, names, and codes match reliably:

polign search articles -text "getting started" -k 5

Search both ways at once (hybrid)

Give it -values and -text together and the server runs both searches and merges them into one ranking. This is usually the best default for search over documents.

polign search articles -values @query.json -text "getting started" -k 5

How the two lists merge is adjustable through fusion, rank-based by default or a weighted blend; the options are in the HTTP API reference.

Narrow results with filters

A -filter limits any search to records whose metadata matches. The simplest form is exact match:

# only records where lang is "en"
polign search articles -values @query.json -k 5 -filter '{"lang": "en"}'

Filters compose: value lists ($in), ranges ($gte, $lt, …), existence checks, and $and/$or/$not combinations. Values are typed, so number filters compare numerically and booleans match by value:

# well-scored and published, since Jan 2026, English or untagged
polign search articles -values @query.json -k 5 \
  -filter '{"score": {"$gte": 0.8}, "published": true,
            "ts": {"$gte": "2026-01-01"},
            "$or": [{"lang": "en"}, {"lang": {"$exists": false}}]}'

Filtering happens during the search, not after it. Asking for 5 results with a filter still returns the 5 best matching results, not whatever survives a trim.

Everyday housekeeping

Three more operations round out the API. You can fetch a record, page through a collection, and delete:

# fetch one record by id
polign get articles guide-1

# list records in a collection
polign list articles

# delete a record
polign delete articles guide-1

And that's nearly the complete surface: put, get, list, delete, query, plus batch put and batch get (plain HTTP routes, also wrapped by the client libraries). There is no index to create, rebuild, or babysit. As a collection grows, the server re-indexes it in the background and swaps the new index in without downtime. Every flag of every command, including the ones this walkthrough skips, is in the CLI reference.

Using it from Python

Everything above works identically through the Python client. Same operations, same options, without hand-writing HTTP calls.

# pip install polign
from polign import Client

client = Client("http://localhost:23000")

client.put("articles", "guide-1", embedding,
           metadata={"title": "Getting started", "score": 0.85,
                     "text": "How to get started with..."})

for hit in client.search("articles", values=query_embedding, k=5,
                         filter={"lang": "en"}):
    print(hit.id, hit.distance, hit.metadata["title"])

The polign package's HTTP client is pure standard library with zero dependencies, and pip install "polign[grpc]" adds a gRPC transport with the identical API. The Python SDK guide covers batching, hybrid search, error handling, and the gRPC transport; other languages talk to the HTTP API or the gRPC API directly.

When something doesn't work

Where to go next

• Operate in production: run it as a service, scale the fleet, control the bill, and give each collection its own bucket.
• HTTP API, Python SDK, and gRPC API are the complete references.
• How it works covers the design and the consistency contract behind all of this.
• The live demo runs hybrid search over Wikipedia on polign_db.