Skip to main content

​
Custom Instructions

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

1

Open Data Connectors

Navigate to Developer > Data Connectors in the sidebar.
2

Select Your Connection

Click on the data source you want to configure.
3

Go to Custom Instructions Tab

In the connection modal, click the Custom Instructions tab.
4

Add Your Context

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

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:
1. Court bookings (bookings table)
2. Private lessons (instructor_bookings table)
3. Program enrollments (program_enrollments table)
4. 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:
  1. Check your Custom Instructions for clarity
  2. Add more specific examples
  3. Correct any Learned Information that may be inaccurate
  4. 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