Fetching Schema

When setting up a Database Agent, Discover fetches your database schema (DDL) and stores it in a Knowledge Base. This allows the agent to understand your table and column structure and generate accurate SQL queries.

Supported Data Sources

Discover can fetch schemas from the following sources:

• PostgreSQL
• MySQL
• BigQuery
• Snowflake
• Microsoft SQL Server
• SQLite

---

Fetching a Schema for the First Time

Schema fetching happens during Database Agent creation or when adding a new data source to a Knowledge Base.

1. Navigate to Agent in the left sidebar and click New Agent.

2. Select Database Agent and click Next.

3. In the Connect your database step, fill in the connection details for your data source:

   • Database Type: Select from PostgreSQL, MySQL, BigQuery, Snowflake, SQL Server, or SQLite.
   • Host and Port (for PostgreSQL, MySQL, SQL Server)
   • Database Name / Dataset ID (for BigQuery)
   • Username and Password
   • BigQuery also requires: Project ID, Data Project ID, and Dataset ID
   • Snowflake also requires: Account, Role, and Warehouse

4. Click Test Connection to verify your credentials.

5. Click Fetch DDL to retrieve the schema from your database.

Schema Manager

After fetching, the Schema Manager opens and displays all available tables and columns.

1. Select tables: Enable the tables you want the agent to have access to. Disable any that are irrelevant to avoid noise in query generation.

2. Enrich schema: Click Enrich Schema to have Discover automatically generate descriptions for your tables and columns using AI.

3. Review and edit descriptions: After enrichment, review the generated descriptions. You can edit any description directly — clear, accurate descriptions directly impact SQL quality.

4. Click Save to store the schema in the Knowledge Base.

Note

All enabled tables must have descriptions before saving. Column descriptions are optional but recommended for better query accuracy.

Optional: Analyze Query History (BigQuery)

For BigQuery, you can optionally enable Analyze usage from query history to help Discover identify your most commonly queried tables:

• BigQuery Logs Project ID: The GCP project containing your audit logs
• BigQuery Logs Dataset ID: The dataset with the query logs
• BigQuery Logs Table ID: The table name (e.g., cloudaudit_googleapis_com_activity)
• Days Back: Number of days of history to analyze (default: 90)

This is useful for large datasets where you want to prioritise the most relevant tables.

---

Updating the Schema (Re-fetching)

When your database schema changes — for example, new tables are added, columns are modified, or descriptions need updating — you can re-fetch the schema to bring your Knowledge Base up to date.

1. Open the Knowledge Base linked to your Database Agent.

2. Click Fetch DDL (or the schema management option for that KB).

3. Re-enter or confirm your database connection details.

4. Click Test Connection, then Fetch DDL.

5. The Schema Manager opens in update mode.

What Happens During an Update

Discover intelligently merges the new schema with your existing configuration:

• New tables and columns are added automatically.
• Existing descriptions you have written or edited are preserved — they are not overwritten.
• Table and column enabled/disabled states are retained so your previous selections remain intact.
• Only new or modified tables and columns are re-enriched with AI-generated descriptions.

This means you can safely re-fetch the schema after database changes without losing your previous work.

Caution

If a table or column is removed from the database, it will no longer appear in the Schema Manager after re-fetching. If it was previously enabled, review your agent’s configuration to ensure no dependent queries break.

---

Tips for Better Schema Quality

• Write descriptions in plain language that reflects how your team refers to each table or column.
• Include units or formats where relevant (e.g., “price in USD”, “timestamp in UTC”).
• For tables with overlapping names, use descriptions to clarify their distinct purposes.
• Add Domain Knowledge in the agent setup to capture business logic that cannot be expressed in schema descriptions alone.