Skip to main content

Data Dictionary

The Data Dictionary is your reference for everything Teela knows about your database structure. It shows every table, column, data type, relationship, and description across your connected data sources: and it's also where you can enhance that information to help Teela answer questions more accurately.

How the Data Dictionary Is Generated​

The Data Dictionary is built automatically during schema extraction. When Teela analyzes your database, it catalogs:

  • Tables: Every table in your database (or every tab in your spreadsheet connections)
  • Columns: Each column within each table, including its name and data type
  • Relationships: Foreign key relationships between tables, and how they join together
  • Descriptions: Auto-generated summaries based on table names, column names, and detected patterns

You don't need to build the Data Dictionary manually: Teela creates it for you. Your job is to review it and enhance it with business context that Teela can't infer on its own.

What You'll See​

When you open the Data Dictionary in the Admin portal, each table entry shows:

  • Table name: The name as it appears in your database
  • Description: A summary of what the table contains (auto-generated, or your custom description)
  • Column list: Every column in the table, with:
    • Column name
    • Data type (e.g., VARCHAR, INT, DATETIME, DECIMAL)
    • Description: What the column represents
    • Relationships: If the column is a foreign key, which table and column it references
    • Semantic tags: Automatically detected categories (see below)

You can search, filter, and sort the Data Dictionary to quickly find what you're looking for.

Auto-Generated Descriptions​

Teela generates initial descriptions for every table and column based on naming patterns. For example:

  • A table named customer_orders gets a description like "Stores customer order records."
  • A column named created_at gets tagged as a date field with a description like "Timestamp when the record was created."

These auto-generated descriptions are a starting point. They're often useful as-is for straightforward naming conventions, but they really shine when you enhance them with your own business context.

Enhancing Descriptions​

Adding your own descriptions is one of the highest-impact things you can do to improve Teela's accuracy. Teela reads these descriptions every time it generates a query, so clear, specific descriptions lead to better results.

How to Add or Edit a Description​

  1. Find the table or column in the Data Dictionary.
  2. Click the Description field.
  3. Write your description in plain English. Be as specific as you can.
  4. Click Save.

What Makes a Good Description​

The best descriptions explain what the data means in your business, not just what it is technically. Compare:

OkayBetter
"Status of the order.""Order status: 'P' = pending, 'A' = approved, 'S' = shipped, 'C' = cancelled. Only 'A' and 'S' orders should be included in revenue calculations."
"Amount field.""Total order amount in USD cents. Divide by 100 to get dollar values. Includes tax but excludes shipping."
"Customer table.""Active and inactive customer records. Use is_active = 1 to filter for current customers. Records go back to 2018; older data is in the legacy_customers table."

The more business context you provide, the more accurately Teela can answer questions.

Column Semantic Detection​

During schema extraction, Teela automatically identifies semantic categories for your columns. This helps Teela understand not just the data type, but the meaning and role of each column.

Common semantic categories include:

  • Status columns: Fields containing status codes or state values (e.g., order_status, is_active)
  • Date fields: Timestamps, dates, and date-range columns (e.g., created_at, start_date, fiscal_quarter)
  • Financial columns: Currency amounts, prices, costs (e.g., total_amount, unit_price, discount)
  • Identifier columns: Primary keys, foreign keys, and lookup codes (e.g., customer_id, sku)
  • Name and label columns: Human-readable names and descriptions (e.g., product_name, category_label)

Semantic tags appear as badges next to column names in the Data Dictionary. Teela uses these tags to make smarter decisions about which columns to include in queries and how to format results.

Using the Schema Diagram Alongside the Data Dictionary​

The Data Dictionary and the Schema Diagram are complementary tools:

  • The Data Dictionary is best for detailed, column-level work: reviewing descriptions, checking data types, and understanding individual tables.
  • The Schema Diagram is best for big-picture work: seeing how tables relate to each other, including/excluding tables, and getting an overall sense of your data model.

Many admins find it helpful to use the Schema Diagram to explore relationships and then switch to the Data Dictionary to add detailed descriptions. You can click on any table in the Schema Diagram to jump directly to its Data Dictionary entry.

How the Data Dictionary Helps Teela​

When a user asks a question, Teela uses the Data Dictionary to:

  1. Find relevant tables: Descriptions help Teela determine which tables contain the data the user is asking about.
  2. Select the right columns: Column descriptions and semantic tags guide Teela to the correct fields.
  3. Apply business rules: Documentation about status codes, date ranges, and calculation methods helps Teela generate accurate queries.
  4. Join tables correctly: Relationship information tells Teela how to connect data across multiple tables.

A well-maintained Data Dictionary is the single biggest factor in Teela's query accuracy.

Keeping It Up to Date​

Your database evolves over time: new tables are added, columns are renamed, relationships change. When this happens, the Data Dictionary can fall out of sync.

When to Re-Extract​

Re-run schema extraction when:

  • New tables or columns are added to your database
  • Tables or columns are renamed or removed
  • Relationships change (new foreign keys, altered join paths)
  • A new connection is added to your organization

What Happens During Re-Extraction​

When you re-extract, Teela:

  1. Scans the database for structural changes.
  2. Adds new tables and columns to the Data Dictionary.
  3. Flags removed tables and columns (and any associated aliases or training data).
  4. Preserves all custom descriptions and documentation you've added: your work is never overwritten.

To re-extract, navigate to your connection in the Admin portal and click Extract Schema, just like the first time.

  • Training the AI: Full training toolkit including documentation, SQL examples, and the Schema Diagram
  • Aliases: Map business terms to the tables and columns in your Data Dictionary
  • Setup: Initial setup including schema extraction