Skip to main content

Training the AI

Teela's accuracy depends directly on how well it understands your data. Training is the process of teaching Teela about your database structure, business rules, and terminology. Better training means better answers for your team.

This page covers the tools for building training data. For ongoing monitoring and improvement, see Monitoring and Improving. For a step-by-step playbook, see Training Best Practices.

Schema Extraction​

Schema extraction is the foundation of Teela's understanding. When you run extraction, Teela analyzes your database and creates three things for each table it finds:

  • DDL records: The raw table structure (columns, data types, constraints, relationships) stored in Teela's training index.
  • Auto-generated documentation: Teela writes initial plain-English descriptions for each table and column based on naming conventions and data patterns. These are starting points you should review and improve.
  • Sample SQL queries: Teela generates basic example queries for each table (simple selects, common aggregations, joins to related tables) so it has something to work with right away.

What Extraction Learns​

  • Tables and columns: What data exists and how it's structured
  • Data types: Whether a column holds text, numbers, dates, etc.
  • Relationships: How tables connect to each other (foreign keys, join paths)
  • Data patterns: Common values, status codes, and field distributions

Running Extraction​

To run extraction, navigate to your connection in the Admin portal and click Extract Schema. For small databases, this completes in a few seconds. For large databases with hundreds of tables, extraction runs in the background and you'll receive an email when it's complete.

tip

You should re-run schema extraction any time your database schema changes, whether that's new tables, renamed columns, or altered relationships. When you re-extract, Teela merges the new schema with your existing training data, so your documentation and aliases are preserved. See Keeping the Data Dictionary Up to Date for guidance.

The Interactive Schema Diagram​

After extraction, the Schema Diagram gives you a visual map of your database. It's one of the most useful tools in the Admin portal for understanding and managing what Teela knows about your data.

Table Colors​

Each table is color-coded:

  • Green: Included in training. Teela will use this table when answering questions.
  • Red: Excluded from training. Teela will ignore this table entirely.
  • Gray: No DDL (Data Definition Language) available. The table exists but Teela couldn't extract its structure.
  • Drag tables to rearrange the layout and organize related tables near each other.
  • Click a table to see its columns, data types, relationships, and any documentation you've added.
  • Zoom from 25% to 250% to get the level of detail you need.
  • Pan by clicking and dragging on the background.
  • Search to quickly find a specific table by name.

Multi-Select for Bulk Actions​

Need to exclude a whole group of staging tables? Hold Shift and click multiple tables to select them, then use the toolbar to include or exclude them all at once.

Including and Excluding Tables​

Not every table in your database is relevant for business questions. Staging tables, system logs, temporary tables, and migration artifacts can confuse Teela and lead to incorrect queries.

To exclude a table:

  1. Open the Schema Diagram or navigate to the table in the Data Dictionary.
  2. Click the table and select Exclude.

When you exclude a table, the change cascades: any training data, aliases, or documentation tied to that table will be flagged or hidden. This keeps everything consistent.

You can re-include a table at any time by selecting it and clicking Include.

Adding Documentation​

Documentation is the single most impactful way to improve Teela's accuracy. When you add plain-English notes to a table or column, you're giving Teela the context it needs to write correct queries. Think of it this way: Teela can see your schema, but it can't see your business rules. Documentation fills that gap.

How to Add Documentation​

  1. Navigate to the table or column in the Schema Diagram or Data Dictionary.
  2. Click the Documentation field.
  3. Write your notes in plain English. Be specific and include examples where possible.
  4. Click Save.

Teela uses this documentation at query time, so the more context you provide, the better the results.

Documentation Priority Levels​

Not all documentation carries equal weight. Teela prioritizes documentation by type when generating queries:

  • Critical: Status code mappings, enumeration values, and core business rules. These are the pieces of context that, if missing, almost guarantee a wrong answer. Examples: what each status code means, which flag indicates a soft-deleted record, how your system defines "active."
  • High: Common query patterns and frequently asked questions. If your team asks "show me revenue by quarter" every week, documentation explaining which column represents revenue and how quarters are defined is high priority.
  • Medium: Relationships between tables that aren't obvious from the schema, historical context about data migrations, and edge cases.
  • Low: General descriptions of what a table contains or what a column name means when the name is already self-explanatory.

Focus your time on critical and high priority documentation first. That's where you'll see the biggest accuracy gains.

Examples of Good Documentation​

Good documentation tells Teela something it can't figure out on its own:

  • "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 table only contains records from 2020 onward. Historical data is in the legacy_orders table."
  • "The amount column stores values in cents, not dollars. Divide by 100 for display."
  • "Rows where is_deleted = 1 should be excluded from all reports."
  • "'Revenue' means the sum of line_total from the order_items table, excluding rows where item_type = 'tax' or item_type = 'shipping'."
  • "A 'churned' customer is one whose last order was more than 12 months ago."

Examples of Bad Documentation​

Bad documentation is either obvious, vague, or too specific to a one-time scenario:

  • "This is the orders table." (Teela already knows the table name.)
  • "Contains customer data." (Too vague to be useful.)
  • "email stores the email address." (The column name already says this.)
  • "Run this query to get John's report for the Q3 board meeting." (Too specific to one person and one moment in time.)
  • "This column is important." (Important how? For what?)

AI Validate & Enhance​

After writing documentation, you can click the AI Validate & Enhance button to have Teela review and improve what you've written. This feature does three things:

  1. Maps terms to schema: Teela checks that every business term you mention actually corresponds to a real table or column in your database. If you reference "the revenue column" but no such column exists, Teela will flag it.
  2. Removes overly specific details: If your documentation references a specific date, a specific person's name, or a one-time scenario, Teela suggests a more generalized version that will be useful across many queries.
  3. Generalizes patterns: Teela rewrites documentation to be more broadly applicable while preserving the core business rule.

After enhancement, Teela shows you:

  • Coaching notes: Suggestions for how to make the documentation even more effective, like "Consider adding the full list of status codes" or "This would be more useful as a SQL example."
  • Unmapped term warnings: Any business terms in your documentation that Teela couldn't match to your schema. These are terms that might need aliases before they'll be useful.

You can accept the enhanced version, keep your original, or edit the enhanced version before saving.

tip

AI Validate & Enhance is especially helpful when you're getting started and aren't sure what good documentation looks like. Write your best attempt, click the button, and learn from the suggestions.

Best Practices for Writing Documentation​

  • Lead with business rules. The most valuable documentation explains how your business interprets the data, not what the data structurally is.
  • Include all possible values for status and type columns. Incomplete lists lead to incomplete queries.
  • Mention exclusion rules. If certain rows should always be filtered out (deleted records, test accounts, internal data), say so.
  • Reference related tables. If two tables are commonly joined together, mention that in the documentation for both tables.
  • Use the terminology your team uses. Write documentation in the same language your users will use when asking questions.
  • Keep it up to date. When business rules change, update the documentation. Stale documentation is worse than no documentation because Teela will confidently give wrong answers.

Adding SQL Examples​

SQL examples teach Teela how to answer specific types of questions. While documentation gives Teela context, SQL examples give it patterns. If your team frequently asks a particular question and Teela doesn't get it right, adding a SQL example is often the fastest fix.

When to Use SQL Examples vs. Documentation​

Use documentation when Teela needs to understand a concept, a business rule, or what a column means. Use SQL examples when Teela needs to learn a specific query pattern, especially one that involves complex joins, subqueries, window functions, or business logic that's hard to describe in words.

A good rule of thumb: if you can explain it in a sentence or two, use documentation. If you need to show the actual SQL to get it right, use a SQL example.

How Teela Uses SQL Examples​

Teela doesn't just memorize your examples and replay them. It treats them as patterns. When a user asks a question similar to one of your examples, Teela adapts the pattern to fit the specific question. For instance, if you provide an example for "show me total revenue by quarter," Teela can use that pattern to answer "show me total revenue by month" or "show me total revenue by region" without needing separate examples for each variation.

This means your examples should focus on the tricky parts (the joins, the filters, the business logic) rather than the trivial parts (which columns to select, basic GROUP BY clauses).

How to Add a SQL Example​

  1. Navigate to Training > SQL Examples in the Admin portal.
  2. Click Add Example.
  3. Enter a sample question (in plain English) and the correct SQL query.
  4. Optionally add notes explaining why the query is written that way.
  5. Click Save.

Tips for Effective SQL Examples​

  • Focus on question types that come up often or that Teela gets wrong. Don't add examples for questions Teela already handles well.
  • Use representative but simple queries. Teela learns patterns, not just exact matches. A clean, readable example teaches better than a complex one.
  • Include examples that demonstrate business-specific logic. How to calculate "active customers," how to compute "net revenue," how to handle fiscal year boundaries.
  • Add notes explaining the "why." If your query uses a specific join order or filter for a reason, explain it in the notes. This helps other admins understand the example and helps Teela weight the important parts.
caution

Avoid adding SQL examples that are too narrow or too complex. An example that only works for one very specific question won't help Teela generalize. An example with 15 joins and nested subqueries may confuse more than it helps.

Vocabulary Wizard​

The Vocabulary Wizard is a guided experience that runs after schema extraction. It walks you through AI-generated questions organized by business pillars like People, Customers, Products, Finances, and Operations.

For each question, you provide answers in plain English, and Teela automatically creates aliases and documentation based on your responses. At the end, you get a Test Drive to try out some queries and see how Teela performs.

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

For more on the initial Vocabulary Wizard experience, see Setup.

Alias Management​

Aliases map business terms to database tables and columns. When your team says "revenue" but your database calls it total_sales_amount, an alias makes that connection. For full details, see the dedicated Aliases page. Here's a quick summary of the key features:

Table and Column Aliases​

You can create aliases for both tables and columns:

  • Table aliases: Map a business term to an entire table. Example: "customers" maps to the clients table.
  • Column aliases: Map a business term to a specific column. Example: "revenue" maps to orders.total_sales_amount.

Usage Tracking​

Every alias shows how often it's been used and when it was last triggered. This helps you understand which aliases are pulling their weight and which might be outdated.

Orphan Detection​

When your schema changes (tables renamed, columns dropped), some aliases may point to targets that no longer exist. Teela flags these as orphaned aliases with a warning indicator. After any schema re-extraction, check for orphans and either remap or delete them. The Alias Manager provides a Bulk Cleanup tool for handling many orphans at once.

AI-Generated Suggestions​

During schema extraction and the Vocabulary Wizard, Teela automatically generates alias suggestions based on your column names, table names, and the documentation you've provided. Review these suggestions to make sure they match how your team actually talks about data.

For the complete guide to creating, editing, and managing aliases, see Aliases.

Importing and Exporting Training Data​

You can export your entire training dataset as a CSV file for backup or migration purposes.

  • Export: Download all documentation, SQL examples, and DDL records as a CSV.
  • Import: Upload a CSV to bulk-add training data. This is useful when migrating between environments, restoring from a backup, or seeding a new connection with training from an existing one.

Navigate to Training > Import/Export to access these tools.

CSV Format​

The import CSV must have three columns:

ColumnDescription
TypeMust be one of: sql, documentation, or ddl
ContentThe actual training content. For sql type, this is the SQL query. For documentation, this is the plain-English text. For ddl, this is the DDL statement.
QuestionThe natural-language question associated with this training item. Required for sql type. Optional for documentation and ddl.
caution

Importing will add to your existing training data, not replace it. If you need to do a full reset, export your current data first as a backup, then contact support.

  • Monitoring and Improving: Learning review queue, knowledge gap dashboard, validation chat, and the feedback loop
  • Training Best Practices: A step-by-step playbook for getting the most out of training
  • Aliases: Map business terms to database columns
  • Data Dictionary: Review and enhance table and column descriptions
  • Setup: Initial setup including schema extraction and the Vocabulary Wizard