Skip to main content

Scenarios

A scenario is a saved query given a stable, public name, so the app that shows recommendations can keep calling that one name while you change everything behind it. Your storefront asks for "cart"; you decide, and keep deciding, what "cart" actually returns.

It is the seam between the people who build the recommender and the people who consume it. On one side, a developer wires a placement to a scenario name once. On the other, you tune the query, swap the engine, or add a rule, and the caller never changes.

What a scenario is​

A scenario has three parts:

  • A name — the contract. "cart", "home-feed", "similar-items". This is what callers hit and the one thing you do not casually rename.
  • An engine — the recommender that serves it. A scenario belongs to exactly one engine, and the engine behind a name can be replaced without the name changing.
  • A query — the logic that turns a request into a ranked list, written in SIDEQL. See SIDEQL in the Platform docs for the language itself; this page is about the scenario wrapped around it.

Placements and query examples​

The list splits into two groups, and the difference matters:

  • Placements — scenarios tagged as a real user-facing surface. These are the names your app calls in production. A placement is a promise you are keeping to live traffic.
  • Query examples — techniques promoted from the playground ("Collaborative Filtering", "HyDE search") kept as reference, not wired to a surface. Read them to learn a pattern; do not point production at one by accident.

When you build a new placement, start from a query example that does the right kind of retrieval, then give it a production name and tune it.

Reading one scenario​

Open a scenario and the workspace shows the whole contract on one screen:

  • Logic (SIDEQL) — the query template. The parts that change per request are parameters, not hard-coded values.
  • Parameters — the runtime inputs the caller supplies, with the defaults used in preview: user_id, count, and whatever else the query names.
  • Rules — filters and boosters attached to this scenario. A filter narrows the result (never show out-of-stock); a booster multiplies score (favor fresh content). Rules compose server-side, so a caller cannot forget to apply one.
  • Preview — the scenario run live against its engine, with catalog metadata and thumbnails where available, plus timing: engine execution time and the round-trip a caller would see.

Run executes the scenario as it stands. Save persists your edits, and from then on /v2 runs the saved version by name.

The five scenario types​

The type tells the engine what shape of answer to return:

  • Search — results for a text query.
  • Items to user — a personalized feed for one member.
  • Items to item — things related to a given item ("more like this").
  • Segments to user — which audiences a member belongs to.
  • Composite — a query that combines more than one of the above.

A scenario's type is chosen to match the placement it serves; the query example you start from already carries the right one.

Calling a scenario from your app​

A scenario is executed by name over the /v2 API. The Integration snippet on each scenario gives you the exact call:

curl -X POST \
  "$SIDE_BASE_URL/v2/engines/{engine}/queries/{name}" \
  -H "x-api-key: $SIDE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "user_id": "…", "count": 20 }'

SIDE_BASE_URL is https://api.nextgres.ai; SIDE_API_KEY comes from the API Keys page. The body carries the scenario's parameters. For a typed client instead of raw HTTP, use the Python or TypeScript SDK.

Because the call names the scenario, not the query, the request your app sends is stable. That is the whole point of the next section.

Why the name is the contract​

The value of a scenario is that the name outlives everything behind it. Once "cart" is live, you can:

  • rewrite its SIDEQL,
  • retrain or swap the engine it points at,
  • attach a new rule,

and no caller changes, no app ships, no coordination happens. An A/B test is just a scenario temporarily routing traffic between two versions of the logic under the one name.

This is also the discipline the name imposes: renaming a live placement breaks every caller hitting the old name, so treat the name as public API and change the insides freely instead.

What a scenario connects to​

  • The engine that serves it (train and configure it under Engines).
  • The rules attached to it (filters and boosters).
  • The loops that run it on a schedule or a trigger, rather than waiting for a caller.
  • KPI, which reports what each scenario actually did once callers start hitting it.