Skip to main content

Domain context

Generic table names work for generic questions. Real businesses have acronyms, metric definitions, naming conventions, and "obvious" facts that aren't obvious to a model with no context.

Domain context is how you teach Qry these things once and have them apply to every conversation afterward. Without it, you'll keep explaining what MRR, CAC, active customer, or cohort 2024-Q1 means every single conversation. With it, Qry just knows.

Domain context is a Skill

Domain context is the everyday name for an instruction Skill that is always applied. The scopes below are Skill scopes, and Skills also hold reference documents, step-by-step procedures and scripts. This page covers the most common case: teaching Qry your vocabulary.

What domain context is​

A free-form text block — Markdown is fine — with a scope. The text is included in every conversation the scope covers:

  1. Personal — all of your conversations.
  2. Workspace — conversations in that workspace, for every member.
  3. Datasource — conversations that use that datasource.
  4. Company-wide — every conversation. Set by an admin.

Scopes add up rather than override: if the company-wide skill defines MRR and you redefine it personally, both definitions reach the model. Keep definitions in one place to avoid that.

What to put in it​

Three categories of fact carry the most weight:

1. Acronyms and metric definitions​

- MRR (Monthly Recurring Revenue): SUM(monthly_subscription_amount) for
all customers with status='active' on the snapshot date.
- CAC (Customer Acquisition Cost): marketing_spend / new_customers in
the same period.
- Active customer: at least one transaction in the last 90 days, where
"transaction" means orders.status = 'completed'.

2. Naming conventions​

- Tables prefixed `dim_` are dimensions; `fct_` are facts; `stg_` are
staging — never query staging tables directly.
- Columns named `_id` are foreign keys; `_at` columns are timestamps in
UTC; `_date` columns are local-timezone dates.
- The `customers` table is deprecated; always use `customers_v2`.

3. Business rules and edge cases​

- Fiscal year starts July 1, not January 1.
- Internal employees (email ends in @example.com) are excluded from all
customer-facing metrics.
- The `region` column has values 'EMEA', 'NA', 'APAC' — anything else
is a data-quality issue, exclude or flag.

What NOT to put in it​

  • Schema details Qry can already see. Table names, column names, types — Qry introspects these. Repeating them in domain context wastes tokens.
  • Per-conversation instructions. "Be terse", "only use SQL never Python" belong in the prompt or memory, not in domain context.
  • Sensitive values. The domain context is included in every relevant prompt — don't put credentials, API keys, or PII in it.

Where to set it​

  • Personal, datasource or company-wide: in Skills (in the navigation, under AI), create an Instruction skill and choose its scope. Datasource and company-wide skills need the corresponding rights.
  • Workspace: in the workspace's settings, Workspace instructions — the same skill, also editable in Skills under the workspace.

Edits take effect on the next conversation turn.

Common issues​

Qry still gets a metric definition wrong after I added it to domain context. The model usually obeys but occasionally falls back to a more "common" definition of an acronym. Add an example query alongside the prose:

- MRR is defined as SUM(monthly_amount) WHERE status='active'.
Example: SELECT SUM(monthly_amount) FROM subscriptions
WHERE status = 'active' AND snapshot_date = CURRENT_DATE;

Domain context is too long, conversations feel slow. Domain context counts against the model's context window. If you've added a 50-table schema there, trim it back. Keep domain context to the non-obvious — Qry can read schema by itself.

Personal and workspace contexts conflict. The model gets both and uses its judgment. If conflicts are real, change one of the two so they're consistent.

An admin changed the company-wide context and I am not sure what is in it. Open Skills and look at the company-wide scope — you can read what applies to you, and the tester shows what a given question would load.

See also​