Knowledge Best Practices

Use Descriptive Names

Chonk understands your schema better when names are clear and consistent.

Add Column Comments

Database column comments are indexed and significantly improve AI understanding.

-- Snowflake
ALTER TABLE orders 
  ALTER COLUMN order_status 
  COMMENT 'Current fulfillment status: pending, shipped, delivered, cancelled';

-- BigQuery
ALTER TABLE orders
  ALTER COLUMN order_status
  SET OPTIONS (description = 'Current fulfillment status: pending, shipped, delivered, cancelled');

Prioritize Authoritative Sources

• Official dbt docs — Always include for best practices
• Your dbt project — Existing models and docs
• Data dictionaries — Business definitions and glossaries
• Team runbooks — Internal standards and patterns

Remove Stale Content

Outdated documentation confuses the AI. Regularly audit your sources.

Structure for Discoverability

• Use clear headings and sections
• Include examples with code snippets
• Define terms before using them
• Link related concepts together

Start Fresh for New Topics

Long conversation threads can dilute context. Start a new chat when:

• Switching to a different data domain
• Beginning a new modeling task
• The AI seems confused about your request

Provide Context Upfront

Iterate Incrementally

Build complex models step by step:

• Generate the staging model first
• Review and refine the output
• Ask for the intermediate transformations
• Finally, request the final mart model

Scan Strategically

You don't need to scan everything. Focus on:

• Source schemas — Raw data from your applications
• Staging schemas — If you have existing dbt models
• Reference tables — Lookup tables and dimensions

Exclude Noise

Filter out tables that add confusion:

# CLI scan with exclusions
datachonk scan \
  --schema raw_shopify \
  --schema raw_stripe \
  --exclude "tmp_*" \
  --exclude "*_backup" \
  --exclude "test_*"

Share Generated Models

When a team member generates a useful model:

• Review and approve the generated code
• Push to your dbt project via GitHub
• The model becomes part of the knowledge base
• Future generations can reference this pattern

Document Decisions

Add context to your generated models:

{{
  config(
    materialized='incremental',
    unique_key='order_id'
  )
}}

/*
  Business Context:
  - Orders are considered "complete" when status = 'delivered'
  - Revenue is calculated excluding tax and shipping
  - Customer attribution uses first-touch model
  
  Generated by DataChonk, reviewed by @data-team
*/

SELECT ...

Limit Knowledge Scope

More isn't always better. A focused knowledge base outperforms a bloated one:

• Keep sources under 10 per project
• Scan only relevant schemas
• Remove unused integrations

Use Project Templates

Pre-configure knowledge settings for common use cases: