Skip to content
Querion

Querion / Guides

Usage examples

Question shapes that work well with Querion, worked examples for the main tasks, and the requests it refuses.

On this page
  1. Phrasing that works, and why
  2. Trends and comparisons
  3. Rankings
  4. Live status (HTTP sources)
  5. Cross-source
  6. Requests Querion refuses
  7. Running one from the terminal
  8. Worked examples
  9. Ask a question and read the steps
  10. Compare the database with a live API
  11. See a refusal
  12. Give the model a curated schema
  13. Ask through the web API

Querion is platform agnostic, so phrase questions in your own domain. The question shapes below come from examples/questions.md in the repository. The worked examples after them show what each main task looks like from the terminal.

Phrasing that works, and why

The model knows only what Querion gives it: your schema, your application programming interface (API) docs, today’s date and the results of its own reads. Good questions follow from that.

  • Name the metric and the period. “Revenue by week for the last 8 weeks” leaves less to guess than “how are sales”. The prompt includes today’s date and week number, so relative periods such as “this month” resolve against the host’s clock. The prompt also tells the model to flag the current period as partial when it compares it with closed ones.
  • Ask for summaries, not dumps. The model sees at most 30 rows of any result. Totals, rankings and top-N lists let the database do the counting.
  • Say “with a chart” when you want one. The prompt tells the model to chart only data it has fetched, so it first runs the query, then draws.
  • Say “live” or name the platform for current state. The model chooses between Postgres and your APIs per question. Saying which one you mean removes the guess.
  • “Revenue by week for the last 8 weeks, with a chart.”
  • “New vs returning customers this month versus last month.”
  • “Average order value by month this year.”

Rankings

  • “Top 10 products by revenue this quarter.”
  • “Which customers spent the most in the last 90 days?”

Live status (HTTP sources)

These need a configured source. See Connecting data sources.

  • “What is the live status of order 14377?”
  • “How many open invoices does customer 88 have right now?”

Cross-source

  • “Compare this month’s orders in the database with the live count from the API.”
  • “Which orders in Postgres are still marked open but show paid in the API?”

Requests Querion refuses

  • “Cancel order 14377.”
  • “Update the price of SKU X.”
  • “Delete the test customers.”

Asking Querion to change data is refused. Asking about past changes, such as “which orders were cancelled last week?”, is normal analytics and is answered. For how the refusal works, and which parts are deterministic, read the safety model.

Running one from the terminal

querion ask "Top 10 products by revenue this quarter"

The output lists the steps taken, then the answer, and a note when charts were generated.

Worked examples

Ask a question and read the steps

querion ask "revenue by week for the last 8 weeks, with a chart"

The command prints one line per step, naming the directives that ran, then the answer. A chart can only use data the model has already fetched, so the query and the chart usually come in separate steps. The output has this shape:

Querion is thinking (opus)...

  step 1: sql
  step 2: chart

<headline, compact table, and the query in a sql block>

[1 chart(s) generated]

The chart image is in the system temporary directory as querion_chart_*.png. The model is told the path and may include it in the answer.

Compare the database with a live API

With a source named example configured, ask a cross-source question:

querion ask "compare this month's orders in the database with the live count from the API"

The prompt lets the model put independent reads in the same turn, so a step line such as step 1: sql, source:example means both reads ran together. A read that depends on an earlier result, such as looking up the ids a query returned, comes in a later step.

See a refusal

A pasted write statement is caught before any model call:

querion ask "DELETE FROM customers WHERE id = 1"
Querion is thinking (opus)...

Read-only firewall: Querion never modifies data (contains a SQL write statement: DELETE FROM customers WHERE). Nothing was executed.

A plain-English request, such as “cancel order 14377”, goes to the model, which is instructed to refuse. When it does, the output reads Read-only firewall: that asked Querion to change data (...). Querion never writes. Nothing was executed. The note in brackets is the model’s description of the write it was asked for.

Give the model a curated schema

When the model guesses table names, or your database is large, write the schema yourself:

querion introspect -o docs/schema.md

Edit the file to remove tables the model should ignore and to add what the names do not say, such as units and status values. Then point the config at it:

database:
  dsn: ${QUERION_DATABASE_DSN}
  schema_doc: docs/schema.md

The path is relative to the directory that holds querion.yaml. Restart querion serve to load it; querion ask reads it on the next run.

Ask through the web API

Start the server, then post a question and poll for the result:

querion serve &
curl -s -X POST http://127.0.0.1:8000/api/ask \
  -H 'Content-Type: application/json' \
  -d '{"question": "average order value by month this year"}'
curl -s http://127.0.0.1:8000/api/ask/<id>

The response fields are listed in CLI and web API.