Quick start

This page gets you from a source checkout to a served query. It uses yolosearch-local: one OS process that runs the complete data plane plus the admin UI, with no flags and no object store to set up. The sample schema and corpus are already in the repository.

Everything here runs on your own machine and writes to one directory you can delete afterward.

• Go 1.27 or newer
• Node.js and npm
• just
• zsh

Start from the root of a YoloSearch source checkout. All commands below are run from there.

just build

This compiles everything under ./cmd/... and ./tools/... into ./bin, which is gitignored. You need two of the results: yolosearch-local, the single-process server, and yolosearch, the client.

./bin/yolosearch-local

It prints a ready block and stays in the foreground:

yolosearch-local: ready
  data:  127.0.0.1:9500
  admin: http://127.0.0.1:8787
  root:  <cwd>/yolosearch-local-data
  objects: <cwd>/yolosearch-local-data/objects
  cache:   <cwd>/yolosearch-local-data/cache
  ingest:  <cwd>/yolosearch-local-data/ingest
  models:  <cwd>/yolosearch-local-data/models

The four derived directories are the whole installation: objects/ holds the authoritative schemas, segments, commit markers, and catalogs; cache/ is disposable; ingest/ is the durable spool and build scratch; models/ holds checksum-addressed embedding model packages. Data persists across restarts.

Leave this terminal running and open a second one for the rest of the steps.

A YoloSearch schema is a protobuf message. Field numbers are the field IDs the index keeps forever, and options on the message and its fields say what the index does with each one. The repository ships one:

./bin/yolosearch schema apply deploy/swarm/articles.proto

apply compiles the .proto in-process — no protoc or buf is involved — and prints one line naming the result (created v1), the message, a field summary, and the key field.

That file declares an articles index whose url field is the logical key, whose title and body are indexed and stored, and whose site, category, and published fields are stored and filterable:

message Article {
  option (yolosearch.v1.document) = {index: "articles"};

  string url = 1 [(yolosearch.v1.field) = {key: true}];
  string title = 2 [(yolosearch.v1.field) = {
    indexed: true
    stored: true
    weight: 2.0
    b: 0.6
  }];
  string body = 3 [(yolosearch.v1.field) = {
    indexed: true
    stored: true
  }];
  string site = 4;
  string category = 5;
  google.protobuf.Timestamp published = 6;
}

Applying the first schema creates the index.

./bin/yolosearch push articles deploy/swarm/articles.jsonl

push fetches the schema first, validates each document client-side, and streams batches to the server. By default the last batch carries a flush, so push returns only once the segment is published and served by this process. The summary line has this shape, with the segment ID, generation ID, and elapsed time differing on every run:

pushed 6 documents in 1 batches · sealed segment 9f3a1c2b… · generation 7d1e0a4c… · PUBLISHED in 0.4s

The input is JSONL: one JSON object per line whose member names are the schema's field names. The key field supplies the document key.

./bin/yolosearch search articles 'title:search' --fields title,url

The table prints KEY, SCORE (four decimals), VERSION, then one column per projected field. --fields asks the server for stored values; without it you get the key, score, and version alone.

A bare term searches every indexed field:

./bin/yolosearch search articles search --fields title,url

A space between terms means OR, not AND. To require both, write AND or use the + prefix on each clause:

./bin/yolosearch search articles 'search AND body:cache' --fields title,url

Phrases, filters, and a larger result window:

./bin/yolosearch search articles 'body:"object storage"' \
  --filter category=engineering --fields title,category,url --top-k 20

The remaining steps cover CQP queries, output formats, statistics, and cleanup.

CQP is the positional grammar. []{0,3} is a gap of up to three tokens:

./bin/yolosearch search articles '[word="cold"] []{0,3} [word="cache"]' \
  --dialect cqp --fields title,url

Both grammars lower to the same abstract syntax tree. explain shows that tree, the lowered query, and its canonical digest. With --index, it fetches the schema from the server before lowering locally:

./bin/yolosearch explain 'title:search AND +body:cache' --index articles

The output format determines which data the server reads:

./bin/yolosearch search articles search --ids --top-k 100

--ids is the cheapest large-result path. --keys and --ids stream hits as the gRPC result stream is consumed instead of buffering the whole top-K, and are mutually exclusive with --fields, --json, and --no-collapse.

./bin/yolosearch stats articles
./bin/yolosearch stats

Then open http://127.0.0.1:8787. The console shows schemas and node statistics, runs queries, applies schemas, and uploads documents. It also supports Clean and Delete for local indexes. The CLI connects to the same server at 127.0.0.1:9500.

Ctrl-C in the first terminal drains both endpoints and joins every background goroutine. Nothing is detached, and no hidden log file is written.

Restarting ./bin/yolosearch-local reopens the same schemas and documents. To delete the local database instead, stop the process and run this guarded reset from the repository root:

local_root="$(realpath ./yolosearch-local-data)"
test "$local_root" = "$(pwd -P)/yolosearch-local-data" && rm -rf -- "$local_root"

Understand what you ran:

• Architecture — the roles and the authority boundary
• Segments and objects — the segment layout written by push
• The query lifecycle — the execution stages of search
• Ranking and exactness — how result ordering is established

Do more with it:

• Schemas — field options, evolution rules, and validation errors
• Ingest — batching, sealing, flush semantics, and deletes
• Lucene grammar and CQP grammar
• Vectors and hybrid search — embedding profiles and fusion
• Local development — the Docker Swarm fleet with real process boundaries
• Configuration — precedence, files, environment, and runtime changes

Run it somewhere else:

• Containers and Kubernetes
• Object store — what authoritative storage requires
• CLI reference — commands and flags, with instructions for generating the current manual