sql-glider 0.1.2__tar.gz → 0.1.4__tar.gz

{sql_glider-0.1.2 → sql_glider-0.1.4}/.gitignore

@@ -211,4 +211,5 @@ src/sqlglider/_version.py
 
 # Random Local Stuff
 junk.md
-megagraph.json
+megagraph.json
+/sqlglider.toml 

{sql_glider-0.1.2 → sql_glider-0.1.4}/ARCHITECTURE.md

@@ -12,6 +12,11 @@ sql-glider/
 │   └── sqlglider/
 │       ├── __init__.py              # Package initialization
 │       ├── cli.py                   # Typer CLI entry point
+│       ├── dissection/
+│       │   ├── __init__.py          # Dissection module exports
+│       │   ├── models.py            # ComponentType, SQLComponent, QueryDissectionResult
+│       │   ├── analyzer.py          # DissectionAnalyzer for query decomposition
+│       │   └── formatters.py        # Output formatters (text, JSON, CSV)
 │       ├── graph/
 │       │   ├── __init__.py          # Graph module exports
 │       │   ├── models.py            # Pydantic models for graph data
@@ -23,6 +28,17 @@ sql-glider/
 │       │   ├── __init__.py          # Lineage module exports
 │       │   ├── analyzer.py          # Core lineage analysis logic
 │       │   └── formatters.py        # Output formatters (text, JSON, CSV)
+│       ├── catalog/
+│       │   ├── __init__.py          # Catalog module exports
+│       │   ├── base.py              # Abstract Catalog class + CatalogError
+│       │   ├── registry.py          # Plugin discovery via entry points
+│       │   └── databricks.py        # Databricks Unity Catalog implementation
+│       ├── templating/
+│       │   ├── __init__.py          # Templating module exports
+│       │   ├── base.py              # Abstract Templater class + TemplaterError
+│       │   ├── registry.py          # Plugin discovery for templaters
+│       │   ├── jinja.py             # Jinja2 templater implementation
+│       │   └── variables.py         # Variable loading from multiple sources
 │       └── utils/
 │           ├── __init__.py          # Utils module exports
 │           ├── config.py            # Configuration file loading
@@ -32,6 +48,11 @@ sql-glider/
 │   ├── sqlglider/
 │   │   ├── __init__.py
 │   │   ├── test_cli.py              # CLI integration tests
+│   │   ├── dissection/
+│   │   │   ├── __init__.py
+│   │   │   ├── test_models.py       # Dissection model tests
+│   │   │   ├── test_analyzer.py     # DissectionAnalyzer tests
+│   │   │   └── test_formatters.py   # Dissection formatter tests
 │   │   ├── graph/
 │   │   │   ├── __init__.py
 │   │   │   ├── test_models.py       # Graph model tests
@@ -92,11 +113,11 @@ sql-glider/
   - Example: `sqlglider lineage query.sql --source-column orders.customer_id`
   - Note: `--column` and `--source-column` are mutually exclusive
 
-**Tables Command:** `sqlglider tables <sql_file>`
-- Lists all tables involved in SQL files with usage and type information
+**Tables Command Group:** `sqlglider tables <subcommand>`
+- `tables overview <sql_file>`: Lists all tables involved in SQL files with usage and type information
 - Outputs include: table name (fully qualified), usage (INPUT/OUTPUT/BOTH), object type (TABLE/VIEW/CTE/UNKNOWN)
 - Supports all standard options: `--dialect`, `--output-format`, `--output-file`, `--templater`, `--var`, `--vars-file`
-- Example: `sqlglider tables query.sql --output-format json`
+- Example: `sqlglider tables overview query.sql --output-format json`
 
 **Error Handling:**
 - File not found errors
@@ -428,7 +449,123 @@ sqlglider graph query graph.json --upstream orders.customer_id
 sqlglider graph query graph.json --downstream customers.id -f json
 ```
 
-### 5. File Utilities (`utils/file_utils.py`)
+### 5. Dissection Module (`dissection/`)
+
+**Purpose:** Decompose SQL queries into constituent parts for unit testing and analysis
+
+The dissection module enables extracting components from SQL queries (CTEs, subqueries, UNION branches, etc.) so they can be tested individually or analyzed for structure.
+
+#### Data Models (`dissection/models.py`)
+
+```python
+class ComponentType(str, Enum):
+    """Type of SQL component extracted from a query."""
+    CTE = "CTE"                     # Common Table Expression
+    MAIN_QUERY = "MAIN_QUERY"       # Primary SELECT statement
+    SUBQUERY = "SUBQUERY"           # Nested SELECT in FROM clause
+    SCALAR_SUBQUERY = "SCALAR_SUBQUERY"  # Single-value subquery
+    TARGET_TABLE = "TARGET_TABLE"   # Output table for DML/DDL
+    SOURCE_QUERY = "SOURCE_QUERY"   # SELECT within DML/DDL
+    UNION_BRANCH = "UNION_BRANCH"   # Individual SELECT in UNION
+
+class SQLComponent(BaseModel):
+    """Represents an extracted SQL component."""
+    component_type: ComponentType
+    component_index: int           # Sequential order within query
+    name: Optional[str] = None     # CTE name, alias, or target table
+    sql: str                       # Extracted SQL for this component
+    parent_index: Optional[int] = None  # Index of parent component
+    depth: int = 0                 # Nesting level (0 = top-level)
+    is_executable: bool = True     # Can run standalone?
+    dependencies: List[str] = []   # CTE names this depends on
+    location: str = ""             # Human-readable location context
+
+class QueryMetadata(BaseModel):
+    """Metadata about a dissected query."""
+    query_index: int               # 0-based index in multi-query file
+    query_preview: str             # First 100 chars of query
+    statement_type: str            # SELECT, INSERT, CREATE, etc.
+    total_components: int          # Number of components extracted
+
+class QueryDissectionResult(BaseModel):
+    """Complete dissection result for a single query."""
+    metadata: QueryMetadata
+    components: List[SQLComponent]
+    original_sql: str              # Full original SQL for reference
+
+    def get_component_by_name(self, name: str) -> Optional[SQLComponent]
+    def get_components_by_type(self, component_type: ComponentType) -> List[SQLComponent]
+    def get_executable_components(self) -> List[SQLComponent]
+```
+
+#### Dissection Analyzer (`dissection/analyzer.py`)
+
+```python
+class DissectionAnalyzer:
+    def __init__(self, sql: str, dialect: str = "spark")
+    def dissect_queries(self) -> List[QueryDissectionResult]
+```
+
+**Extraction Order:**
+1. CTEs (by declaration order)
+2. TARGET_TABLE (for INSERT/CREATE/MERGE)
+3. SOURCE_QUERY (for DML/DDL statements)
+4. MAIN_QUERY (with full SQL including WITH clause)
+5. UNION_BRANCHES (if MAIN_QUERY is a UNION)
+6. SUBQUERIES (depth-first from FROM clauses)
+7. SCALAR_SUBQUERIES (from SELECT list, WHERE, HAVING)
+
+**Key Features:**
+- Uses SQLGlot AST traversal for accurate extraction
+- Tracks CTE dependencies by finding table references matching CTE names
+- UNION flattening extracts all branches from nested UNION expressions
+- Parent-child relationships via `parent_index` and `depth`
+- `location` field provides human-readable context (e.g., "SELECT list in CTE 'customer_segments'")
+
+#### Formatters (`dissection/formatters.py`)
+
+```python
+class DissectionTextFormatter:
+    @staticmethod
+    def format(results: List[QueryDissectionResult], console: Console) -> None
+
+class DissectionJsonFormatter:
+    @staticmethod
+    def format(results: List[QueryDissectionResult]) -> str
+
+class DissectionCsvFormatter:
+    @staticmethod
+    def format(results: List[QueryDissectionResult]) -> str
+```
+
+**Output Formats:**
+- **Text:** Rich table with columns for Index, Type, Name, Depth, Executable, Location, SQL Preview
+- **JSON:** Full structured data with all component details
+- **CSV:** Flattened format with semicolon-separated dependencies
+
+#### CLI Command
+
+```bash
+# Dissect a SQL file
+sqlglider dissect query.sql
+
+# JSON output
+sqlglider dissect query.sql --output-format json
+
+# CSV output
+sqlglider dissect query.sql --output-format csv
+
+# Export to file
+sqlglider dissect query.sql -f json -o dissected.json
+
+# From stdin
+echo "WITH cte AS (SELECT id FROM users) SELECT * FROM cte" | sqlglider dissect
+
+# With templating
+sqlglider dissect query.sql --templater jinja --var schema=analytics
+```
+
+### 6. File Utilities (`utils/file_utils.py`)
 
 **Purpose:** File I/O operations with proper error handling
 
@@ -442,7 +579,7 @@ def read_sql_file(file_path: Path) -> str
 - PermissionError: Cannot read file
 - UnicodeDecodeError: File not UTF-8 encoded
 
-### 5. Configuration System (`utils/config.py`)
+### 7. Configuration System (`utils/config.py`)
 
 **Purpose:** Load and manage configuration from `sqlglider.toml`
 
@@ -453,6 +590,11 @@ class ConfigSettings(BaseModel):
     dialect: Optional[str] = None
     level: Optional[str] = None
     output_format: Optional[str] = None
+    templater: Optional[str] = None
+    templating: Optional[TemplatingConfig] = None
+    catalog_type: Optional[str] = None
+    ddl_folder: Optional[str] = None
+    catalog: Optional[CatalogConfig] = None
 ```
 
 **Key Functions:**
@@ -480,6 +622,11 @@ def load_config(config_path: Optional[Path] = None) -> ConfigSettings
 dialect = "postgres"
 level = "column"
 output_format = "json"
+catalog_type = "databricks"
+ddl_folder = "./ddl"
+
+[sqlglider.catalog.databricks]
+warehouse_id = "abc123..."
 ```
 
 **Design Notes:**
@@ -488,6 +635,65 @@ output_format = "json"
 - Fail-safe: Never crashes on config errors
 - Forward compatible: Ignores unknown settings for future features
 
+### 8. Catalog Module (`catalog/`)
+
+**Purpose:** Plugin system for fetching DDL from remote data catalogs
+
+The catalog module provides an extensible architecture for connecting to various data catalogs (e.g., Databricks Unity Catalog) and fetching table DDL definitions.
+
+**Plugin Architecture:**
+
+```python
+# Abstract base class
+class Catalog(ABC):
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+    @abstractmethod
+    def get_ddl(self, table_name: str) -> str: ...
+
+    @abstractmethod
+    def get_ddl_batch(self, table_names: List[str]) -> Dict[str, str]: ...
+
+    def configure(self, config: Optional[Dict[str, Any]] = None) -> None: ...
+```
+
+**Registry Pattern:**
+
+- Catalogs are discovered via Python entry points (`sqlglider.catalogs`)
+- Lazy loading with graceful handling of missing optional dependencies
+- Factory function `get_catalog(name)` returns configured instances
+
+**Built-in Catalogs:**
+
+- **databricks**: Databricks Unity Catalog via `databricks-sdk`
+  - Uses `SHOW CREATE TABLE` via statement execution API
+  - Requires warehouse ID for SQL execution
+  - Authentication via env vars or config
+
+**CLI Integration:**
+
+```bash
+# Pull DDL for tables in a SQL file
+sqlglider tables pull query.sql --catalog-type databricks
+
+# Output to folder (one file per table)
+sqlglider tables pull query.sql -c databricks -o ./ddl/
+
+# List available catalog providers
+sqlglider tables pull --list
+```
+
+**Adding Custom Catalogs:**
+
+1. Create a class inheriting from `Catalog`
+2. Register via entry point in `pyproject.toml`:
+   ```toml
+   [project.entry-points."sqlglider.catalogs"]
+   my-catalog = "my_package.catalog:MyCatalog"
+   ```
+
 ## Technology Stack
 
 ### Core Dependencies

{sql_glider-0.1.2 → sql_glider-0.1.4}/CLAUDE.md

@@ -59,6 +59,10 @@ This project uses `uv` for Python package management. Python 3.11+ is required.
 ```
 src/sqlglider/
 ├── cli.py                    # Typer CLI entry point
+├── dissection/
+│   ├── analyzer.py           # DissectionAnalyzer for query decomposition
+│   ├── formatters.py         # Output formatters (text, JSON, CSV)
+│   └── models.py             # ComponentType, SQLComponent, QueryDissectionResult
 ├── graph/
 │   ├── builder.py            # Build lineage graphs from SQL files
 │   ├── merge.py              # Merge multiple graphs
@@ -109,7 +113,7 @@ uv run sqlglider lineage query.sql --dialect postgres
 
 ### Reading from Stdin
 
-All commands (`lineage`, `tables`, `template`) support reading SQL from stdin when no file is provided:
+All commands (`lineage`, `tables overview`, `tables pull`, `template`) support reading SQL from stdin when no file is provided:
 
 ```bash
 # Pipe SQL directly to lineage analysis
@@ -128,8 +132,8 @@ FROM customers c
 JOIN orders o ON c.id = o.customer_id
 EOF
 
-# Pipe to tables command
-echo "SELECT * FROM users JOIN orders ON users.id = orders.user_id" | uv run sqlglider tables
+# Pipe to tables overview command
+echo "SELECT * FROM users JOIN orders ON users.id = orders.user_id" | uv run sqlglider tables overview
 
 # Pipe template with variables
 echo "SELECT * FROM {{ schema }}.users" | uv run sqlglider template --var schema=prod
@@ -174,25 +178,25 @@ Extract all tables involved in SQL files with usage and type information:
 
 ```bash
 # List all tables in a SQL file
-uv run sqlglider tables query.sql
+uv run sqlglider tables overview query.sql
 
 # JSON output
-uv run sqlglider tables query.sql --output-format json
+uv run sqlglider tables overview query.sql --output-format json
 
 # CSV output
-uv run sqlglider tables query.sql --output-format csv
+uv run sqlglider tables overview query.sql --output-format csv
 
 # Export to file
-uv run sqlglider tables query.sql --output-format csv --output-file tables.csv
+uv run sqlglider tables overview query.sql --output-format csv --output-file tables.csv
 
 # Different SQL dialect
-uv run sqlglider tables query.sql --dialect postgres
+uv run sqlglider tables overview query.sql --dialect postgres
 
 # Filter to queries referencing a specific table (multi-query files)
-uv run sqlglider tables multi_query.sql --table customers
+uv run sqlglider tables overview multi_query.sql --table customers
 
 # With templating support
-uv run sqlglider tables query.sql --templater jinja --var schema=analytics
+uv run sqlglider tables overview query.sql --templater jinja --var schema=analytics
 ```
 
 **Output includes:**
@@ -200,6 +204,32 @@ uv run sqlglider tables query.sql --templater jinja --var schema=analytics
 - **Usage**: `INPUT` (read from), `OUTPUT` (written to), or `BOTH`
 - **Object Type**: `TABLE`, `VIEW`, `CTE`, or `UNKNOWN`
 
+### DDL Retrieval from Remote Catalogs
+
+Pull DDL definitions from remote data catalogs for tables used in SQL:
+
+```bash
+# Pull DDL for tables in a SQL file (output to stdout)
+uv run sqlglider tables pull query.sql --catalog-type databricks
+
+# Pull DDL to a folder (one file per table)
+uv run sqlglider tables pull query.sql -c databricks -o ./ddl/
+
+# With templating
+uv run sqlglider tables pull query.sql -c databricks --templater jinja --var schema=prod
+
+# From stdin
+echo "SELECT * FROM my_catalog.my_schema.users" | uv run sqlglider tables pull -c databricks
+
+# List available catalog providers
+uv run sqlglider tables pull --list
+```
+
+**Notes:**
+- Requires optional dependency: `pip install sql-glider[databricks]`
+- CTEs are automatically excluded (they don't exist in remote catalogs)
+- Configure authentication via environment variables (`DATABRICKS_HOST`, `DATABRICKS_TOKEN`, `DATABRICKS_WAREHOUSE_ID`) or `sqlglider.toml`
+
 ### Graph-Based Lineage (Cross-File Analysis)
 
 ```bash
@@ -293,6 +323,45 @@ SELECT * FROM cte
 3. Config file (`[sqlglider.templating.variables]`)
 4. Environment variables (`SQLGLIDER_VAR_*`)
 
+### Query Dissection
+
+Decompose SQL queries into constituent parts for unit testing and analysis:
+
+```bash
+# Dissect a SQL file (text output)
+uv run sqlglider dissect query.sql
+
+# JSON output with full component details
+uv run sqlglider dissect query.sql --output-format json
+
+# CSV output for spreadsheet analysis
+uv run sqlglider dissect query.sql --output-format csv
+
+# Export to file
+uv run sqlglider dissect query.sql --output-format json --output-file dissected.json
+
+# With templating support
+uv run sqlglider dissect query.sql --templater jinja --var schema=analytics
+
+# From stdin
+echo "WITH cte AS (SELECT id FROM users) SELECT * FROM cte" | uv run sqlglider dissect
+```
+
+**Extracted Component Types:**
+- `CTE`: Common Table Expressions from WITH clause
+- `MAIN_QUERY`: The primary SELECT statement
+- `SUBQUERY`: Nested SELECT in FROM clause
+- `SCALAR_SUBQUERY`: Single-value subquery in SELECT list, WHERE, HAVING
+- `TARGET_TABLE`: Output table for INSERT/CREATE/MERGE (not executable)
+- `SOURCE_QUERY`: SELECT within DML/DDL statements
+- `UNION_BRANCH`: Individual SELECT in UNION/UNION ALL
+
+**Use Cases:**
+- Unit test CTEs and subqueries individually
+- Extract DQL from CTAS, CREATE VIEW, INSERT statements
+- Analyze query structure and component dependencies
+- Break apart complex queries for understanding
+
 ## Development Guidelines
 
 ### Code Style

{sql_glider-0.1.2 → sql_glider-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-glider
-Version: 0.1.2
+Version: 0.1.4
 Summary: SQL Utility Toolkit for better understanding, use, and governance of your queries in a native environment.
 Project-URL: Homepage, https://github.com/rycowhi/sql-glider/
 Project-URL: Repository, https://github.com/rycowhi/sql-glider/
@@ -26,6 +26,8 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: rustworkx>=0.15.0
 Requires-Dist: sqlglot[rs]>=25.0.0
 Requires-Dist: typer>=0.9.0
+Provides-Extra: databricks
+Requires-Dist: databricks-sdk>=0.20.0; extra == 'databricks'
 Description-Content-Type: text/markdown
 
 # SQL Glider
@@ -40,6 +42,7 @@ SQL Glider provides powerful column-level and table-level lineage analysis for S
 
 - **Forward Lineage:** Trace output columns back to their source tables and columns
 - **Reverse Lineage:** Impact analysis - find which output columns are affected by a source column
+- **Query Dissection:** Decompose SQL into components (CTEs, subqueries, UNION branches) for unit testing
 - **Table Extraction:** List all tables in SQL files with usage type (INPUT/OUTPUT) and object type (TABLE/VIEW/CTE)
 - **Multi-level Tracing:** Automatically handles CTEs, subqueries, and complex expressions
 - **Graph-Based Lineage:** Build and query lineage graphs across thousands of SQL files
@@ -171,15 +174,32 @@ List all tables involved in SQL files with usage and type information:
 
 ```bash
 # List all tables in a SQL file
-uv run sqlglider tables query.sql
+uv run sqlglider tables overview query.sql
 
 # JSON output with detailed table info
-uv run sqlglider tables query.sql --output-format json
+uv run sqlglider tables overview query.sql --output-format json
 
 # Export to CSV
-uv run sqlglider tables query.sql --output-format csv --output-file tables.csv
+uv run sqlglider tables overview query.sql --output-format csv --output-file tables.csv
 ```
 
+### Pull DDL from Remote Catalogs
+
+Fetch DDL definitions from remote data catalogs (e.g., Databricks Unity Catalog):
+
+```bash
+# Pull DDL for all tables used in a SQL file (outputs to stdout)
+uv run sqlglider tables pull query.sql --catalog-type databricks
+
+# Save DDL files to a folder (one file per table)
+uv run sqlglider tables pull query.sql -c databricks -o ./ddl/
+
+# List available catalog providers
+uv run sqlglider tables pull --list
+```
+
+**Note:** Requires optional dependencies. Install with: `pip install sql-glider[databricks]`
+
 **Example Output (JSON):**
 ```json
 {
@@ -204,6 +224,94 @@ uv run sqlglider tables query.sql --output-format csv --output-file tables.csv
 - `CTE`: Common Table Expression (WITH clause)
 - `UNKNOWN`: Cannot determine type from SQL alone
 
+### Query Dissection
+
+Decompose SQL queries into constituent parts for unit testing and analysis:
+
+```bash
+# Dissect a SQL file (text output)
+uv run sqlglider dissect query.sql
+
+# JSON output with full component details
+uv run sqlglider dissect query.sql --output-format json
+
+# CSV output for spreadsheet analysis
+uv run sqlglider dissect query.sql --output-format csv
+
+# Export to file
+uv run sqlglider dissect query.sql -f json -o dissected.json
+
+# With templating support
+uv run sqlglider dissect query.sql --templater jinja --var schema=analytics
+
+# From stdin
+echo "WITH cte AS (SELECT id FROM users) SELECT * FROM cte" | uv run sqlglider dissect
+```
+
+**Example Input:**
+```sql
+WITH order_totals AS (
+    SELECT customer_id, SUM(amount) AS total
+    FROM orders
+    GROUP BY customer_id
+)
+INSERT INTO analytics.summary
+SELECT * FROM order_totals WHERE total > 100
+```
+
+**Example Output (JSON):**
+```json
+{
+  "queries": [{
+    "query_index": 0,
+    "statement_type": "INSERT",
+    "total_components": 3,
+    "components": [
+      {
+        "component_type": "CTE",
+        "component_index": 0,
+        "name": "order_totals",
+        "sql": "SELECT customer_id, SUM(amount) AS total FROM orders GROUP BY customer_id",
+        "is_executable": true,
+        "dependencies": [],
+        "location": "WITH clause"
+      },
+      {
+        "component_type": "TARGET_TABLE",
+        "component_index": 1,
+        "name": "analytics.summary",
+        "sql": "analytics.summary",
+        "is_executable": false,
+        "location": "INSERT INTO target"
+      },
+      {
+        "component_type": "SOURCE_QUERY",
+        "component_index": 2,
+        "sql": "SELECT * FROM order_totals WHERE total > 100",
+        "is_executable": true,
+        "dependencies": ["order_totals"],
+        "location": "INSERT source SELECT"
+      }
+    ]
+  }]
+}
+```
+
+**Extracted Component Types:**
+- `CTE`: Common Table Expressions from WITH clause
+- `MAIN_QUERY`: The primary SELECT statement
+- `SUBQUERY`: Nested SELECT in FROM clause
+- `SCALAR_SUBQUERY`: Single-value subquery in SELECT list, WHERE, HAVING
+- `TARGET_TABLE`: Output table for INSERT/CREATE/MERGE (not executable)
+- `SOURCE_QUERY`: SELECT within DML/DDL statements
+- `UNION_BRANCH`: Individual SELECT in UNION/UNION ALL
+
+**Use Cases:**
+- Unit test CTEs and subqueries individually
+- Extract DQL from CTAS, CREATE VIEW, INSERT statements
+- Analyze query structure and component dependencies
+- Break apart complex queries for understanding
+
 ### Different SQL Dialects
 
 ```bash
@@ -475,7 +583,7 @@ Options:
 ### Tables Command
 
 ```
-sqlglider tables <sql_file> [OPTIONS]
+sqlglider tables overview <sql_file> [OPTIONS]
 
 Arguments:
   sql_file                    Path to SQL file to analyze [required]
@@ -491,6 +599,66 @@ Options:
   --help                      Show help message and exit
 ```
 
+```
+sqlglider tables pull <sql_file> [OPTIONS]
+
+Arguments:
+  sql_file                    Path to SQL file to analyze [optional, reads from stdin if omitted]
+
+Options:
+  --catalog-type, -c          Catalog provider (e.g., 'databricks') [required if not in config]
+  --ddl-folder, -o            Output folder for DDL files [optional, outputs to stdout if omitted]
+  --dialect, -d               SQL dialect (spark, postgres, snowflake, etc.) [default: spark]
+  --templater, -t             Templater for SQL preprocessing (e.g., 'jinja', 'none') [optional]
+  --var, -v                   Template variable in key=value format (repeatable) [optional]
+  --vars-file                 Path to variables file (JSON or YAML) [optional]
+  --list, -l                  List available catalog providers and exit
+  --help                      Show help message and exit
+```
+
+**Databricks Setup:**
+
+Install the optional Databricks dependency:
+```bash
+pip install sql-glider[databricks]
+```
+
+Configure authentication (via environment variables or `sqlglider.toml`):
+```bash
+export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
+export DATABRICKS_TOKEN="dapi..."
+export DATABRICKS_WAREHOUSE_ID="abc123..."
+```
+
+### Dissect Command
+
+```
+sqlglider dissect [sql_file] [OPTIONS]
+
+Arguments:
+  sql_file                    Path to SQL file to analyze [optional, reads from stdin if omitted]
+
+Options:
+  --dialect, -d               SQL dialect (spark, postgres, snowflake, etc.) [default: spark]
+  --output-format, -f         Output format: 'text', 'json', or 'csv' [default: text]
+  --output-file, -o           Write output to file instead of stdout [optional]
+  --templater, -t             Templater for SQL preprocessing (e.g., 'jinja', 'none') [optional]
+  --var, -v                   Template variable in key=value format (repeatable) [optional]
+  --vars-file                 Path to variables file (JSON or YAML) [optional]
+  --help                      Show help message and exit
+```
+
+**Output Fields:**
+- `component_type`: Type of component (CTE, MAIN_QUERY, SUBQUERY, etc.)
+- `component_index`: Sequential order within the query (0-based)
+- `name`: CTE name, subquery alias, or target table name
+- `sql`: The extracted SQL for this component
+- `is_executable`: Whether the component can run standalone (TARGET_TABLE is false)
+- `dependencies`: List of CTE names this component references
+- `location`: Human-readable context (e.g., "WITH clause", "FROM clause")
+- `depth`: Nesting level (0 = top-level)
+- `parent_index`: Index of parent component for nested components
+
 ### Graph Commands
 
 ```
@@ -612,6 +780,10 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed technical documentation.
 ```
 src/sqlglider/
 ├── cli.py                    # Typer CLI entry point
+├── dissection/
+│   ├── analyzer.py           # DissectionAnalyzer for query decomposition
+│   ├── formatters.py         # Output formatters (text, JSON, CSV)
+│   └── models.py             # ComponentType, SQLComponent, QueryDissectionResult
 ├── graph/
 │   ├── builder.py            # Build graphs from SQL files
 │   ├── merge.py              # Merge multiple graphs