# Catalog and search

The shop, products, variants, collections, pages, blogs, menus and metaobjects, with search, predictive search and recommendations over the store's products.

The catalog is what a storefront reads before a buyer opens a cart: products with their variants and options, plus collections in the store's order and the content and navigation around them. Read a tag filter, a search, a recommendation, a variant picked by its options and a page of results:

```bash
SF=("$RYSTIC_URL/api/2026-10/graphql.json" -H 'X-Shopify-Storefront-Access-Token: placeholder' -H 'Content-Type: application/json')
curl -s "${SF[@]}" -d '{"query":"{ products(first: 10, query: \"tag:summer\") { nodes { handle } } }"}' | jq -c '.data.products.nodes'
# -> [{"handle":"classic-tee"}]
curl -s "${SF[@]}" -d '{"query":"{ search(query: \"tee\", first: 5) { totalCount nodes { ... on Product { handle } } } }"}' | jq -c '.data.search'
# -> {"nodes":[{"handle":"classic-tee"}],"totalCount":1}
curl -s "${SF[@]}" -d '{"query":"{ productRecommendations(productHandle: \"classic-tee\") { handle } }"}' | jq -c '.data.productRecommendations'
# -> [{"handle":"trail-cap"},{"handle":"canvas-tote"},{"handle":"gift-card"}]
curl -s "${SF[@]}" -d '{"query":"{ product(handle: \"classic-tee\") { variantBySelectedOptions(selectedOptions: [{name: \"Size\", value: \"M\"}, {name: \"Color\", value: \"Natural\"}]) { id title } } }"}' | jq -c '.data.product.variantBySelectedOptions'
# -> {"id":"gid://shopify/ProductVariant/9002","title":"M / Natural"}
curl -s "${SF[@]}" -d '{"query":"{ products(first: 2) { nodes { handle } pageInfo { hasNextPage endCursor } } }"}' | jq -c '.data.products.pageInfo'
# -> {"endCursor":"Y3Vyc29yOjI=","hasNextPage":true}
```

### Products and collections

The reads below return each product with its variants and each collection's products in the store's order.

| Read | What it returns |
|---|---|
| `product` by `id` or `handle`, `productByHandle`, `products` | each product with its variants and its `options` with their `values` |
| `collection`, `collectionByHandle`, `collections` | each collection's products, in the store's order |

A variant returns these fields, through `node` and `nodes` too:

- `price` and `compareAtPrice`
- `sku`, `quantityAvailable` and `availableForSale`
- `selectedOptions` and `product`

Every field that returns a product, such as `search` or `collection.products`, also returns these:

- `priceRange` and `compareAtPriceRange`
- each option's `optionValues`
- `variantBySelectedOptions`: the variant whose options equal the pairs you send, or `null`
- `selectedOrFirstAvailableVariant`: that same match, else the first available variant

### Search and recommendations

`products(query:)` filters by `tag:`. `search`, `predictiveSearch`, `productRecommendations` and `productTags` return results from the store's products.

**Differs from Shopify:** the simulator doesn't honor all of Shopify's query syntax, so send plain terms. [Limitations](https://www.rystic.ai/docs/simulators/shopify-storefront.md#limitations) lists what it ignores or misreads.

### Content and navigation

The simulator serves the store's content and navigation through these fields:

| Records | Fields |
|---|---|
| pages | `page`, `pageByHandle`, `pages` |
| blogs and articles | `blog`, `blogByHandle`, `blogs`, `article`, `articles` |
| menus | `menu`, with its nested items |
| metaobjects | `metaobject`, `metaobjects` by `type` |
| redirects | `urlRedirects` |
| the shop | `shop`, `paymentSettings`, `localization`, `publicApiVersions` |

---

Source: https://www.rystic.ai/docs/simulators/shopify-storefront/features/catalog-and-search · Markdown: https://www.rystic.ai/docs/simulators/shopify-storefront/features/catalog-and-search.md