ORBSEARCH DOCUMENTATION
OrbSearch
OrbSearch finds products in your catalog, understands the query and explains every result. What it does, what it leaves to you and where to start.
OrbSearch is search and discovery for a shop. Meilisearch retrieves; OrbSearch understands the query, applies your rules and explains every result. The engine is its own open-source project, and its documentation lives at orbsearch.dev/docs. This page orients you and links there.
A search is one call to the Query API, which needs no key. In the engine's example store, a furniture shop that sells in German:
curl -s 'http://127.0.0.1:7800/v1/search?query=graues%20Sofa' \
| jq -c '.resolution, [.sections[] | select(.type == "product") | .hits[].entity]'"Sofa" names the category wohnen/sofas and "graues" the colour grey, so the answer lists the two grey sofas and nothing else. The quickstart runs this on your machine in a few minutes.
What OrbSearch does
- Reads what the query names. "graues Sofa" becomes the sofas filtered to grey, and "weiss" finds "Weiß". The import reads units, option spellings and colour groups as their attributes define them.
- Explains every result.
debug=1adds a trace of every step, and every answer names the release and catalog snapshot it came from. - Takes the export you already write. CSV, Excel, a Google Merchant Center feed or JSON; OrbSearch derives the attributes, filters and sorting from the data. See your own catalog.
- Publishes configuration as a release. Synonyms, rules and facets go live together, and publishing an earlier release is a rollback.
- Answers with a section per entity type: categories, products, content and brands. A category's page in search lists the products of the categories below it.
- Brings the storefront side.
@orbsearch/reactholds the search box, results and filters, built on@orbsearch/client. Neither package is on npm yet.
What OrbSearch leaves to you
| OrbSearch does not | Who does |
|---|---|
| Decide prices, stock or the purchase | Your checkout, such as OrbCart. Search shows offers; checkout stays authoritative. |
| Own your product data | Your shop's export, or OrbCatalog's feed. |
| Count purchases or conversions | Your systems. A storefront reports clicks and views only. |
| Run on someone else's servers | You do: one Docker Compose stack on one machine. See self-hosting. |
Status lists every limit OrbSearch has today.
Change what you need
Everything in OrbSearch changes in one of three ways, from shallow to deep.
| Depth | You | Example |
|---|---|---|
| Configure | Edit the release in the admin or the management API. | Synonyms, rules, filters and sorting. |
| Compose | Restyle and rearrange the React components. | Tokens, data-slot styles, a tile built from its parts. |
| Replace | Draw a part with a component of your own. | A facet display of your own. |
In the shared admin, Search holds Insights, Synonyms, Rules, Search settings, Filters and sorting and Search releases. Every change there goes into OrbSearch's draft, and the Search edit role writes it.
With OrbCatalog
OrbSearch needs none of its siblings: it takes any shop's export. With OrbCatalog, OrbSearch polls the catalog's feed every 10 to 1440 minutes, and the catalog pushes offer changes as they happen, so a price is live in search in seconds. Connect the products shows the configuration.
Next steps
| You want to | Read |
|---|---|
| See it run | Quickstart |
| Understand the model | Concepts |
| Search your own catalog | Your own catalog |
| Build the storefront side | Your storefront |
| Give it your shop's look | Customize |
| Know what works today | Status |