catalogkit-query 0.1.0__py3-none-any.whl

catalogkit/query/__init__.py

@@ -0,0 +1,39 @@
+"""Public package surface for catalogkit-query."""
+
+from __future__ import annotations
+
+from catalogkit.core import CatalogArtifact
+
+from ._version import __version__
+from .api import build_catalog_artifact, build_query_map, render_json, render_text
+from .errors import QueryMapContractError, QueryMapError, QueryMapParseError
+from .models import (
+    OutputColumn,
+    OutputSourceHint,
+    QueryMap,
+    QuerySummary,
+    Relation,
+    RelationEdge,
+    RelationUsage,
+    WarningEntry,
+)
+
+__all__ = [
+    "__version__",
+    "build_catalog_artifact",
+    "build_query_map",
+    "CatalogArtifact",
+    "OutputColumn",
+    "OutputSourceHint",
+    "QueryMap",
+    "QuerySummary",
+    "QueryMapContractError",
+    "QueryMapError",
+    "QueryMapParseError",
+    "Relation",
+    "RelationEdge",
+    "RelationUsage",
+    "render_json",
+    "render_text",
+    "WarningEntry",
+]

catalogkit/query/__main__.py

@@ -0,0 +1,9 @@
+"""Module entrypoint for `python -m catalogkit.query`."""
+
+from __future__ import annotations
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

catalogkit/query/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.1.0"

catalogkit/query/api.py

@@ -0,0 +1,39 @@
+"""Public API for catalogkit-query."""
+
+from __future__ import annotations
+
+from catalogkit.core import CatalogArtifact
+
+from .build import build_catalog_artifact_from_parsed, build_query_map_from_parsed
+from .models import QueryMap
+from .parser import parse_statement
+from .render.json import render_json
+from .render.text import render_text
+
+
+def build_query_map(
+    sql: str,
+    *,
+    dialect: str,
+) -> QueryMap:
+    """Build the public catalogkit-query artifact for one SQL statement."""
+    parsed = parse_statement(sql, dialect=dialect)
+    return build_query_map_from_parsed(parsed)
+
+
+def build_catalog_artifact(
+    sql: str,
+    *,
+    dialect: str,
+) -> CatalogArtifact:
+    """Build the shared catalog artifact for CatalogKit composition."""
+    parsed = parse_statement(sql, dialect=dialect)
+    return build_catalog_artifact_from_parsed(parsed)
+
+
+__all__ = [
+    "build_catalog_artifact",
+    "build_query_map",
+    "render_json",
+    "render_text",
+]

catalogkit/query/ast_utils.py

@@ -0,0 +1,72 @@
+"""Shared sqlglot AST helpers for catalogkit-query."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from sqlglot import exp
+
+
+def iter_ctes(root_expression: exp.Expression) -> Iterable[exp.CTE]:
+    """Yield every CTE in the parsed query."""
+    yield from root_expression.find_all(exp.CTE)
+
+
+def cte_name(cte: exp.CTE) -> str:
+    """Return the raw CTE name from the AST."""
+    alias = cte.alias
+    if isinstance(alias, str):
+        return alias
+    return str(alias or "").strip()
+
+
+def qualified_table_name(table: exp.Table) -> str:
+    """Return the dotted table name as it appears in the AST."""
+    parts = [
+        str(part).strip()
+        for part in (table.catalog, table.db, table.name)
+        if str(part or "").strip()
+    ]
+    return ".".join(parts)
+
+
+def has_join_ancestor(node: exp.Expression, *, stop_node: exp.Expression) -> bool:
+    """Detect whether a table node appears under a JOIN subtree."""
+    current = node.parent
+    while current is not None and current is not stop_node:
+        if isinstance(current, exp.Join):
+            return True
+        current = current.parent
+    return False
+
+
+def iter_table_nodes(expression: exp.Expression | None) -> Iterable[exp.Table]:
+    """Yield all table nodes under an expression."""
+    if expression is None:
+        return
+    for table in expression.find_all(exp.Table):
+        yield table
+
+
+def iter_table_nodes_skipping_ctes(
+    expression: exp.Expression | None,
+) -> Iterable[exp.Table]:
+    """Yield table nodes while skipping traversal into nested CTE definitions."""
+    if expression is None:
+        return
+    yield from _walk_tables(expression, skip_ctes=True)
+
+
+def _walk_tables(expression: exp.Expression, *, skip_ctes: bool) -> Iterable[exp.Table]:
+    if skip_ctes and isinstance(expression, exp.CTE):
+        return
+    if isinstance(expression, exp.Table):
+        yield expression
+        return
+    for child in expression.args.values():
+        if isinstance(child, list):
+            for item in child:
+                if isinstance(item, exp.Expression):
+                    yield from _walk_tables(item, skip_ctes=skip_ctes)
+        elif isinstance(child, exp.Expression):
+            yield from _walk_tables(child, skip_ctes=skip_ctes)

catalogkit/query/build.py

@@ -0,0 +1,249 @@
+"""Artifact assembly for catalogkit-query."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from catalogkit.core import CatalogArtifact, Edge, Evidence, Warning, merge
+from sqlglot import exp
+
+from .ctes import extract_dependency_edges
+from .errors import QueryMapContractError
+from .models import (
+    EdgeKind as QueryMapEdgeKind,
+    QueryMap,
+    QuerySummary,
+    RelationEdge,
+    RelationUsage,
+    WarningCode,
+    WarningEntry,
+)
+from .parser import ParsedStatement
+from .relations import RelationExtraction, extract_relations
+
+_QUERYMAP_EDGE_KINDS = {"depends_on", "joins"}
+_QUERYMAP_WARNING_CODES = {
+    "parse_recovered",
+    "select_star",
+    "table_star",
+    "ambiguous_output_source",
+    "unresolved_output_source",
+    "non_equi_join",
+    "unsupported_construct",
+}
+
+
+def build_query_map_from_parsed(parsed: ParsedStatement) -> QueryMap:
+    """Build the public catalogkit-query artifact for one parsed SQL statement."""
+    artifact, relation_extraction = _build_catalog_artifact_from_parsed(parsed)
+
+    edges = [_relation_edge_from_catalog_edge(edge) for edge in artifact.edges]
+    warnings = [_warning_entry_from_warning(warning) for warning in artifact.warnings]
+    summary = QuerySummary(
+        dialect=parsed.dialect,
+        statement_type=parsed.statement.key.lower(),
+        has_ctes=bool(relation_extraction.cte_nodes),
+        relation_count=len(relation_extraction.relations),
+        cte_count=len(relation_extraction.cte_nodes),
+        output_count=0,
+    )
+
+    return QueryMap(
+        version=artifact.version,
+        summary=summary,
+        relations=relation_extraction.relations,
+        relation_usages=[
+            RelationUsage(
+                relation_id=usage.relation_id,
+                alias=usage.alias,
+                context=usage.context,
+                sql=usage.sql,
+                normalized_sql=usage.sql,
+            )
+            for usage in relation_extraction.relation_usages
+        ],
+        edges=_dedupe_query_map_edges(edges),
+        outputs=[],
+        warnings=_dedupe_warnings(warnings),
+    )
+
+
+def build_catalog_artifact_from_parsed(parsed: ParsedStatement) -> CatalogArtifact:
+    """Build the shared catalog artifact used for CatalogKit composition."""
+    artifact, _ = _build_catalog_artifact_from_parsed(parsed)
+    return artifact
+
+
+def _build_catalog_artifact_from_parsed(
+    parsed: ParsedStatement,
+) -> tuple[CatalogArtifact, RelationExtraction]:
+    """Build the internal shared artifact and keep extraction metadata nearby."""
+    relation_extraction = extract_relations(parsed.root_expression, dialect=parsed.dialect)
+    dependency_extraction = extract_dependency_edges(
+        parsed.root_expression,
+        relation_extraction=relation_extraction,
+        dialect=parsed.dialect,
+    )
+
+    if not relation_extraction.nodes:
+        raise QueryMapContractError("No tables or CTE relations were found in the SQL statement.")
+
+    nodes_by_id = {node.id: node.model_copy(deep=True) for node in relation_extraction.nodes}
+    for usage in relation_extraction.relation_usages:
+        node = nodes_by_id[usage.relation_id]
+        node.evidence.append(
+            Evidence(
+                location=usage.context,
+                expression=usage.sql,
+                confidence="high",
+            )
+        )
+
+    artifact = CatalogArtifact(
+        nodes=sorted(nodes_by_id.values(), key=lambda node: node.id),
+        edges=dependency_extraction.edges,
+        warnings=[
+            *dependency_extraction.warnings,
+            *_extract_contract_warnings(parsed.root_expression, dialect=parsed.dialect),
+        ],
+    )
+    return merge(artifact), relation_extraction
+
+
+def _extract_contract_warnings(
+    root_expression: Any,
+    *,
+    dialect: str,
+) -> list[Warning]:
+    warnings: list[Warning] = []
+
+    union_expression = root_expression.find(exp.Union)
+    if union_expression is not None:
+        warnings.append(
+            Warning(
+                code="unsupported_construct",
+                message="UNION queries are mapped at the relation level only in the MVP.",
+                location=union_expression.sql(dialect=dialect),
+            )
+        )
+    intersect_expression = root_expression.find(exp.Intersect)
+    if intersect_expression is not None:
+        warnings.append(
+            Warning(
+                code="unsupported_construct",
+                message="INTERSECT queries are mapped at the relation level only in the MVP.",
+                location=intersect_expression.sql(dialect=dialect),
+            )
+        )
+    except_expression = root_expression.find(exp.Except)
+    if except_expression is not None:
+        warnings.append(
+            Warning(
+                code="unsupported_construct",
+                message="EXCEPT queries are mapped at the relation level only in the MVP.",
+                location=except_expression.sql(dialect=dialect),
+            )
+        )
+
+    for select in root_expression.find_all(exp.Select):
+        for selection in select.expressions:
+            if isinstance(selection, exp.Star):
+                warnings.append(
+                    Warning(
+                        code="select_star",
+                        message="SELECT * was detected; output mapping is deferred in the MVP.",
+                        location=selection.sql(dialect=dialect),
+                    )
+                )
+            elif isinstance(selection, exp.Column) and str(selection.name or "").strip() == "*":
+                warnings.append(
+                    Warning(
+                        code="table_star",
+                        message="table.* was detected; output mapping is deferred in the MVP.",
+                        location=selection.sql(dialect=dialect),
+                    )
+                )
+
+    for join in root_expression.find_all(exp.Join):
+        on_clause = join.args.get("on")
+        using_clause = join.args.get("using")
+        if on_clause is None and using_clause is None:
+            warnings.append(
+                Warning(
+                    code="unsupported_construct",
+                    message="JOIN without ON/USING is not modeled beyond relation dependency mapping.",
+                    location=join.sql(dialect=dialect),
+                )
+            )
+            continue
+        if on_clause is not None and not _is_equality_join(on_clause):
+            warnings.append(
+                Warning(
+                    code="non_equi_join",
+                    message="Non-equality join detected; MVP preserves relation dependencies but does not model join semantics.",
+                    location=join.sql(dialect=dialect),
+                )
+            )
+
+    return warnings
+
+
+def _is_equality_join(expression: Any) -> bool:
+    if isinstance(expression, exp.EQ):
+        return True
+    if isinstance(expression, exp.And):
+        return _is_equality_join(expression.left) and _is_equality_join(expression.right)
+    return False
+
+
+def _relation_edge_from_catalog_edge(edge: Edge) -> RelationEdge:
+    if edge.kind not in _QUERYMAP_EDGE_KINDS:
+        raise QueryMapContractError(
+            f"catalogkit-query cannot emit unsupported edge kind {edge.kind!r} in its public contract."
+        )
+    sql = edge.evidence[0].expression if edge.evidence else None
+    return RelationEdge(
+        kind=cast(QueryMapEdgeKind, edge.kind),
+        source_id=edge.source_id,
+        target_id=edge.target_id,
+        label=edge.label,
+        confidence=edge.confidence,
+        sql=sql,
+        normalized_sql=sql,
+    )
+
+
+def _warning_entry_from_warning(warning: Warning) -> WarningEntry:
+    if warning.code not in _QUERYMAP_WARNING_CODES:
+        raise QueryMapContractError(
+            f"catalogkit-query cannot emit unsupported warning code {warning.code!r} in its public contract."
+        )
+    return WarningEntry(
+        code=cast(WarningCode, warning.code),
+        message=warning.message,
+        location=warning.location,
+    )
+
+
+def _dedupe_query_map_edges(edges: list[RelationEdge]) -> list[RelationEdge]:
+    seen: set[tuple[str, str, str | None]] = set()
+    deduped: list[RelationEdge] = []
+    for edge in edges:
+        key = (edge.source_id, edge.target_id, edge.sql)
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(edge)
+    return deduped
+
+
+def _dedupe_warnings(warnings: list[WarningEntry]) -> list[WarningEntry]:
+    seen: set[tuple[str, str, str | None]] = set()
+    deduped: list[WarningEntry] = []
+    for warning in warnings:
+        key = (warning.code, warning.message, warning.location)
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(warning)
+    return deduped

catalogkit/query/cli.py

@@ -0,0 +1,61 @@
+"""CLI entrypoint for catalogkit-query."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .api import build_query_map, render_json, render_text
+from .errors import QueryMapError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="catalogkit-query",
+        description="Map one supported SQL statement into deterministic catalog dependencies.",
+    )
+    parser.add_argument(
+        "sql_file",
+        help="Path to a UTF-8 SQL file containing exactly one supported statement.",
+    )
+    parser.add_argument(
+        "--dialect",
+        required=True,
+        help="sqlglot dialect name, for example postgres, snowflake, tsql, or bigquery.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("text", "json"),
+        default="text",
+        help="Renderer output format.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        sql = Path(args.sql_file).read_text(encoding="utf-8")
+        artifact = build_query_map(sql, dialect=args.dialect)
+        if args.format == "json":
+            print(json.dumps(render_json(artifact), indent=2, sort_keys=False))
+        else:
+            print(render_text(artifact))
+        return 0
+    except (OSError, QueryMapError) as exc:
+        print(f"catalogkit-query error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

catalogkit/query/ctes.py

@@ -0,0 +1,111 @@
+"""Dependency edge extraction for catalogkit-query."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from catalogkit.core import Edge, Evidence, Warning, cte_id, normalize_identifier, normalize_identifier_part
+from sqlglot import exp
+
+from .ast_utils import cte_name, iter_ctes, iter_table_nodes, iter_table_nodes_skipping_ctes, qualified_table_name
+from .errors import QueryMapContractError
+from .relations import RelationExtraction
+
+
+@dataclass(frozen=True)
+class DependencyExtraction:
+    edges: list[Edge]
+    warnings: list[Warning]
+
+
+def extract_dependency_edges(
+    root_expression: exp.Expression,
+    *,
+    relation_extraction: RelationExtraction,
+    dialect: str,
+) -> DependencyExtraction:
+    """Extract relation-level dependency edges for root query and CTEs."""
+    edges: list[Edge] = []
+    warnings: list[Warning] = []
+
+    for cte in iter_ctes(root_expression):
+        raw_cte_name = cte_name(cte)
+        if not raw_cte_name:
+            continue
+        source_id = cte_id(raw_cte_name)
+        for table in iter_table_nodes(cte.this):
+            target_id = _resolve_relation_id(table, relation_extraction=relation_extraction)
+            if target_id is None:
+                continue
+            if target_id == source_id:
+                warnings.append(
+                    Warning(
+                        code="unsupported_construct",
+                        message=f"Recursive CTE {normalize_identifier_part(raw_cte_name)!r} is not modeled explicitly in the MVP.",
+                        location=table.sql(dialect=dialect),
+                    )
+                )
+                continue
+            edges.append(
+                Edge(
+                    kind="depends_on",
+                    source_id=source_id,
+                    target_id=target_id,
+                    label="depends_on",
+                    confidence="high",
+                    evidence=[
+                        Evidence(
+                            location="cte_body",
+                            expression=table.sql(dialect=dialect),
+                            confidence="high",
+                        )
+                    ],
+                )
+            )
+
+    for table in iter_table_nodes_skipping_ctes(root_expression):
+        target_id = _resolve_relation_id(table, relation_extraction=relation_extraction)
+        if target_id is None:
+            continue
+        edges.append(
+            Edge(
+                kind="depends_on",
+                source_id="query:root",
+                target_id=target_id,
+                label="depends_on",
+                confidence="high",
+                evidence=[
+                    Evidence(
+                        location="root_query",
+                        expression=table.sql(dialect=dialect),
+                        confidence="high",
+                    )
+                ],
+            )
+        )
+
+    return DependencyExtraction(edges=edges, warnings=warnings)
+
+
+def _resolve_relation_id(
+    table: exp.Table,
+    *,
+    relation_extraction: RelationExtraction,
+) -> str | None:
+    name = str(table.name or "").strip()
+    if not name:
+        return None
+
+    cte_node = relation_extraction.cte_nodes.get(normalize_identifier_part(name))
+    if cte_node is not None:
+        return cte_node.id
+
+    qualified_name = qualified_table_name(table)
+    normalized_qualified_name = normalize_identifier(qualified_name)
+    table_node = relation_extraction.table_nodes.get(normalized_qualified_name)
+    if table_node is not None:
+        return table_node.id
+
+    raise QueryMapContractError(
+        f"Unresolved relation id for table reference {qualified_name!r}."
+    )

catalogkit/query/errors.py

@@ -0,0 +1,15 @@
+"""Package-specific errors for catalogkit-query."""
+
+from __future__ import annotations
+
+
+class QueryMapError(Exception):
+    """Base class for catalogkit-query failures."""
+
+
+class QueryMapParseError(QueryMapError):
+    """Raised when SQL cannot be parsed into a supported AST."""
+
+
+class QueryMapContractError(QueryMapError):
+    """Raised when parsed SQL cannot be represented by the current contract."""

catalogkit/query/models.py

@@ -0,0 +1,93 @@
+"""Public artifact models for catalogkit-query."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Confidence = Literal["high", "medium", "low"]
+RelationKind = Literal["table", "cte"]
+RelationUsageContext = Literal["from", "join", "cte_body"]
+EdgeKind = Literal["depends_on", "joins"]
+WarningCode = Literal[
+    "parse_recovered",
+    "select_star",
+    "table_star",
+    "ambiguous_output_source",
+    "unresolved_output_source",
+    "non_equi_join",
+    "unsupported_construct",
+]
+
+
+class QuerySummary(BaseModel):
+    dialect: str
+    statement_type: str
+    has_ctes: bool
+    relation_count: int
+    cte_count: int
+    output_count: int = 0
+
+
+class Relation(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+    kind: RelationKind
+    name: str
+    qualified_name: str | None = None
+    schema_name: str | None = Field(
+        default=None,
+        alias="schema",
+        serialization_alias="schema",
+    )
+
+
+class RelationUsage(BaseModel):
+    relation_id: str
+    alias: str | None = None
+    context: RelationUsageContext
+    sql: str
+    normalized_sql: str | None = None
+
+
+class RelationEdge(BaseModel):
+    kind: EdgeKind
+    source_id: str
+    target_id: str
+    label: str | None = None
+    confidence: Confidence = "high"
+    sql: str | None = None
+    normalized_sql: str | None = None
+
+
+class OutputSourceHint(BaseModel):
+    relation_id: str | None = None
+    column_name: str | None = None
+    confidence: Confidence = "medium"
+
+
+class OutputColumn(BaseModel):
+    name: str
+    ordinal: int
+    expression_sql: str
+    normalized_expression_sql: str | None = None
+    inferred: bool = False
+    sources: list[OutputSourceHint] = Field(default_factory=list)
+
+
+class WarningEntry(BaseModel):
+    code: WarningCode
+    message: str
+    location: str | None = None
+
+
+class QueryMap(BaseModel):
+    version: str = "1"
+    summary: QuerySummary
+    relations: list[Relation] = Field(default_factory=list)
+    relation_usages: list[RelationUsage] = Field(default_factory=list)
+    edges: list[RelationEdge] = Field(default_factory=list)
+    outputs: list[OutputColumn] = Field(default_factory=list)
+    warnings: list[WarningEntry] = Field(default_factory=list)

catalogkit/query/parser.py

@@ -0,0 +1,57 @@
+"""sqlglot parsing helpers for catalogkit-query."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import sqlglot
+from sqlglot import exp
+
+from .errors import QueryMapContractError, QueryMapParseError
+
+
+@dataclass(frozen=True)
+class ParsedStatement:
+    statement: exp.Expression
+    root_expression: exp.Expression
+    dialect: str
+
+
+def parse_statement(sql: str, *, dialect: str) -> ParsedStatement:
+    """Parse exactly one SQL statement into a supported AST."""
+    cleaned = (sql or "").strip()
+    if not cleaned:
+        raise QueryMapParseError("SQL input is empty.")
+
+    try:
+        statements = [stmt for stmt in sqlglot.parse(cleaned, read=dialect) if stmt is not None]
+    except Exception as exc:
+        raise QueryMapParseError(f"Failed to parse SQL with dialect {dialect!r}: {exc}") from exc
+
+    if not statements:
+        raise QueryMapParseError("SQL input produced no parseable statements.")
+    if len(statements) != 1:
+        raise QueryMapContractError("catalogkit-query accepts exactly one SQL statement per invocation.")
+
+    statement = statements[0]
+    root_expression = _unwrap_root_expression(statement)
+    if not isinstance(root_expression, exp.Query):
+        raise QueryMapContractError(
+            "catalogkit-query supports exactly one SELECT, INSERT ... SELECT, or CREATE ... AS SELECT statement per invocation."
+        )
+    return ParsedStatement(statement=statement, root_expression=root_expression, dialect=dialect)
+
+
+def _unwrap_root_expression(statement: exp.Expression) -> exp.Expression:
+    """Return the query-like root expression used for structure mapping."""
+    if isinstance(statement, exp.Create):
+        expression = statement.args.get("expression")
+        if isinstance(expression, exp.Expression):
+            return expression
+
+    if isinstance(statement, exp.Insert):
+        expression = statement.args.get("expression")
+        if isinstance(expression, exp.Expression):
+            return expression
+
+    return statement

catalogkit/query/relations.py

@@ -0,0 +1,210 @@
+"""Relation discovery for catalogkit-query."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from catalogkit.core import Node, cte_id, leaf_name, normalize_identifier, normalize_identifier_part, schema_name, table_id
+from sqlglot import exp
+
+from .ast_utils import (
+    cte_name,
+    has_join_ancestor,
+    iter_ctes,
+    iter_table_nodes,
+    iter_table_nodes_skipping_ctes,
+    qualified_table_name,
+)
+from .models import Relation
+
+RelationUsageContext = Literal["from", "join", "cte_body"]
+
+
+@dataclass(frozen=True)
+class RelationUsage:
+    relation_id: str
+    alias: str | None
+    context: RelationUsageContext
+    sql: str
+
+
+@dataclass(frozen=True)
+class RelationExtraction:
+    nodes: list[Node]
+    relations: list[Relation]
+    relation_usages: list[RelationUsage]
+    cte_nodes: dict[str, Node]
+    table_nodes: dict[str, Node]
+    relation_by_id: dict[str, Relation]
+
+
+def extract_relations(root_expression: exp.Expression, *, dialect: str) -> RelationExtraction:
+    """Extract canonical table and CTE nodes plus usage evidence."""
+    cte_nodes = _extract_cte_nodes(root_expression)
+    cte_relations = _extract_cte_relations(root_expression)
+    table_nodes: dict[str, Node] = {}
+    relation_by_id: dict[str, Relation] = {
+        relation.id: relation for relation in cte_relations.values()
+    }
+    relation_usages: list[RelationUsage] = []
+
+    for cte in iter_ctes(root_expression):
+        for table in iter_table_nodes(cte.this):
+            node = _resolve_node(
+                table,
+                cte_nodes=cte_nodes,
+                table_nodes=table_nodes,
+                relation_by_id=relation_by_id,
+                cte_relations=cte_relations,
+            )
+            if node is None:
+                continue
+            relation_usages.append(
+                _build_usage(
+                    relation_id=node.id,
+                    table=table,
+                    context="join" if has_join_ancestor(table, stop_node=cte.this) else "cte_body",
+                    dialect=dialect,
+                )
+            )
+
+    for table in iter_table_nodes_skipping_ctes(root_expression):
+        node = _resolve_node(
+            table,
+            cte_nodes=cte_nodes,
+            table_nodes=table_nodes,
+            relation_by_id=relation_by_id,
+            cte_relations=cte_relations,
+        )
+        if node is None:
+            continue
+        relation_usages.append(
+            _build_usage(
+                relation_id=node.id,
+                table=table,
+                context="join" if has_join_ancestor(table, stop_node=root_expression) else "from",
+                dialect=dialect,
+            )
+        )
+
+    nodes = sorted([*table_nodes.values(), *cte_nodes.values()], key=lambda node: node.id)
+    relations = sorted(relation_by_id.values(), key=lambda relation: relation.id)
+    return RelationExtraction(
+        nodes=nodes,
+        relations=relations,
+        relation_usages=_dedupe_usages(relation_usages),
+        cte_nodes=cte_nodes,
+        table_nodes=table_nodes,
+        relation_by_id=relation_by_id,
+    )
+
+
+def _extract_cte_nodes(root_expression: exp.Expression) -> dict[str, Node]:
+    nodes: dict[str, Node] = {}
+    for cte in iter_ctes(root_expression):
+        raw_name = cte_name(cte)
+        if not raw_name:
+            continue
+        normalized_name = normalize_identifier_part(raw_name)
+        node = Node(
+            id=cte_id(raw_name),
+            kind="cte",
+            name=normalized_name,
+        )
+        nodes[normalized_name] = node
+    return nodes
+
+
+def _extract_cte_relations(root_expression: exp.Expression) -> dict[str, Relation]:
+    relations: dict[str, Relation] = {}
+    for cte in iter_ctes(root_expression):
+        raw_name = cte_name(cte)
+        if not raw_name:
+            continue
+        normalized_name = normalize_identifier_part(raw_name)
+        relations[normalized_name] = Relation(
+            id=cte_id(raw_name),
+            kind="cte",
+            name=raw_name,
+        )
+    return relations
+
+
+def _resolve_node(
+    table: exp.Table,
+    *,
+    cte_nodes: dict[str, Node],
+    table_nodes: dict[str, Node],
+    relation_by_id: dict[str, Relation],
+    cte_relations: dict[str, Relation],
+) -> Node | None:
+    table_name = str(table.name or "").strip()
+    if not table_name:
+        return None
+
+    normalized_table_name = normalize_identifier_part(table_name)
+    cte_node = cte_nodes.get(normalized_table_name)
+    if cte_node is not None:
+        relation_by_id[cte_node.id] = cte_relations[normalized_table_name]
+        return cte_node
+
+    qualified_name = qualified_table_name(table)
+    normalized_qualified_name = normalize_identifier(qualified_name)
+    node = table_nodes.get(normalized_qualified_name)
+    if node is None:
+        raw_schema_name = _raw_schema_name(table)
+        node = Node(
+            id=table_id(qualified_name),
+            kind="table",
+            name=leaf_name(qualified_name),
+            qualified_name=normalized_qualified_name,
+            schema=schema_name(qualified_name),
+        )
+        table_nodes[normalized_qualified_name] = node
+        relation_by_id[node.id] = Relation(
+            id=node.id,
+            kind="table",
+            name=table_name,
+            qualified_name=qualified_name,
+            schema=raw_schema_name,
+        )
+    return node
+
+
+def _build_usage(
+    *,
+    relation_id: str,
+    table: exp.Table,
+    context: RelationUsageContext,
+    dialect: str,
+) -> RelationUsage:
+    return RelationUsage(
+        relation_id=relation_id,
+        alias=str(table.alias or "").strip() or None,
+        context=context,
+        sql=table.sql(dialect=dialect),
+    )
+
+
+def _dedupe_usages(usages: list[RelationUsage]) -> list[RelationUsage]:
+    seen: set[tuple[str, str | None, str, str]] = set()
+    deduped: list[RelationUsage] = []
+    for usage in usages:
+        key = (usage.relation_id, usage.alias, usage.context, usage.sql)
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(usage)
+    return deduped
+
+
+def _raw_schema_name(table: exp.Table) -> str | None:
+    parts = [
+        str(part).strip()
+        for part in (table.catalog, table.db)
+        if str(part or "").strip()
+    ]
+    if not parts:
+        return None
+    return ".".join(parts)

catalogkit/query/render/__init__.py

@@ -0,0 +1 @@
+"""Renderers for catalogkit-query."""

catalogkit/query/render/json.py

@@ -0,0 +1,10 @@
+"""JSON renderer for catalogkit-query."""
+
+from __future__ import annotations
+
+from ..models import QueryMap
+
+
+def render_json(query_map: QueryMap) -> dict:
+    """Return the canonical JSON-serializable catalogkit-query artifact."""
+    return query_map.model_dump(mode="json", by_alias=True)

catalogkit/query/render/text.py

@@ -0,0 +1,42 @@
+"""Text renderer for catalogkit-query."""
+
+from __future__ import annotations
+
+from ..models import QueryMap
+
+
+def render_text(query_map: QueryMap) -> str:
+    """Render the public catalogkit-query artifact for human reading."""
+    lines: list[str] = []
+    summary = query_map.summary
+
+    lines.append("catalogkit-query")
+    lines.append(f"dialect: {summary.dialect}")
+    lines.append(f"statement_type: {summary.statement_type}")
+    lines.append(f"has_ctes: {summary.has_ctes}")
+    lines.append("")
+
+    lines.append("relations:")
+    for relation in query_map.relations:
+        display_name = relation.qualified_name or relation.name
+        lines.append(f"  - [{relation.kind}] {display_name}")
+
+    lines.append("")
+    lines.append("relation_usages:")
+    for usage in query_map.relation_usages:
+        alias = f" alias={usage.alias}" if usage.alias else ""
+        lines.append(f"  - {usage.context}: {usage.relation_id}{alias} :: {usage.sql}")
+
+    lines.append("")
+    lines.append("dependencies:")
+    for edge in query_map.edges:
+        lines.append(f"  - {edge.source_id} -> {edge.target_id}")
+
+    if query_map.warnings:
+        lines.append("")
+        lines.append("warnings:")
+        for warning in query_map.warnings:
+            location = f" [{warning.location}]" if warning.location else ""
+            lines.append(f"  - {warning.code}: {warning.message}{location}")
+
+    return "\n".join(lines)

catalogkit_query-0.1.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: catalogkit-query
+Version: 0.1.0
+Summary: Map one SQL statement into deterministic CatalogKit dependencies.
+Author: ClearMetric Labs
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Clearmetric-Labs/CatalogKit
+Project-URL: Source, https://github.com/Clearmetric-Labs/CatalogKit
+Project-URL: Issues, https://github.com/Clearmetric-Labs/CatalogKit/issues
+Keywords: sql,lineage,dependencies,ctes,sqlglot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: catalogkit-core>=0.1.0
+Requires-Dist: sqlglot>=25.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build>=1.2.2; extra == "release"
+Requires-Dist: twine>=5.1.1; extra == "release"
+
+# catalogkit-query
+
+`catalogkit-query` maps one supported SQL statement into a deterministic `QueryMap`
+artifact so you can answer "what feeds what in this query?" fast.
+
+It is a narrow static-analysis tool:
+
+- input: exactly one SQL statement from one SQL file
+- output: canonical relations, relation usages, dependency edges, and warnings
+- no warehouse credentials
+- no dbt project
+- no AI key
+
+## Install
+
+```bash
+python -m pip install catalogkit-query
+```
+
+## Imports
+
+```python
+from catalogkit.query import build_catalog_artifact, build_query_map
+```
+
+For local development:
+
+```bash
+python -m pip install -e ../catalogkit-core
+python -m pip install -e ".[dev,release]"
+```
+
+## Quickstart
+
+```bash
+catalogkit-query --dialect postgres ./examples/ugly_real_world.sql
+catalogkit-query --dialect postgres --format json ./examples/ugly_real_world.sql
+```
+
+## Output Contract
+
+`catalogkit-query` preserves its public `QueryMap` shape:
+
+- `summary`
+- `relations`
+- `relation_usages`
+- `edges`
+- `outputs`
+- `warnings`
+
+For CatalogKit composition, the package also exposes a shared
+`CatalogArtifact` builder backed by `catalogkit-core`.
+
+The shared core artifact contains:
+
+- `version`
+- `nodes`
+- `edges`
+- `warnings`
+
+## Supported Statements
+
+`catalogkit-query` accepts exactly one supported statement per invocation:
+
+- `SELECT ...`
+- `INSERT ... SELECT ...`
+- `CREATE ... AS SELECT ...`
+
+Unsupported statement shapes fail loudly.
+
+## Contract Docs
+
+- [`../catalogkit-core/docs/contract.md`](../catalogkit-core/docs/contract.md)
+- [`docs/limitations.md`](docs/limitations.md)

catalogkit_query-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+catalogkit/query/__init__.py,sha256=6qW-plZ1StWh0O2Q_FxnyuOgGroUPxixIOIGdUzQSKo,873
+catalogkit/query/__main__.py,sha256=iIrnnBjgpYVZD63t9ru8KzuP4CGDw6Cz_0k4UI962PI,175
+catalogkit/query/_version.py,sha256=VDsBswzfU7gNsBkIaxxV6tsi0ixlms3WjN7HYgZJZ2g,46
+catalogkit/query/api.py,sha256=xklIf3019k_StOzHqZhRlRVgngEgMJ224Auw0KcRS-M,969
+catalogkit/query/ast_utils.py,sha256=ZUxja752oU6gVJ29hDd9hOFU-YDvGhwYb7s5J6e80Z4,2272
+catalogkit/query/build.py,sha256=2C_XlIhb1kBPcYZCmdgVIB35ROCq9eq8QHCQEw05ZKI,8733
+catalogkit/query/cli.py,sha256=JchrYitnOPFR-z7iVmOwh4H4wN-RY_73G5SA_6morVM,1692
+catalogkit/query/ctes.py,sha256=a7CgBz7Jfs8VOBMPsI_TIP3qSfkjjLcV_H2833KETqw,3687
+catalogkit/query/errors.py,sha256=9WFMZGViim10tDJ9sYDzb-_5TSr0ZLDnaDJg803SSB0,408
+catalogkit/query/models.py,sha256=2BLSWPai196SAe_g4GeAuVq8m_JvMB2NzvTkYPEytzY,2272
+catalogkit/query/parser.py,sha256=NEAMWtZGPEIXY8zBb-YvufJd1ZTEjfdLyrzEWSAJouQ,2016
+catalogkit/query/relations.py,sha256=1egUNMsikbRWJf5WX7SO_QLXBQze46z4iOvZsIAg40E,6359
+catalogkit/query/render/__init__.py,sha256=syO-eCIlCdZ1a_xkesnnpdjUQaOt9HUsutl5IAI6tDw,38
+catalogkit/query/render/json.py,sha256=V_0VJltBB88gNxdN_ykkkxMB6vHQWJrLC-eQgY-sszY,293
+catalogkit/query/render/text.py,sha256=fev3tMlo_ri8e0yk-jFKnvNx90c_z-tD3IFjIIwKbFo,1426
+catalogkit_query-0.1.0.dist-info/METADATA,sha256=z_H6V1vM0O1hehzYAM9hDnWaXk0SUGciKg9rfChOAdc,2847
+catalogkit_query-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+catalogkit_query-0.1.0.dist-info/entry_points.txt,sha256=p9fIIzi20wQMw9wVYJpS8L2w0Pl-HT07ga8MHY5joB4,63
+catalogkit_query-0.1.0.dist-info/top_level.txt,sha256=RsnUdiXrSqkJn7elbvcSi3dAxxLtc6rLuzPGHGR_44I,11
+catalogkit_query-0.1.0.dist-info/RECORD,,

catalogkit_query-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

catalogkit_query-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+catalogkit-query = catalogkit.query.cli:main

catalogkit_query-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+catalogkit