# OrbSearch

> Open-source search and discovery for commerce on Meilisearch. Every page below is also plain Markdown at its path plus .md, such as /docs/quickstart.md; /docs/llms-full.txt holds them all, /docs/openapi.json describes both APIs.

- Guide

  - **Getting started**
  - [Overview](/docs/): OrbSearch is open-source search and discovery for commerce. Meilisearch retrieves; OrbSearch understands the query, applies the merchant's rules and explains every result.
  - [Quickstart](/docs/quickstart): Run OrbSearch on your machine, load a small furniture store and read why a search found what it found.
  - [Your own catalog](/docs/your-own-catalog): Send the export your shop already writes and search it, without writing any configuration first.
  - [Concepts](/docs/concepts): How OrbSearch is shaped, from what a merchant sends to what a shopper gets back.
  - [Status](/docs/status): The limits you meet in OrbSearch today, each stated plainly.

  - **Search**
  - [How search understands a query](/docs/query-understanding): OrbSearch reads what a query names in the shop's own words, such as a category, a color or a width, and searches only the words that are left.
  - [Search and browse](/docs/search): One endpoint answers every search, category page and search box; send a link or a JSON body and read what comes back.
  - [Autocomplete](/docs/autocomplete): Suggest searches, categories and products while the shopper types, from one request after each pause in typing.
  - [Facets and filters](/docs/facets): Read the facets a page answers with, send the shopper's choices as filters, and count a facet when the shopper opens it.
  - [Sorting](/docs/sorting): Draw a page's sort control from the answer, send the shopper's choice, and read why a page starts in the order it does.
  - [Category pages](/docs/category-pages): Browse a category without words, with its products, its subcategories and the banners placed on it.
  - [Product pages](/docs/product-pages): Fetch one product as its page shows it, with its offer, details and variants, by its id or its URL.
  - [When nothing is found](/docs/no-results): A search whose named filters match nothing steps back until it finds products, and says what it left out.
  - [URLs and redirects](/docs/urls): Serve the merchant's own URLs, keep a listing's state in its URL, and carry the old shop's links over.

  - **Merchandising**
  - [Synonyms](/docs/synonyms): Tell OrbSearch which words mean the same, so a shopper who types "couch" finds the sofas.
  - [Patterns](/docs/patterns): Turn a phrase of the query, such as "bis 220 cm", into a filter, so shoppers find what fits.
  - [Fields and typos](/docs/fields-and-typos): Choose which fields a search reads, in which order, and how many typos it forgives.
  - [Rules: pin, boost, bury, hide, redirect](/docs/rules): Put a product first, move others up or down, hide one or send a search elsewhere, each with a rule whose condition and effects the trace explains.
  - [Ranking](/docs/ranking): How OrbSearch orders the products that match equally well, by a business score from your catalog's sales, ratings and dates, and how to read why a product stands where it does.
  - [Pages and their filters](/docs/pages): Choose the filters and sorting of each page, so the sofa page offers width and seats and the lamp page the light source.
  - [Banners and teasers](/docs/banners): Put a campaign's banner or a teaser to another page on a category page, with the condition, window, order and trace of a rule.
  - [Sponsored products](/docs/sponsored-products): Sell a brand the first place in a search, mark the product as an ad on the storefront, and count its views and clicks for the campaign report.
  - [Releases: draft, preview, publish, roll back](/docs/releases): Change the search configuration in a draft, see it as shoppers will, publish it the way the change needs and go back to an earlier release.

  - **Catalog**
  - [Formats we read](/docs/formats): The exports OrbSearch reads as your shop writes them, how it recognizes each one, and OrbSearch JSON Lines, its own format.
  - [Importing and mapping](/docs/importing): Keep an export as an import, see what it becomes, correct how its columns are read, then publish it.
  - [The import report](/docs/import-report): Read what every index run took in and what it left out: each row and value with its reason, and each setting it derived.
  - [Feeds on a schedule](/docs/feeds): Let OrbSearch fetch your shop's export from its URL on a schedule, so the catalog stays current on its own.
  - [Types and attributes](/docs/types-and-attributes): Say what each entry of the catalog is and what its values mean, so "164 cm" filters as a width and "Samt" shows as velvet in English.
  - [Variants](/docs/variants): Sell a product in colors and sizes, each variant with its own price and stock, and show the one the shopper filtered for.
  - [Channels](/docs/channels): Set up the markets a shop sells in, each with its languages, currency, countries and the products it carries.
  - [Overlays](/docs/overlays): Correct the catalog's data for search, add search words or give products badges, and keep it all when the next export arrives.
  - [Live prices and stock](/docs/prices-and-stock): Change a price, a sale or the stock between two catalogs, and search shows it within seconds, without an index run.

  - **Storefront**
  - [Your storefront](/docs/your-storefront): Run a shop on the home store in a few minutes, with the search box, listing and product pages of the React components.
  - [Customize](/docs/customize): Give the storefront your shop's look and parts in four steps, from a few tokens to components of your own.
  - [React components](/docs/react): The search box, listing and product pages for React 19, built on the client, with every part yours to restyle or swap.
  - [The client](/docs/client): Call the Query API from any storefront with typed requests and answers, and read and write a listing's URL.
  - [Theming](/docs/theming): Every --orb-* token, the contrast pairs the defaults meet, the slots parts carry, and the components' styles with or without Tailwind.
  - [Accessibility](/docs/accessibility): What the storefront components do for keyboard, focus and screen reader users, and what stays your shop's to set.
  - [Clicks and views](/docs/clicks-and-views): Report what shoppers click and see after a search, so Insights shows the searches that find what nobody opens.
  - [Recipes](/docs/recipes): Complete storefront code for two common layouts, one facet of your own and filters in a sheet on a phone.

  - **Insights**
  - [Insights](/docs/insights): What shoppers search and click, what finds nothing and the filters they choose, from a search log the Query API keeps off the read path, masked before it is stored.

  - **Agents**
  - [Agents](/docs/agents): Shoppers, merchants and developers act through AI agents too, so every surface of OrbSearch answers an agent as it answers a person.

  - **Operate**
  - [Self-hosting](/docs/self-hosting): Run OrbSearch in production with Docker Compose on one machine, behind a proxy that terminates TLS.
- Reference

  - **APIs**
  - [Conventions](/docs/reference/conventions): What the Query API and the management API share, from JSON and ids to keys, problems and the OpenAPI document.
  - [Query API](/docs/reference/query-api): The public, read-only API storefronts, browsers and agents ask: searches, product pages, URLs and robots.txt.
  - [Management API](/docs/reference/management-api): The control plane's API for catalogs, imports, releases, rules, synonyms and index runs, called with the management key.
  - [Events API](/docs/reference/events-api): Clicks on and views of an answer's hits and banners, as a storefront reports them for Insights.

  - **Release files**
  - [attributes.json](/docs/reference/release-files/attributes): What each attribute value means.
  - [categories.json](/docs/reference/release-files/categories): The facets and sort options of search and category pages.
  - [channels.json](/docs/reference/release-files/channels): The channels a merchant sells in, and the context keys requests may carry.
  - [overlays.json](/docs/reference/release-files/overlays): Corrections to catalog data, applied when documents are built.
  - [patterns.json](/docs/reference/release-files/patterns): Query patterns that become filters.
  - [ranking.json](/docs/reference/release-files/ranking): Signals and weights, boost and bury strengths, sort options and section order.
  - [redirects.json](/docs/reference/release-files/redirects): The old shop's URLs.
  - [relations.json](/docs/reference/release-files/relations): What links between entities mean.
  - [routes.json](/docs/reference/release-files/routes): The merchant's URLs.
  - [rules.json](/docs/reference/release-files/rules): The rules in precedence order.
  - [synonyms.json](/docs/reference/release-files/synonyms): A synonym dictionary per language.
  - [tests.json](/docs/reference/release-files/tests): Search tests, checked before every publish.
  - [types.json](/docs/reference/release-files/types): The entity types a release searches, and how each is listed, searched and returned.

  - **Catalog**
  - [entity.json](/docs/reference/catalog/entity): Anything that can be found: a product, a category, a guide, a brand or an entity of the merchant's own type.
  - [feed.json](/docs/reference/catalog/feed): How the shop's export is read and where each of its columns goes.

  - **Answers**
  - [The trace](/docs/reference/trace): Why an answer is what it is: every step a search, a page or a product lookup took, with what it decided.
  - [Problems](/docs/reference/problems): Every error either API answers with: an RFC 9457 problem, the statuses it comes with and when.
  - [Limits](/docs/reference/limits): What one request, rule, release or call may hold at most, and why each limit sits where it does.

  - **Configuration**
  - [Environment variables](/docs/reference/environment): Every setting of the stack's .env, what it does, its default and the services that read it.
  - [Ports and services](/docs/reference/services): The services of the compose stack: what each runs, the ports it listens on and the volumes it keeps.

  - **Glossary**
  - [Glossary](/docs/reference/glossary): Every term the API, the panel and these docs share, in one sentence each, with the page that explains it.