Skip to main content

Set Up Your First Project

Use this playbook after you create a project and connect a data source. It shows the fastest path to a usable first project, then explains the modeling and knowledge setup that improves answer quality over time.

First-Time User Checklist​

Use this as a practical setup sequence for your first Wren AI project:

Day 1-2: Connect and model​

  • Connect your main warehouse (Snowflake, BigQuery, and similar sources).
  • Select 5-10 key tables for your first use case.
  • Use the Modeling AI Assistant to generate initial semantics and relationships.
  • Refine descriptions for your primary metrics, entity IDs, and date fields.

Learn more in First Project Best Practices.

Day 3: Configure Instructions​

  • Add global rules for exclusions, date defaults, formatting, charts, and summaries.
  • Add 2-3 question-matching instructions for recurring concepts like late delivery or YoY comparison.

Learn more in First Project Best Practices.

Day 4-5: Add Question-SQL Pairs​

  • Identify 5-10 critical metrics.
  • Import the trusted SQL behind those metrics.
  • Map each metric to a clear natural-language question.

Learn more in First Project Best Practices.

Day 6: Iterate with real questions​

  • Collect actual questions from stakeholders.
  • Save strong answers as Question-SQL Pairs.
  • Turn repeated corrections into Instructions.
  • Update semantics when the AI chooses the wrong tables, joins, or definitions.

Learn more in First Project Best Practices.

What “Context Engineering” Means in Wren AI​

In Wren AI, you shape the AI’s behavior mainly through:

  1. Semantics (data modeling & MDL) – how tables, columns, joins, and metrics are described and categorized so the AI understands what the data means and how to join/aggregate it correctly.
  2. Instructions – reusable rules that tell the AI how to think about SQL generation, charts, and summaries (e.g., which statuses to exclude, how to format money, how to define “late delivery”).
  3. Question-SQL Pairs – “gold-standard” examples that pin specific natural-language questions to exact SQL, for complex metrics and error-prone logic.

Think of it like this:

  • Semantics = dictionary + schema
  • Instructions = house rules
  • Question-SQL Pairs = worked examples

Your job as a context engineer is to push as much knowledge as possible into these three layers, so ad-hoc questions become safe, consistent, and predictable.

Project Scoping & Domain Boundaries (Avoid the “One Giant Graph” Trap)​

Best practice

Create separate Wren AI projects per business use case / domain, instead of building one huge, mixed graph for the entire company.

Why

  • Different domains often have different definitions for the same term
  • e.g. “Revenue” in Finance vs “Revenue” in Marketing vs “GMV” in Ops
  • A single giant graph with mixed semantics makes it much easier for the AI to:
    • Pick the wrong tables/metrics
    • Mix conflicting definitions
    • Produce more hallucinations or subtly wrong answers
    • Smaller, focused projects give you:
      • Cleaner semantic layers
      • Clearer Instructions and Question-SQL Pairs per domain
      • Easier governance and testing

How to scope projects​

Use separate projects for things like:

  • Marketing & Growth analytics (campaigns, channels, attribution, CAC, ROAS)
  • Product analytics (events, feature usage, funnels, retention)
  • Sales & Revenue (pipeline, bookings, MRR, ARR)
  • Operations / Supply chain / Manufacturing (lead times, yield, utilization, defects)

If a domain:

  • Has its own owners/stakeholders, and
  • Has its own metric definitions / dashboards,

...it almost always deserves its own Wren AI project.

Rule of thumb​

If you start seeing:

  • Long lists of tables no one understands,
  • Multiple “Revenue” or “LTV” definitions colliding,
  • Instructions that only apply to some teams,

...you’ve probably made the project too big.

Split by business use case, keep each project coherent and opinionated, and the AI will hallucinate less and behave more like a domain expert.