How-to guides

A how-to guide solves one task for someone who already runs a node. Each guide states what it needs, the requests to send, and what to do when one is refused.

Working with the API

• Handle errors in a client

  Read the error body, decide what to do with each class of failure, and retry without indexing anything twice.

• Generating an API client

  Fetch the OpenAPI document, build a client from it, give it a key, and keep it current with the node.

• Testing an application against a node

  Run an integration test suite against a node in a container, make the writes visible before asserting, and reset between tests.

Indexes and documents

• Defining an index

  Create and update an index as desired state, pick what each field is for, and avoid overwriting concurrent changes.

• Indexing documents

  Send documents, load a dataset, keep it current with feeds and deletes, and recover from a refused request.

• Updating parts of documents

  Change one field, one sub-document, or one locale without resending the rest of the document.

• Reading documents back

  Page an index back out again to export it, load it somewhere else, or see what a document holds.

• Make a write visible to search

  Find out why a document you just indexed is not in the results yet, and pass the token the write returned so the search waits for it.

• Using sub-documents

  Hold a list of values that are documents of their own, ask several things of one of them, and order, count, and change them.

• Modeling dynamic attributes

  Hold attributes the definition does not name in advance, filter and count by them, and change them one at a time.

• Localizing fields

  Hold values in several languages and search them by locale.

• Customizing text analysis

  Configure presets, custom chains, and stopwords and synonyms shared between fields.

Searching

• Searching an index

  Work with the search box, the scope it runs in, user-selected filters, facets, ordering, and highlighting.

• Searching from a search box

  Send what a person typed straight to the engine, choose how many of their words a document has to hold, and show them when the search that ran was not the one they typed.

• Reading numbers in the search box

  Declare a unit on a price or a size so that `under 100 kr` and `256gb` become filters, and show the shopper what was read.

• Reading colours and brands in the search box

  Opt a facet field into the search settings so that `red nike shoes` filters by colour and brand, without a reindex.

• Suggesting what to search for while it is typed

  Opt the brand and category fields into suggestions so that a search box completes `adi` to `adidas` on every keystroke, forgives a typo, and marks the part that was typed.

• Searching by vector

  Index the vectors that a model produces, find the nearest of them, and combine that with a text search.

• Paginating search results

  Use offsets, cursors, and numbered pages, and choose when each is the right tool.

• Find out why a result ranked where it did

  Read a hit's score back as the clauses and fields you wrote, and find out why a document is missing rather than only why it is low.

• Tuning ranking

  Lift documents with a boost, rank by popularity or freshness with ranking signals, break ties, and rescore the best results, all without reindexing.

Changing an index

• Rolling out a definition change

  Change what an index holds for documents already in it, without callers noticing.

• Reindexing into a new generation

  Have the engine fill the new generation from the one it replaces, instead of sending every document again.

• Changing synonyms without reindexing

  Make a synonym take effect over a catalogue that is already indexed, and decide which side of the search a set belongs on.

• Excluding words from typo tolerance

  Hold a brand name or a model code to its spelling inside a field that forgives mistakes in every other word.

• Surviving Lucene upgrades

  Notice an index nearing the end of its readable life and reindex it in time.

Running a deployment

• Running on one node

  Keep everything on disk with nothing else running, and manage what that costs.

• Running multiple nodes

  Configure indexer candidacy, failover, and how writes find the node that serves them.

• Deploying on Kubernetes

  Configure a pool that searches and a pool that writes, route writes, and handle host requirements for many indexes.

• Authenticating to object storage

  Give a node a key pair, the role of the AWS environment it runs in, or a credentials file that something else renews.

• Securing a deployment

  Bootstrap the first key, hand out one key per client, and rotate keys.

• Running a public demo node

  Answer searches from a browser with no credentials, and narrow what that can cost.

Operating a deployment

• Operating a deployment

  See what each node is serving, tell a node that is behind from one that is broken, and manage disk and upgrades.

• Monitoring a deployment

  Send the meters a node exposes to Grafana Cloud or another backend, keep what a deployment holding hundreds of indexes pays for under control, and choose what to alert on.

• Repairing the index registry

  Audit the registry against what the storage holds, rebuild one that is lost or corrupt, and spot drift before it matters.

• Benchmarking the engine

  Measure searching and indexing, and compare a change against what came before it.