Custom Instructions

Overview

Custom Instructions allow you to provide context, terminology definitions, and business rules that help the Data Assistant understand your specific data model and give more accurate responses.

Why Use Custom Instructions?

Every organization has unique terminology, data structures, and business logic. Custom Instructions bridge the gap between your internal knowledge and Cobi’s understanding of your data.

Define Terminology

Map your business terms to database tables and columns

Explain Relationships

Clarify how tables connect and what joins are appropriate

Set Business Rules

Define how to calculate metrics like revenue, active users, or churn

Improve Accuracy

Help Cobi write correct queries on the first try

Adding Custom Instructions

Open Data Connectors

Navigate to Developer > Data Connectors in the sidebar.

Select Your Connection

Click on the data source you want to configure.

Go to Custom Instructions Tab

In the connection modal, click the Custom Instructions tab.

Add Your Context

Enter your instructions in plain text. Be specific and comprehensive.

Save Changes

Click Save Changes to apply your instructions.

What to Include

Business Context

Start with a high-level description of what your database contains:

This is a sports facility management database for a tennis club.

Key Terminology

Define terms your team uses and map them to database concepts:

Key terminology:
- "Members" = users with active package subscriptions
- "Courts" = playing facilities (can have sub-courts)
- "Bookings" = court reservations
- "Lessons" = private coaching sessions (instructor_bookings table)
- "Programs" = group classes, camps, clinics

Revenue Sources

Explain where different metrics come from:

Revenue comes from:
Court bookings (bookings table)
Private lessons (instructor_bookings table)
Program enrollments (program_enrollments table)
Membership fees (via Stripe subscriptions)

Query Guidance

Provide specific instructions for common questions:

When asked about "revenue", sum the `total` field from bookings and instructor_bookings.
When asked about "members", count users with active package_user_mappings.
Payment status 1 = paid, 0 = unpaid.
Booking status 1 = confirmed, 0 = pending, 2 = cancelled.

Example: Complete Custom Instructions

Here’s a full example for a sports facility:

This is a sports facility management database for a Padel/Tennis club.

Key terminology:
- "Members" = users with active package subscriptions
- "Courts" = playing facilities (can have sub-courts)
- "Bookings" = court reservations
- "Lessons" = private coaching sessions (instructor_bookings table)
- "Programs" = group classes, camps, clinics

Revenue comes from:
1. Court bookings (bookings table)
2. Private lessons (instructor_bookings table)
3. Program enrollments (program_enrollments table)
4. Membership fees (via Stripe subscriptions)

When asked about "revenue", sum the `total` field from bookings and instructor_bookings.
When asked about "members", count users with active package_user_mappings.
Payment status 1 = paid, 0 = unpaid.
Booking status 1 = confirmed, 0 = pending, 2 = cancelled.

Best Practices

Be Specific

Instead of “customers are in the users table”, say “customers are stored in the users table, identified by the id column, with user_type = 'customer' to distinguish from staff accounts.”

Document Status Codes

Many databases use numeric codes for statuses. Always document what they mean:

Order status codes:
- 0 = draft
- 1 = pending payment
- 2 = paid
- 3 = shipped
- 4 = delivered
- 5 = cancelled

Explain Calculations

If metrics require specific calculations, be explicit:

"Active users" = users who have logged in within the last 30 days (check `last_login` column).
"Monthly revenue" = SUM(amount) from transactions WHERE status = 'completed' AND refunded = false.

Note Table Relationships

Help Cobi understand how to join tables correctly:

To get customer orders: JOIN customers ON orders.customer_id = customers.id
To get order items: JOIN order_items ON order_items.order_id = orders.id
Products are linked via order_items.product_id = products.id

Update Regularly

As your data model evolves, update your Custom Instructions to reflect new tables, columns, or business rules.

Learned Information

In addition to Custom Instructions (which you write), Cobi automatically builds Learned Information as you interact with the Data Assistant. This includes:

Table and column descriptions discovered through queries
Relationships between tables
Common query patterns

You can view and edit Learned Information in the Learned Information tab of your data connector settings.

Troubleshooting

Data Assistant Still Gets It Wrong

If Cobi isn’t interpreting your data correctly:

Check your Custom Instructions for clarity
Add more specific examples
Correct any Learned Information that may be inaccurate
Try rephrasing your question to include the terminology you defined

Instructions Not Taking Effect

After saving Custom Instructions:

Start a new conversation to ensure the context is loaded
Check that you’re using the correct data source in your query

Next Steps

Connect your database if you haven’t already
Start asking questions in the Data Assistant to see your instructions in action

Getting Started

Self-Hosted Deployment

Data Sources

Channels

API

Overview

Why Use Custom Instructions?

Define Terminology

Explain Relationships

Set Business Rules

Improve Accuracy

Adding Custom Instructions

What to Include

Business Context

Key Terminology

Revenue Sources

Query Guidance

Example: Complete Custom Instructions

Best Practices

Be Specific

Document Status Codes

Explain Calculations

Note Table Relationships

Update Regularly

Learned Information

Troubleshooting

Data Assistant Still Gets It Wrong

Instructions Not Taking Effect

Next Steps

​Overview

​Why Use Custom Instructions?

Define Terminology

Explain Relationships

Set Business Rules

Improve Accuracy

​Adding Custom Instructions

​What to Include

​Business Context

​Key Terminology

​Revenue Sources

​Query Guidance

​Example: Complete Custom Instructions

​Best Practices

​Be Specific

​Document Status Codes

​Explain Calculations

​Note Table Relationships

​Update Regularly

​Learned Information

​Troubleshooting

​Data Assistant Still Gets It Wrong

​Instructions Not Taking Effect

​Next Steps

Overview

Why Use Custom Instructions?

Adding Custom Instructions

What to Include

Business Context

Key Terminology

Revenue Sources

Query Guidance

Example: Complete Custom Instructions

Best Practices

Be Specific

Document Status Codes

Explain Calculations

Note Table Relationships

Update Regularly

Learned Information

Troubleshooting

Data Assistant Still Gets It Wrong

Instructions Not Taking Effect

Next Steps