# Search Syntax

Use this when writing `SearchQuery` values for `navigationDefinitions`, product rails, category pages, grids, and shop-wide defaults.

## Query Text

`query`, `keywords`, and `SearchQuery.Query` are backend text queries. Do not treat spaces as OR.

- `query: "lego matchbox playmobil"` is a narrowing query and can return few or no results when products do not match the combined text.
- `query: "lego | matchbox | playmobil"` is the recommended broad OR form for category and rail alternatives.
- Use short product-language terms that actually appear in titles, brands, tags, and descriptions.
- Keep tenant/account scoping in `defaultQuery.SourceAccountId`, not in the user-facing text query.

## Tags

`tags="a,b"` and `SearchQuery.Tags = [a, b]` are narrowing filters. Multiple `SearchQuery.Tags` are narrowing AND-style constraints.

Use multiple tags only when a product should have all of those tags. Do not use comma-separated tags as alternatives for broad categories. For alternatives, prefer an OR query:

```ts
{ label: "Legetøj", slug: "legetoej", query: { query: "lego | matchbox | playmobil" } }
```

Use tags for confirmed shared classification:

```ts
{ label: "Sommerkjoler", slug: "sommerkjoler", query: { query: "kjole | sommerkjole", tags: ["dametøj"] } }
```

## Recommended Category Workflow

1. Run `npx orderly-init-navigation --suggest --account-id <account-id>`.
2. Read `querySyntax` and `navigationSuggestions` in `navigation-products.json`.
3. Prefer suggestions with healthy `matchedProducts` counts.
4. Write `src/navigation.ts` manually with stable unique slugs and at most two category levels.
5. Run the build and fix every warning that says a category page or homepage rail matched 0 products.

For broad categories, start with `Query` OR terms and add tags only after verifying that they do not remove too many products.
