Metadata-Version: 2.4
Name: catalogkit-query
Version: 0.1.1
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)
