Metadata-Version: 2.4
Name: kqlbridge
Version: 0.6.6
Summary: KQL → Spark SQL / T-SQL transpiler for Microsoft Fabric and Databricks
License: Apache License
        Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
           "License" shall mean the terms and conditions for use, reproduction,
           and distribution as defined by Sections 1 through 9 of this document.
        
           "Licensor" shall mean the copyright owner or entity authorized by
           the copyright owner that is granting the License.
        
           "Legal Entity" shall mean the union of the acting entity and all
           other entities that control, are controlled by, or are under common
           control with that entity.
        
           "You" (or "Your") shall mean an individual or Legal Entity
           exercising permissions granted by this License.
        
           "Source" form shall mean the preferred form for making modifications,
           including but not limited to software source code, documentation
           source, and configuration files.
        
           "Object" form shall mean any form resulting from mechanical
           transformation or translation of a Source form, including but
           not limited to compiled object code, generated documentation,
           and conversions to other media types.
        
           "Work" shall mean the work of authorship made available under
           the License.
        
           "Derivative Works" shall mean any work that is based on the Work.
        
           "Contribution" shall mean any work of authorship submitted to the Licensor.
        
           "Contributor" shall mean Licensor and any Legal Entity on behalf of
           whom a Contribution has been received by the Licensor.
        
        2. Grant of Copyright License. Subject to the terms and conditions of
           this License, each Contributor hereby grants to You a perpetual,
           worldwide, non-exclusive, no-charge, royalty-free, irrevocable
           copyright license to reproduce, prepare Derivative Works of,
           publicly display, publicly perform, sublicense, and distribute the
           Work and such Derivative Works in Source or Object form.
        
        3. Grant of Patent License. Subject to the terms and conditions of
           this License, each Contributor hereby grants to You a perpetual,
           worldwide, non-exclusive, no-charge, royalty-free, irrevocable
           patent license to make, have made, use, offer to sell, sell,
           import, and otherwise transfer the Work.
        
        4. Redistribution. You may reproduce and distribute copies of the
           Work or Derivative Works thereof in any medium, with or without
           modifications, and in Source or Object form, provided that You
           meet the following conditions:
        
           (a) You must give any other recipients of the Work or Derivative
               Works a copy of this License; and
        
           (b) You must cause any modified files to carry prominent notices
               stating that You changed the files; and
        
           (c) You must retain, in the Source form of any Derivative Works
               that You distribute, all copyright, patent, trademark, and
               attribution notices from the Source form of the Work; and
        
           (d) If the Work includes a "NOTICE" text file, include a readable
               copy of the attribution notices contained within such NOTICE file.
        
        5. Submission of Contributions. Unless You explicitly state otherwise,
           any Contribution intentionally submitted for inclusion in the Work
           shall be under the terms and conditions of this License, without any
           additional terms or conditions.
        
        6. Trademarks. This License does not grant permission to use the trade
           names, trademarks, service marks, or product names of the Licensor.
        
        7. Disclaimer of Warranty. Unless required by applicable law or
           agreed to in writing, Licensor provides the Work on an "AS IS"
           BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
        
        8. Limitation of Liability. In no event and under no legal theory
           shall any Contributor be liable for any damages arising as a result
           of this License or out of the use or inability to use the Work.
        
        9. Accepting Warranty or Additional Liability. While redistributing
           the Work or Derivative Works thereof, You may choose to offer,
           and charge a fee for, acceptance of support, warranty, indemnity,
           or other liability obligations consistent of this License.
        
        Copyright 2026 Navakanth — KQLBridge Contributors
        
Project-URL: Homepage, https://github.com/navakanth/kqlbridge
Project-URL: Repository, https://github.com/navakanth/kqlbridge
Project-URL: Issues, https://github.com/navakanth/kqlbridge/issues
Keywords: kql,kusto,spark,databricks,fabric,transpiler,sql
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lark>=1.1.9
Requires-Dist: sqlglot>=25.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

# KQLBridge

**KQL → Spark SQL / T-SQL transpiler for Microsoft Fabric and Databricks**

[![PyPI version](https://badge.fury.io/py/kqlbridge.svg)](https://badge.fury.io/py/kqlbridge)
[![Eval Score](https://img.shields.io/badge/eval-85%25-brightgreen)](tests/eval/prepare.py)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)

KQLBridge lets data engineers write queries in **Kusto Query Language (KQL)** and compile them to **Spark SQL** (Databricks, Microsoft Fabric Spark notebooks) or **T-SQL** (Fabric SQL Warehouse, Synapse Analytics).

```python
from kqlbridge import translate

kql = "AppLogs | where Level == 'Error' | summarize count() by ServiceName"
sql = translate(kql, target="spark")
# → SELECT ServiceName, COUNT(*) FROM AppLogs WHERE Level = 'Error' GROUP BY ServiceName
```

---

## Why KQLBridge?

Microsoft Fabric runs two query engines side by side: **Eventhouse** (KQL) and **Spark notebooks / SQL Warehouse** (Spark SQL / T-SQL). Teams that wrote years of KQL analytics can't simply copy-paste those queries into a Spark cell. KQLBridge automates the translation.

**Use cases:**
- Migrate ADX / Eventhouse KQL workloads to Databricks or Fabric Spark
- Build routing agents that pick the right engine per query at runtime
- Teach polyglot data engineering — learn one language, compile to all targets

---

## Installation

```bash
pip install kqlbridge
```

**Requires**: Python 3.10+, no external services, no API keys.

---

## Quick Start

### Python API

```python
from kqlbridge import translate, detect_operators, is_supported

# Translate KQL → Spark SQL (Microsoft Fabric Lakehouse / Databricks)
sql = translate(
    "AppLogs | where TimeGenerated > ago(24h) | project Message, Level",
    target="spark"
)

# Translate KQL → T-SQL (Microsoft Fabric SQL Warehouse / Synapse)
sql = translate(
    "AppLogs | where TimeGenerated > ago(24h) | project Message, Level",
    target="tsql"
)

# Check which operators are used
ops = detect_operators("AppLogs | where Level == 'Error' | summarize count() by Host")
# → ['where', 'summarize']

# Gate unsupported queries before translating
if is_supported(kql):
    sql = translate(kql)
else:
    print("Unsupported operators — keep in KQL engine")
```

### CLI

```bash
# Translate to Spark SQL (default)
kqlbridge translate "AppLogs | where Level == 'Error' | summarize count() by Host"

# Translate to T-SQL
kqlbridge translate "Events | where ts > ago(7d) | take 100" --tsql

# Check if a query is supported (exit 0 = yes, exit 1 = no — useful in CI)
kqlbridge check "AppLogs | where Level == 'Error' | join (Users) on UserId"

# List all supported operators
kqlbridge operators
```

---

## Supported Operators (v0.2)

| KQL Operator | Spark SQL Output | Status |
|---|---|---|
| `where` | `WHERE clause` | ✅ v0.1 |
| `project` | `SELECT columns` | ✅ v0.1 |
| `summarize count()` | `SELECT COUNT(*) GROUP BY` | ✅ v0.1 |
| `summarize sum/avg/min/max` | Aggregation functions | ✅ v0.1 |
| `bin(col, 1h)` | `DATE_TRUNC('hour', col)` | ✅ v0.1 |
| `ago(1h)` | `CURRENT_TIMESTAMP - INTERVAL '1 hours'` | ✅ v0.1 |
| `extend` | `SELECT *, expr AS alias` | ✅ v0.1 |
| `order by` / `sort by` | `ORDER BY col ASC/DESC` | ✅ v0.1 |
| `take` / `limit` | `LIMIT n` | ✅ v0.1 |
| `distinct` | `SELECT DISTINCT` | ✅ v0.1 |
| `join` (inner) | `INNER JOIN ON key` | ✅ v0.1 |
| `union` | `UNION ALL` | ✅ v0.1 |
| `let` variables | CTEs (`WITH … AS`) | ✅ v0.1 |
| `count()` | `COUNT(*)` scalar | ✅ v0.1 |

See [supported_operators.md](docs/supported_operators.md) for full reference.
See [unsupported_operators.md](docs/unsupported_operators.md) for operators with no SQL equivalent.

---

## Eval Score

KQLBridge measures accuracy against a **locked 100-query benchmark** (70 standard, 20 edge-case, 10 adversarial). The eval script is the single source of truth — it is never modified by the agent loop.

```bash
python tests/eval/prepare.py
# SCORE: 85.0% (85/100)
```

---

## Architecture

```
KQL input
  → Lark lexer (LOCKED grammar: kql.lark)
  → Parser (MODIFIABLE: parser.py)
  → AST nodes (LOCKED: ast_nodes.py)
  → Semantic check (LOCKED: semantic.py)
  → Generator (MODIFIABLE: generators/spark_sql.py)
  → Spark SQL / T-SQL output
```

**Locked files** (oracle, grammar, types) are never touched by the agentic build loop.
**Modifiable files** (parser, generators) are where improvements happen.

---

## Contributing

All contributions must include a corresponding test case in `tests/eval/benchmark.json`.
PRs that do not include a new test case will not be merged.

```bash
git clone https://github.com/navakanth/kqlbridge
cd kqlbridge
pip install -e ".[dev]"
python tests/eval/prepare.py  # baseline score
pytest tests/                 # unit tests
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.

---

## Companion Projects

- **PipeQL** — Pipe-first SQL syntax that compiles to the same Spark SQL target (v0.2 roadmap)
- **DE-Context Kit** — Routing agent + CDLC skill packages using KQLBridge under the hood

---

## License

Apache 2.0. See [LICENSE](LICENSE).
