Instructions

Instructions are guidelines that help direct how Wren AI generates results, including SQL queries, charts, and summaries. They allow you to define business rules, data model understanding, and query patterns to ensure consistent and accurate outputs aligned with your organization’s specific needs across every result type.

Instructions support three scopes:

• When generating SQL queries: Instructions guide how SQL should be interpreted, structured, joined, filtered, and formatted based on your business rules and data model.
• When generating charts or visuals: Instructions influence how charts are generated, including default chart type, grouping and sorting logic, metric calculation, labeling, and how business metrics should be visually represented.
• When summarizing query results: Instructions determine how results should be interpreted and described in plain language, including terminology, domain context, aggregation explanation, and how insights should be communicated.

Instructions come in two forms:

• Global Instructions: Global Instructions apply to every query that Wren AI generates. They're ideal for setting consistent standards, enforcing business rules, and guiding how Wren AI interprets your data model.
• Question-Matching Instructions: Question-Matching Instructions are applied only when a user's question matches certain patterns or topics. They're ideal for guiding how Wren AI should handle specific business concepts, metrics, or types of analysis.

By configuring Instructions, you can:

• Enforce consistent naming conventions and formatting
• Implement business rules and data filtering standards
• Guide how specific business concepts should be calculated
• Ensure proper table joins and relationships are used correctly
• Standardize output formatting for better readability

Global Instructions

Adding SQL queries Instructions

To add a Global Instruction:

1. Navigate to the Knowledge tab
2. Click the "Add an Instruction" button
3. Select "When generating SQL queries"
4. Select "Global" under "Apply instruction to”
5. Enter your instruction details in the text field
6. Click "Submit" to save and apply the instruction

Example - Order Status Filtering

A common need is to ensure consistent handling of order statuses in calculations. Here's an example of a Global Instruction that standardizes order filtering:

Exclude orders with `order_status IN ('canceled', 'unavailable')` from any sales or revenue-related calculations.

With this instruction in place, when a user asks "What was our total revenue last month?", Wren AI will generate SQL that includes proper filtering:

As you can see, the SQL query includes the WHERE clause that excludes canceled and unavailable orders from the calculation.

Adding charts and visual Instructions

To add a Global Instruction:

1. Navigate to the Knowledge tab
2. Click the "Add an Instruction" button
3. Select "When generating charts or visuals"
4. Select "Global" under "Apply instruction to”
5. Enter your instruction details in the text field
6. Click "Submit" to save and apply the instruction

Example – Proportion Chart Visualization Rules

It is important to maintain consistent visual rules when generating charts. Here’s an example of a Global Instruction that standardizes how proportions are visualized:

1. Specify chart type

   When visualizing proportions, always use a bar chart.

2. Specify chart color

   The largest category should always be highlighted in yellow.

By configuring this as a Global Instruction, chart outputs will automatically follow a unified visual logic without manual adjustments.

Adding summarizing query result Instructions

To add a Global Instruction:

1. Navigate to the Knowledge tab
2. Click the "Add an Instruction" button
3. Select "When summarizing query results"
4. Select "Global" under "Apply instruction to”
5. Enter your instruction details in the text field
6. Click "Submit" to save and apply the instruction

Example – Comparison Summary Standardization

A common requirement is to ensure consistent phrasing when summarizing comparison results. Here’s an example of a Global Instruction that standardizes how comparison summaries are generated:

1. Format Definition

   The first sentence must start with: “Here is the analysis summary:”

2. Required Analytical Content

   The summary should also include the potential cause of the difference if it can be reasonably determined.

3. Content Constraints

   Avoid adding excessive contextual background. Keep the phrasing concise and report-style.

By configuring this as a Global Instruction, summaries will consistently present comparison results in a direct, concise, and easily comparable format.

Question-Matching Instructions

Adding SQL queries Instructions

To add a Question-Matching Instruction:

1. Navigate to the Knowledge tab
2. Click the "Add an Instruction" button
3. Select "When generating SQL queries"
4. Select "Matched to specific questions" under "Apply instruction to”
5. Enter your instruction details in the text field
6. Click "Submit" to save and apply the instruction

Example - Order Status Filtering

For questions about delivery performance, you might want to ensure consistent definition of what constitutes a "late delivery." Here's an example of a Question-Matching Instruction for this purpose:

Matching Questions:

• What is our late delivery rate?
• How many orders were delayed?
• What percentage of deliveries are late?

Instruction Details:

Use the difference between `order_estimated_delivery_date` and `order_delivered_customer_date` from `olist_orders_dataset`. 
If the delivered date is later than the estimated date, consider it a late delivery.

When a user asks "What percentage of our deliveries were late?", Wren AI will generate SQL that accurately calculates late deliveries based on your defined criteria:

The answer shows the percentage of deliveries that were late.

As you can see, the SQL query compares the order_estimated_delivery_date and order_delivered_customer_date from the olist_orders_dataset table, as defined in the instruction.

This ensures consistent methodology when analyzing delivery performance across your organization.

Adding charts and visual Instructions

To add a Question-Matching Instruction:

1. Navigate to the Knowledge tab
2. Click the "Add an Instruction" button
3. Select "When generating charts or visuals"
4. Select "Matched to specific questions" under "Apply instruction to”
5. Enter your instruction details in the text field
6. Click "Submit" to save and apply the instruction

Example – Question-Matching Instruction (Charts)

Applies when question contains: “top 5”, “highest 5”, “largest 5”

Instruction:

When users ask for top 5 comparison, always return a horizontal bar chart sorted descending by value.
The highest category should be highlighted in yellow.

Adding summarizing query result Instructions

To add a Question-Matching Instruction:

1. Navigate to the Knowledge tab
2. Click the "Add an Instruction" button
3. Select "When summarizing query results"
4. Select "Matched to specific questions" under "Apply instruction to”
5. Enter your instruction details in the text field
6. Click "Submit" to save and apply the instruction

Example – YoY Comparison Summary Rules

Applies when question contains: “year over year”, “YoY”

Instruction:

When summarizing YoY questions, explicitly mention the direction of change (increase or decrease) and include the YoY % delta in the first sentence.
Do not include monthly breakdown unless user explicitly asks for it.

Managing Instructions

You can view, edit, and delete your instructions from the Instructions management page: