Skip to Content

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=1 adds 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/react holds the search box, results and filters, built on @orbsearch/client. Neither package is on npm yet.

What OrbSearch leaves to you

OrbSearch does notWho does
Decide prices, stock or the purchaseYour checkout, such as OrbCart. Search shows offers; checkout stays authoritative.
Own your product dataYour shop's export, or OrbCatalog's feed.
Count purchases or conversionsYour systems. A storefront reports clicks and views only.
Run on someone else's serversYou 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.

DepthYouExample
ConfigureEdit the release in the admin or the management API.Synonyms, rules, filters and sorting.
ComposeRestyle and rearrange the React components.Tokens, data-slot styles, a tile built from its parts.
ReplaceDraw 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 toRead
See it runQuickstart
Understand the modelConcepts
Search your own catalogYour own catalog
Build the storefront sideYour storefront
Give it your shop's lookCustomize
Know what works todayStatus

On this page