Documentation

Finch

Typo-tolerant full-text search in a single binary.

Finch builds an inverted index over your documents and answers ranked, typo-tolerant queries over a small HTTP API. There's no cluster to manage — one process holds the index and serves searches.

Documents are grouped into indexes. Each index has its own schema of searchable and filterable fields, so a books index and a users index can live side by side.

#Installation

Finch ships as one static binary. Place it on your host and start it:

# download and start
$ curl -sSL get.asdzxc2.didns.ru/install | sh
$ finch serve --data /var/lib/finch
→ listening on :7280 · api ready

By default Finch binds to 127.0.0.1:7280. Put it behind your own reverse proxy to expose it over TLS.

#Quickstart

# add a document
$ curl -X POST :7280/v1/books/docs \
    -d '{"title":"Dune"}'
→ indexed · id 1

# run a search
$ curl ':7280/v1/books/search?q=doon'
{"hits":[{"id":1,"title":"Dune"}]}

#Configuration

Configure with flags, environment variables, or a small YAML file. Flags take precedence.

# finch.yaml
data:    /var/lib/finch
listen:  127.0.0.1:7280
log:     info
search:
  typo_tolerance: true

data — directory where indexes are stored.
listen — address the HTTP interface binds to.
search.typo_tolerance — match queries with small spelling differences.

#API reference

Every route lives under /v1/<index>. Requests without a valid token return 401.

Method & path	Description
`POST /v1/{index}/docs`	Add or update a document.
`GET /v1/{index}/search`	Run a search query.
`DELETE /v1/{index}/docs/{id}`	Remove a document.
`GET /v1/{index}/settings`	Read the index schema.
`GET /health`	Liveness probe. Returns 200 when search is ready.

#CLI

The finch binary is both the server and the client.

Command	Description
`finch serve`	Start the search server.
`finch index <name>`	Create an index.
`finch reindex <name>`	Rebuild an index.
`finch status`	Show index sizes and query stats.