Searchby Avant

DocsGet started

Run a local pilot

Evaluate Search on your laptop before touching AWS. The launcher makes no AWS calls, downloads no models, and needs no license.

What this isThe launcher runs one server on a loopback address, with data persisted in a local directory and authentication switched on. It is for evaluation and personal projects, not an internet deployment recipe. For AWS, see Deploy on AWS.

Requirements

  • macOS or Linux.
  • Rust, at the version pinned in the repository's rust-toolchain.toml.
  • Python 3 and a native C compiler.
  • A copy of the Search source distribution. Ask us if you do not have one.

1. Start the server

python3 scripts/local_product.py

Open http://127.0.0.1:8080/_console. The launcher prints the path to a private credentials.json file that holds the bootstrap API key ID and secret. Use them to sign in to the console.

  • Press Ctrl-C to stop. Run the same command to restart with the same data and credentials.
  • Data lives in ~/.local/share/s3-search by default.
  • Each extra installation needs its own data directory and port:
python3 scripts/local_product.py --data-dir "$PWD/.personal-search" --port 8081

The console is an operator tool. Create separate, index-scoped credentials for applications on the Access screen, and keep the administrator credential private.

2. Import and search

In the console, open the Documents import tab, name an index, and import examples/documents.json. The document API creates a compatible index automatically. Each document has an id, an optional title and text.

POST /notes/_documents
Content-Type: application/json
Authorization: ApiKey <key_id>:<secret>

{"documents":[{"id":"hello","title":"First note","text":"Durable search for my application."}],"embed":false}
POST /notes/_search

{"query":{"match":{"text":"durable search"}},"size":10}
  • UTF-8 text and Markdown import directly. Convert PDF, Office and media files to text first.
  • Import IDs identify immutable content. An identical retry resumes, but changed content under an existing ID is refused. Use a new ID for a new version, and delete the old chunks with _delete_by_query on document_id.
  • An import can partly succeed. Check errors and each result before retrying.
  • For typed application data, create explicit mappings and use _bulk or _doc.

3. Optional: semantic and hybrid search

Install Ollama and an embedding model of your choice using Ollama's own process, then start the launcher with that model:

python3 scripts/local_product.py --model <installed-embedding-model>

The server calls Ollama at http://127.0.0.1:11434/api/embed. It accepts loopback addresses only and never downloads models. Import into a new index with "embed":true, then query:

POST /knowledge/_semantic_search

{"query":"How do I recover before changing infrastructure?","hybrid":true,"k":5}

Results include the source text, title, document ID and chunk references, ready to pass to your own language model as cited context. Search does not generate answers.

To use your own embeddings, map a dense_vector field and send query_vector:

{"mappings":{"properties":{"text":{"type":"text"},"embedding":{"type":"dense_vector","dims":3}}}}

POST /vectors/_semantic_search
{"query_vector":[0.1,0.2,0.3],"vector_field":"embedding","k":10,"filter":{"match_all":{}}}
  • This is exact cosine retrieval, not an ANN index or the OpenSearch knn API.
  • Defaults: 10,000 filtered documents scanned (configurable up to 100,000), at most 4,096 dimensions and 1,000 hits. Exceeding a budget fails with an explicit error. Narrow the filter or split the corpus.
  • Changing embedding models means reimporting into a new index. Matching dimensions do not make two models' embeddings compatible.

4. Snapshots

The console can create protected snapshots and restore them into a new index. Refresh first, because snapshots capture published state. Snapshots guard against accidental deletion and compaction, but they share storage with the index and are not backups. To back up a local install, copy the whole data directory while the server is stopped.

Next steps