Instructions

Instructions are guidelines that help direct how Wren AI generates SQL queries and responses. They allow you to define business rules, data model understanding, and query patterns to ensure consistent, accurate results aligned with your organization's specific needs.

Instructions come in two forms:

• Global Instructions: Applied to all queries, regardless of the question asked
• Question-Matching Instructions: Applied only when a user's question matches certain patterns or topics

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
• Standardize output formatting for better readability

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.

Adding Global Instructions

To add a Global Instruction:

1. Navigate to the Knowledge tab
2. Click the "Add an Instruction" button
3. Select "Global" under "Apply instruction to"
4. Enter your instruction details in the text field
5. 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.

More Examples

Round to 2 Decimal Places

Always round all floating point numbers (e.g., revenue, averages, percentages) to 2 decimal places using the `ROUND(..., 2)` function in SQL.

Use LEFT JOIN for Optional Tables

Always use LEFT JOIN when joining optional or non-required tables like reviews or payments, to prevent loss of rows.

Output Column Alias with specific language

Always output column alias with Traditional Chinese.

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.

Adding Question-Matching Instructions

To add a Question-Matching Instruction:

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

Example - Late Deliveries Analysis

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.

More Examples

For questions about "product return rate" or "return ratio"

Match questions that contain "product return rate" or "return ratio".

Olist does not explicitly include returns, so treat orders with `order_status = 'canceled'` as proxy for returned/canceled orders.
Use the ratio of canceled orders to total orders.

For questions about "seller performance" or "top sellers"

Match questions that contain "seller performance" or "top sellers".

Aggregate revenue and order counts by `seller_id` from `olist_order_items_dataset`. Join with `olist_orders_dataset` to apply filters like date or status.

Managing Instructions

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