Skip to main content

AI Copilot: DB Documentation

retinder.labana
Updated

Overview

The AI Copilot description feature in SqlDBM lets you generate text descriptions for columns, tables, and schemas directly from the DB Documentation page. Instead of writing descriptions manually, you trigger AI generation on individual fields or in bulk across an entire table or schema. The AI uses the structure of your data model (column names, data types, key flags, and existing descriptions) to produce contextually relevant output.

This feature is available to users who work in the DB Documentation view and have been granted permission by the Admin to use Copilot. It is designed to reduce the time spent documenting large or undocumented databases.

 

What You Can Accomplish

  • Generate a description for a single column or object description field
  • Generate descriptions for all empty fields in a table or schema in one action
  • Overwrite all existing descriptions in a table or schema with AI-generated output
  • Improve logical names for columns based on physical names, data types, and existing descriptions
  • Undo or redo any AI-generated change on a per-action basis
     

Feature Details

Where the Feature Appears

The AI Copilot description controls appear in two locations within SqlDBM:

  • DB Documentation page — the primary surface for this feature
  • Diagram (fields on objects) — the same icons and behaviors appear in the "Manage Fields from Diagram" panel in Model Governance

Individual Descriptions

You can generate a description for any single column or object description field. The AI icon only appears when you hover over a description field, it is not permanently visible.

Steps

  1. Open the DB Documentation page for your database.
  2. Hover over any description field for a column or object.
  3. Click the AI diamond icon that appears in the field.
  4. Wait for the spinner to complete. The field will be populated with the AI-generated description.

Overwrite behavior

Clicking the AI icon on an individual field always overwrites the existing content in that field. There is no prompt asking you to confirm before the overwrite occurs.

Bulk Descriptions

You can generate descriptions for all columns and objects under a table or schema in a single action. The AI icon for bulk actions is visible next to the object name — you do not need to hover.

Steps

  1. On the DB Documentation page, locate the table or schema you want to document.
  2. Click the AI icon to the right of the table or schema name.
  3. A context menu with a purple border appears. Select one of the following actions:
  • Add missing descriptions — generates descriptions only for fields that are currently empty. Existing content is not modified.
  • Add or improve descriptions — generates descriptions and overwrites all description fields, including those that already have content.
  • Improve logical names — rewrites logical names for columns based on physical names, data types, and existing descriptions.
  1. While the action is running, the AI icon shows a shimmer or spinner animation and the context menu displays "thinking…".
  2. When processing is complete, all affected fields are updated.

Schema-level scope

When you trigger a bulk action at the schema level, it applies recursively to all tables and columns within that schema, including nested objects.

Undo and Redo

All AI-generated changes support standard undo and redo behavior. The scope of the undo matches the scope of the action:

  • A single field generation undoes one field.
  • A bulk action undoes all changes made by that bulk action at once

Scope and Reach

AI actions only affect objects that are currently visible on the DB Documentation page. If an object is hidden due to a filter or collapsed view, it is not included in the operation.

The following object types are supported:

  • Tables and their columns
  • Schemas (named schemas and objects with no schema assigned)
  • Templates and template columns (treated as tables; no schema-level bulk action)

The following object types are not affected:

  • Functions
  • Procedures

 

How It Works

Context Passed to the AI

For every AI generation request (including single-column requests) SqlDBM passes table-level context to the AI. This context includes:

  • Table name
  • Table description
  • All column names in the table
  • Column data types
  • Null flag
  • Primary key (PK), alternate key (AK), and foreign key (FK) flags
  • Foreign key parent name
  • Existing column descriptions

This means that even when you generate a description for a single column, the AI has visibility into the full structure of the table to produce a more accurate result.
 

Add Missing vs. Add or Improve

The two bulk description options differ in how they handle existing content:

Action Behavior
Add missing descriptions Generates descriptions for empty fields only. Fields with existing content are not changed.
Add or improve descriptions Generates descriptions and overwrites all description fields, including those with existing content.
Improve logical names Rewrites logical names for columns based on physical names, data types, and existing descriptions. Overwrites existing logical names.

 

Response Times

SqlDBM targets the following response times for AI generation. If a request exceeds the maximum tolerable time, an error message is displayed.

Operation type Target response Maximum tolerable time
Individual description < 1.5 seconds 3 seconds
Bulk operation 2–4 seconds 6 seconds

 

Error Messages

If an error occurs, SqlDBM displays a banner message. The table below shows each error type and the message text.

Error type Message displayed
Incomplete response Incomplete or malformed response. Please try the prompt again with more context.
Server error The Copilot failed to respond. Please try again in a few minutes.
Object limit exceeded Object limit exceeded. Please try again with fewer objects.
Generic error Copilot could not complete the request. Please try again.


 

Limitations

Feature Access

  • This feature is controlled by the "AI Descriptions" flag. Your workspace must have this flag enabled for the AI Copilot description controls to appear.
  • Contact your account administrator or SqlDBM support to confirm whether this feature is enabled for your workspace.

Scope Restrictions

  • AI actions only process objects that are visible on the current DB Documentation page. Objects hidden by filters or collapsed views are not included.
  • Functions and procedures are not supported and will not be processed.
  • Templates do not have a schema-level bulk action. You can run bulk actions at the template level, but not across all templates at once.

Content Behavior

  • Individual field generation always overwrites the existing content in that field without confirmation.
  • The "Add or improve descriptions" bulk action overwrites all description fields, including those with existing content.
  • The "Improve logical names" action overwrites existing logical names.
  • AI-generated content is based on the structural context of your model. The quality of output depends on the completeness of your model metadata, including column names, data types, and existing descriptions.
     

Out of Scope

The following capabilities are not part of this feature:

  • Adding or modifying flags (PK, AK, FK) via AI
  • Filling Model Governance (MG) or dbt fields via AI
  • Reviewing or improving all metadata at once

Object Limits

  • If a bulk operation includes more objects than the system can process in a single request, you will see the message: "Object limit exceeded. Please try again with fewer objects." In this case, run the action on a smaller set of objects, such as individual tables rather than the full schema.

Related articles