Skip to main content

Training Best Practices

This is a playbook for getting the most out of Teela's training system. Whether you're setting up a new connection or fine-tuning an existing one, these practices will help you build training data that makes Teela accurate and reliable.

For details on the specific training tools, see Training the AI. For ongoing monitoring, see Monitoring and Improving.

Start with the Vocabulary Wizard​

The Vocabulary Wizard is the single best place to begin. It asks you targeted questions about your business and automatically creates aliases and documentation from your answers. Even if you don't finish every section, the wizard gives Teela a solid baseline to work from.

You can re-run the wizard at any time from Training > Vocabulary Wizard, which is useful after adding new data sources or when your business terminology evolves.

Focus on Business Rules and Status Codes First​

These are critical priority. If your database uses coded values (status = 'A', type = 3, is_active = 1), document every single one. Teela has no way to guess what 'A' or '3' means without your help. This is the documentation that prevents the most wrong answers.

Here's an example of what this looks like in practice:

"The status column uses 'A' for active, 'I' for inactive, 'S' for suspended, and 'C' for closed. Only 'A' records should be included in active customer counts."

This single piece of documentation can fix dozens of queries at once.

Document Column Meanings for Ambiguous Names​

Columns like amt, val, code, flag, type, and desc are common in databases but meaningless without context. If a column name doesn't clearly describe what it holds, add documentation. On the other hand, a column named email_address is self-explanatory and doesn't need documentation.

Ask yourself: If someone who knows nothing about your business saw this column name, would they know what it means? If not, document it.

Add SQL Examples for Problem Questions​

If you notice Teela consistently struggling with a particular type of question, that's a signal to add a SQL example. One well-crafted example can fix an entire category of similar questions because Teela learns the pattern, not just the specific query.

Good candidates for SQL examples:

  • Questions involving complex joins across multiple tables
  • Calculations with business-specific logic (net revenue, customer lifetime value)
  • Queries that need specific filters your team always expects (exclude test accounts, only active records)
  • Date-based queries with non-standard fiscal years or custom time periods

If you can explain the issue in a sentence or two, use documentation instead. SQL examples are most valuable when the query pattern itself is what Teela needs to learn.

Review the Knowledge Gap Dashboard Regularly​

Make it part of your weekly routine. Even 10 minutes of reviewing gaps and creating aliases can meaningfully improve accuracy. Pay special attention to gaps with high occurrence counts because those represent the terms your team is using the most.

The Knowledge Gap Dashboard shows you exactly which terms users are searching for that Teela can't resolve. Each gap is an opportunity to create an alias or add documentation.

Use the Validation Chat to Test After Changes​

After adding documentation, aliases, or SQL examples, open the Training Validation chat and test with the kinds of questions your team actually asks. This catches issues before your users encounter them.

A good testing session looks like:

  1. Ask 5-10 questions your team commonly asks.
  2. Check that the generated SQL is hitting the right tables and columns.
  3. Verify that filters and business rules are being applied correctly.
  4. Try some edge cases (date ranges, unusual status codes, questions that span multiple tables).

Keep Documentation Up to Date​

When your company changes how it defines "active customer" or updates its status codes, update the documentation immediately. Stale documentation will cause Teela to confidently produce wrong answers, which is worse than producing no answer at all.

Good times to review your training data:

  • After a database schema change (new tables, renamed columns)
  • After a business process change (new status codes, new product categories)
  • After re-running schema extraction
  • When you notice a pattern of wrong answers in the Learning Review Queue

Don't Over-Document​

Your time is valuable. A column named customer_email doesn't need documentation saying "this is the customer's email address." Focus your energy on the things Teela can't figure out from the schema alone: business rules, coded values, implicit filters, and non-obvious relationships.

As a general rule:

  • Document: Status codes, business definitions, calculated metrics, exclusion rules, date conventions, abbreviations
  • Skip: Self-explanatory column names, obvious table descriptions, standard data types

Check the Feedback-Flagged Tab Weekly​

The Feedback-Flagged tab in the Learning Review Queue contains thumbs-down feedback from your users. Each item includes an AI diagnosis of what went wrong and a suggested fix. These are your best leads for high-impact improvements because they represent real questions where Teela fell short.

The "Create Training From This" button makes it easy to turn a diagnosis into a new piece of training data with the relevant fields pre-filled.

Let Auto-Approve Work for You​

Teela's auto-approve system handles the easy wins automatically. When a query gets 2 or more positive signals (thumbs-up, DataClip saves) with no negative signals, it's added to training without you having to do anything. Check the Auto-Approved tab periodically to make sure the quality is good, but don't feel like you need to manually approve everything.

Use Aliases Generously​

Aliases are lightweight and powerful. If your team says "revenue" but the column is called total_sales_amount, create an alias. If they say "clients" but the table is customers, create an alias. The more aliases you have for common terms, the less often Teela will need to guess or ask clarifying questions.

Don't forget about:

  • Industry jargon your team uses
  • Abbreviations (MRR, ARR, COGS, AOV)
  • Informal names for tables or reports
  • Regional or departmental terminology
  • Training the AI: Schema extraction, documentation, SQL examples, vocabulary wizard, and import/export
  • Monitoring and Improving: Learning review queue, knowledge gap dashboard, validation chat, and the feedback loop
  • Aliases: Map business terms to database columns
  • Data Dictionary: Review and enhance table and column descriptions