duckdb-kql 0.0.1.dev1__tar.gz → 0.0.1.dev3__tar.gz

{duckdb_kql-0.0.1.dev1 → duckdb_kql-0.0.1.dev3}/CONTRIBUTING.md

@@ -24,7 +24,7 @@ Docker, DuckDB and the emulator yourself.
 Before opening a pull request:
 
 ```bash
-ruff check src tools tests
+ruff check src tools tests demo
 mypy
 pytest
 ```
@@ -87,6 +87,7 @@ report waiting to be filed against someone else's report.
 | Links in the docs resolve | Including the absolute ones the README uses for PyPI. |
 | A consumer's type checker sees real types | The package ships `py.typed`, so `Any` in a public signature is a promise broken silently. `tests/test_typing.py` checks from the outside; `mypy` alone cannot. |
 | The committed parser matches `grammar/Kql.g4` | The generated parser is committed so installs need no Java. |
+| The demo notebook still executes | `demo/` ships with its outputs, so a broken demo keeps looking authoritative. |
 
 ## The emulator
 
@@ -155,6 +156,15 @@ The whole procedure:
 1. Go to **Releases → Draft a new release**, create the tag `vX.Y.Z` on `main`,
    click **Generate release notes**, and publish.
 
+**The tag is used verbatim**, so any PEP 440 version works — `v0.2.0`,
+`v0.2.0rc1`, `v0.0.1.dev1`. This is `version_scheme = "only-version"` in
+`pyproject.toml`, and it is deliberate: `setuptools_scm`'s default invents a
+version for untagged commits by guessing the next release and appending
+`.dev<distance>`, which makes a tag that already ends in `.devN` unbuildable and
+breaks *every commit after it*. Taking the tag as written avoids the guess
+entirely; untagged builds are told apart by a local segment naming the commit
+(`0.0.1.dev1+gfe285ea`) rather than by counting commits.
+
 That is it. The release workflow builds the sdist and wheel, verifies the built
 version equals the tag, smoke-tests the wheel in a clean environment, uploads to
 PyPI via [Trusted Publishing][oidc], and attaches the artifacts to the release.

{duckdb_kql-0.0.1.dev1 → duckdb_kql-0.0.1.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: duckdb-kql
-Version: 0.0.1.dev1
+Version: 0.0.1.dev3
 Summary: Run Kusto KQL queries on DuckDB, from Python
 Project-URL: Homepage, https://github.com/mmaitre314/duckdb-kql
 Project-URL: Documentation, https://github.com/mmaitre314/duckdb-kql/blob/main/docs/getting-started.md
@@ -58,7 +58,10 @@ Provides-Extra: arrow
 Requires-Dist: pyarrow; extra == 'arrow'
 Provides-Extra: dev
 Requires-Dist: duckdb>=0.10; extra == 'dev'
+Requires-Dist: ipykernel; extra == 'dev'
 Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: nbclient; extra == 'dev'
+Requires-Dist: nbformat; extra == 'dev'
 Requires-Dist: pandas; extra == 'dev'
 Requires-Dist: pandas-stubs; extra == 'dev'
 Requires-Dist: pyarrow; extra == 'dev'
@@ -135,6 +138,20 @@ duckdb-kql queries/ -o build/sql/ --check   # fails the build if a .sql is stale
 
 See [Build-time translation](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/cli.md).
 
+## Query it from the Azure Data Explorer UI
+
+`duckdb-kql serve` puts a local Kusto REST endpoint in front of a DuckDB file,
+so Kusto's own tools can query it. Standard library only — no new dependency.
+
+```bash
+duckdb-kql serve analytics.duckdb     # http://127.0.0.1:31415
+```
+
+Open <https://dataexplorer.azure.com>, choose **Add connection**, and paste that
+URL. It listens on loopback only and cannot be told otherwise, because it
+answers unauthenticated queries: see
+[A local Kusto endpoint](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/kusto-server.md).
+
 ## Three layers
 
 | Layer | Import | Needs | For |
@@ -163,7 +180,7 @@ runs without a database.
 import duckdb_kql
 
 con = duckdb_kql.connect("analytics.duckdb")   # duckdb.connect + TimeZone=UTC
-rel = duckdb_kql.sql(con, "StormEvents | summarize n = count() by State")
+rel = duckdb_kql.kql(con, "StormEvents | summarize n = count() by State")
 rel.fetchall()
 ```
 
@@ -198,7 +215,7 @@ values; they are bound as values, so the generated SQL contains no
 caller-controlled text at all.
 
 ```python
-duckdb_kql.sql(con, """
+duckdb_kql.kql(con, """
     declare query_parameters(state:string);
     StormEvents | where State == state
 """, {"state": user_input})     # safe whatever user_input contains
@@ -212,7 +229,7 @@ Measured against the real KQL engine (the Kusto Emulator), not asserted.
 |---|---|
 | Doc-corpus cases matching ground truth | **245** of 1036 (0 mismatches) |
 | [Azure Monitor's published KQL subset](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/azure-monitor-profile.md) | **114 / 119 (96%)** |
-| Tabular operators | **15 / 41** |
+| Tabular operators | **16 / 41** |
 | Scalar functions / aggregates / binary operators | **110 / 19 / 33** |
 
 Supported operators: `where`, `project`, `project-away`, `project-rename`,
@@ -245,6 +262,7 @@ approximation.
 | [Getting started](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/getting-started.md) | Install, first query, the three layers |
 | [**KQL support matrix**](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/kql-support.md) | Every operator and function, supported or not, each with its gotchas |
 | [Build-time CLI](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/cli.md) | Translating `.kql` to `.sql` in CI, to avoid a runtime dependency |
+| [Local Kusto endpoint](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/kusto-server.md) | `duckdb-kql serve` — query a DuckDB file from the Azure Data Explorer UI |
 | [API reference](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/api.md) | Every public function and type |
 | [Kusto SDK compatibility](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/kusto-client.md) | What Layer 2 implements, no-ops, and refuses |
 | [Azure Monitor profile](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/azure-monitor-profile.md) | Coverage against a published KQL subset |
@@ -256,6 +274,7 @@ approximation.
 | [`docs/m0-grammar-spike.md`](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/m0-grammar-spike.md) | Grammar viability result |
 | [`docs/frequency-scan-results.md`](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/frequency-scan-results.md) | What KQL constructs actually get used |
 | [`docs/licensing.md`](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/licensing.md) | Third-party licensing review |
+| [demo/](https://github.com/mmaitre314/duckdb-kql/blob/main/demo/demo.ipynb) | Notebook tour of all three layers, with outputs |
 | [CONTRIBUTING.md](https://github.com/mmaitre314/duckdb-kql/blob/main/CONTRIBUTING.md) | How to add a mapping, and when not to |
 | [SECURITY.md](https://github.com/mmaitre314/duckdb-kql/blob/main/SECURITY.md) | Reporting vulnerabilities; what is in scope |
 | [Releases](https://github.com/mmaitre314/duckdb-kql/releases) | What changed, and when |

{duckdb_kql-0.0.1.dev1 → duckdb_kql-0.0.1.dev3}/README.md

@@ -57,6 +57,20 @@ duckdb-kql queries/ -o build/sql/ --check   # fails the build if a .sql is stale
 
 See [Build-time translation](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/cli.md).
 
+## Query it from the Azure Data Explorer UI
+
+`duckdb-kql serve` puts a local Kusto REST endpoint in front of a DuckDB file,
+so Kusto's own tools can query it. Standard library only — no new dependency.
+
+```bash
+duckdb-kql serve analytics.duckdb     # http://127.0.0.1:31415
+```
+
+Open <https://dataexplorer.azure.com>, choose **Add connection**, and paste that
+URL. It listens on loopback only and cannot be told otherwise, because it
+answers unauthenticated queries: see
+[A local Kusto endpoint](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/kusto-server.md).
+
 ## Three layers
 
 | Layer | Import | Needs | For |
@@ -85,7 +99,7 @@ runs without a database.
 import duckdb_kql
 
 con = duckdb_kql.connect("analytics.duckdb")   # duckdb.connect + TimeZone=UTC
-rel = duckdb_kql.sql(con, "StormEvents | summarize n = count() by State")
+rel = duckdb_kql.kql(con, "StormEvents | summarize n = count() by State")
 rel.fetchall()
 ```
 
@@ -120,7 +134,7 @@ values; they are bound as values, so the generated SQL contains no
 caller-controlled text at all.
 
 ```python
-duckdb_kql.sql(con, """
+duckdb_kql.kql(con, """
     declare query_parameters(state:string);
     StormEvents | where State == state
 """, {"state": user_input})     # safe whatever user_input contains
@@ -134,7 +148,7 @@ Measured against the real KQL engine (the Kusto Emulator), not asserted.
 |---|---|
 | Doc-corpus cases matching ground truth | **245** of 1036 (0 mismatches) |
 | [Azure Monitor's published KQL subset](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/azure-monitor-profile.md) | **114 / 119 (96%)** |
-| Tabular operators | **15 / 41** |
+| Tabular operators | **16 / 41** |
 | Scalar functions / aggregates / binary operators | **110 / 19 / 33** |
 
 Supported operators: `where`, `project`, `project-away`, `project-rename`,
@@ -167,6 +181,7 @@ approximation.
 | [Getting started](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/getting-started.md) | Install, first query, the three layers |
 | [**KQL support matrix**](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/kql-support.md) | Every operator and function, supported or not, each with its gotchas |
 | [Build-time CLI](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/cli.md) | Translating `.kql` to `.sql` in CI, to avoid a runtime dependency |
+| [Local Kusto endpoint](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/kusto-server.md) | `duckdb-kql serve` — query a DuckDB file from the Azure Data Explorer UI |
 | [API reference](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/api.md) | Every public function and type |
 | [Kusto SDK compatibility](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/kusto-client.md) | What Layer 2 implements, no-ops, and refuses |
 | [Azure Monitor profile](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/azure-monitor-profile.md) | Coverage against a published KQL subset |
@@ -178,6 +193,7 @@ approximation.
 | [`docs/m0-grammar-spike.md`](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/m0-grammar-spike.md) | Grammar viability result |
 | [`docs/frequency-scan-results.md`](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/frequency-scan-results.md) | What KQL constructs actually get used |
 | [`docs/licensing.md`](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/licensing.md) | Third-party licensing review |
+| [demo/](https://github.com/mmaitre314/duckdb-kql/blob/main/demo/demo.ipynb) | Notebook tour of all three layers, with outputs |
 | [CONTRIBUTING.md](https://github.com/mmaitre314/duckdb-kql/blob/main/CONTRIBUTING.md) | How to add a mapping, and when not to |
 | [SECURITY.md](https://github.com/mmaitre314/duckdb-kql/blob/main/SECURITY.md) | Reporting vulnerabilities; what is in scope |
 | [Releases](https://github.com/mmaitre314/duckdb-kql/releases) | What changed, and when |

duckdb_kql-0.0.1.dev3/demo/demo.ipynb

@@ -0,0 +1,503 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "915bc73e",
+   "metadata": {},
+   "source": [
+    "# duckdb-kql — run KQL queries on DuckDB\n",
+    "\n",
+    "[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/mmaitre314/duckdb-kql?devcontainer_path=.devcontainer%2Fdemo%2Fdevcontainer.json&quickstart=1)\n",
+    "\n",
+    "[`duckdb-kql`](https://github.com/mmaitre314/duckdb-kql) translates\n",
+    "[Kusto Query Language](https://learn.microsoft.com/azure/data-explorer/kusto/query/) (KQL)\n",
+    "into [DuckDB](https://duckdb.org/) SQL, so you can run KQL against local files and in-process data with\n",
+    "no cluster and no network.\n",
+    "\n",
+    "To get started, either open the GitHub Codespace above or install Python followed by `pip install duckdb-kql[all]`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "0a703ebc",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-14T00:22:04.749501Z",
+     "iopub.status.busy": "2026-08-14T00:22:04.749303Z",
+     "iopub.status.idle": "2026-08-14T00:22:04.811776Z",
+     "shell.execute_reply": "2026-08-14T00:22:04.810477Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "duckdb-kql 0.0.1.dev2\n"
+     ]
+    }
+   ],
+   "source": [
+    "import duckdb_kql\n",
+    "\n",
+    "print(\"duckdb-kql\", duckdb_kql.__version__)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "adbf3927",
+   "metadata": {},
+   "source": [
+    "## Sample data\n",
+    "\n",
+    "Connect to an in-memory instance of DuckDB and populate a sample table `Requests`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "9e490c5b",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-14T00:22:04.813929Z",
+     "iopub.status.busy": "2026-08-14T00:22:04.813705Z",
+     "iopub.status.idle": "2026-08-14T00:22:06.117089Z",
+     "shell.execute_reply": "2026-08-14T00:22:06.115877Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{'Requests': ['Timestamp', 'Service', 'Region', 'Status', 'LatencyMs', 'UserId']}\n"
+     ]
+    }
+   ],
+   "source": [
+    "import random\n",
+    "from datetime import datetime, timedelta\n",
+    "\n",
+    "con = duckdb_kql.connect()\n",
+    "\n",
+    "start = datetime(2026, 3, 1)\n",
+    "\n",
+    "rows = []\n",
+    "for i in range(2_000):\n",
+    "    service = random.choice([\"checkout\", \"search\", \"auth\", \"catalog\"])\n",
+    "    status = random.choice([200, 200, 200, 500] if service == \"auth\" else [200, 200, 200, 200, 503])\n",
+    "    rows.append((\n",
+    "        start + timedelta(seconds=i * 37),\n",
+    "        service,\n",
+    "        random.choice([\"us-west-2\", \"us-east-1\", \"eu-west-1\"]),\n",
+    "        status,\n",
+    "        round(random.lognormvariate(3.2, 0.6), 1),\n",
+    "        f\"user-{random.randint(1, 120):03d}\",\n",
+    "    ))\n",
+    "\n",
+    "con.execute(\"\"\"\n",
+    "    CREATE TABLE Requests (\n",
+    "        Timestamp TIMESTAMP, Service VARCHAR, Region VARCHAR,\n",
+    "        Status INTEGER, LatencyMs DOUBLE, UserId VARCHAR\n",
+    "    )\n",
+    "\"\"\")\n",
+    "con.executemany(\"INSERT INTO Requests VALUES (?, ?, ?, ?, ?, ?)\", rows)\n",
+    "\n",
+    "print(duckdb_kql.engine.schema(con))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f570c3d5",
+   "metadata": {},
+   "source": [
+    "## Basic query"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3a08280a",
+   "metadata": {},
+   "source": [
+    "Run a simple query."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "885b458a",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-14T00:22:06.119481Z",
+     "iopub.status.busy": "2026-08-14T00:22:06.119136Z",
+     "iopub.status.idle": "2026-08-14T00:22:06.588029Z",
+     "shell.execute_reply": "2026-08-14T00:22:06.586666Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "┌──────────┬───────────┬──────────┬───────┐\n",
+       "│ Service  │  Region   │ Failures │ Users │\n",
+       "│ varchar  │  varchar  │  int64   │ int64 │\n",
+       "├──────────┼───────────┼──────────┼───────┤\n",
+       "│ auth     │ us-east-1 │       60 │    47 │\n",
+       "│ auth     │ us-west-2 │       41 │    34 │\n",
+       "│ search   │ us-west-2 │       40 │    34 │\n",
+       "│ checkout │ us-west-2 │       39 │    36 │\n",
+       "│ auth     │ eu-west-1 │       36 │    31 │\n",
+       "└──────────┴───────────┴──────────┴───────┘"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "duckdb_kql.kql(con, \"\"\"\n",
+    "    Requests\n",
+    "    | where Status >= 500\n",
+    "    | summarize Failures = count(), Users = dcount(UserId) by Service, Region\n",
+    "    | sort by Failures desc\n",
+    "    | take 5\n",
+    "\"\"\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fd37be76",
+   "metadata": {},
+   "source": [
+    "## Query with parameters"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "91860b14",
+   "metadata": {},
+   "source": [
+    "Run a query with parameters (preventing query injection)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "ec5d5b75",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-14T00:22:06.590536Z",
+     "iopub.status.busy": "2026-08-14T00:22:06.590303Z",
+     "iopub.status.idle": "2026-08-14T00:22:06.624113Z",
+     "shell.execute_reply": "2026-08-14T00:22:06.622769Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "┌───────┐\n",
+       "│ Count │\n",
+       "│ int64 │\n",
+       "├───────┤\n",
+       "│   137 │\n",
+       "└───────┘"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "duckdb_kql.kql(con, \"\"\"\n",
+    "    declare query_parameters(service:string, floor:long);\n",
+    "    \n",
+    "    Requests\n",
+    "    | where Service == service and Status >= floor\n",
+    "    | count\n",
+    "\"\"\",\n",
+    "    {\"service\": \"auth\", \"floor\": 500})"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0a9d90b5",
+   "metadata": {},
+   "source": [
+    "## KustoClient-compatible query\n",
+    "\n",
+    "Run a query using APIs compatible with Kusto client SDK ([azure-kusto-data](https://github.com/Azure/azure-kusto-python)). Useful to unit-test code with KQL queries meant to run against actual Kusto clusters."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "f0323551",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-14T00:22:06.626383Z",
+     "iopub.status.busy": "2026-08-14T00:22:06.626164Z",
+     "iopub.status.idle": "2026-08-14T00:22:06.657424Z",
+     "shell.execute_reply": "2026-08-14T00:22:06.656176Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "columns  : [('Service', 'string'), ('Errors', 'long')]\n",
+      "raw_rows : [['auth', 137], ['search', 100], ['catalog', 98], ['checkout', 96]]\n",
+      "\n"
+     ]
+    },
+    {
+     "data": {
+      "text/html": [
+       "<div>\n",
+       "<style scoped>\n",
+       "    .dataframe tbody tr th:only-of-type {\n",
+       "        vertical-align: middle;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe tbody tr th {\n",
+       "        vertical-align: top;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe thead th {\n",
+       "        text-align: right;\n",
+       "    }\n",
+       "</style>\n",
+       "<table border=\"1\" class=\"dataframe\">\n",
+       "  <thead>\n",
+       "    <tr style=\"text-align: right;\">\n",
+       "      <th></th>\n",
+       "      <th>Service</th>\n",
+       "      <th>Errors</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>auth</td>\n",
+       "      <td>137</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1</th>\n",
+       "      <td>search</td>\n",
+       "      <td>100</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>2</th>\n",
+       "      <td>catalog</td>\n",
+       "      <td>98</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>3</th>\n",
+       "      <td>checkout</td>\n",
+       "      <td>96</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "    Service  Errors\n",
+       "0      auth     137\n",
+       "1    search     100\n",
+       "2   catalog      98\n",
+       "3  checkout      96"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from duckdb_kql.kusto import KustoClient\n",
+    "from duckdb_kql.kusto.helpers import dataframe_from_result_table\n",
+    "\n",
+    "client = KustoClient(con)\n",
+    "\n",
+    "response = client.execute(\"NetDefaultDB\", \"\"\"\n",
+    "    Requests\n",
+    "    | where Status >= 500\n",
+    "    | summarize Errors = count() by Service\n",
+    "    | sort by Errors desc\n",
+    "\"\"\")\n",
+    "\n",
+    "table = response.primary_results[0]\n",
+    "print(\"columns  :\", [(c.column_name, c.column_type) for c in table.columns])\n",
+    "print(\"raw_rows :\", table.raw_rows)\n",
+    "print()\n",
+    "dataframe_from_result_table(table)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "792b4716",
+   "metadata": {},
+   "source": [
+    "## KQL query translation\n",
+    "\n",
+    "Pre-compute the SQL-equivalent query. This removes the runtime dependency on `duckdb_kql`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "edad6fb7",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-14T00:22:06.659549Z",
+     "iopub.status.busy": "2026-08-14T00:22:06.659325Z",
+     "iopub.status.idle": "2026-08-14T00:22:07.027790Z",
+     "shell.execute_reply": "2026-08-14T00:22:07.026542Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "WITH _s0 AS (SELECT * FROM \"Requests\"),\n",
+      "     _s1 AS (SELECT * FROM _s0 WHERE ((\"Status\" >= CAST(500 AS BIGINT)) AND coalesce(regexp_matches(\"Region\", '(?i)\\b' || regexp_escape('west') || '\\b'), FALSE))),\n",
+      "     _s2 AS (SELECT \"Service\" AS \"Service\", count(*) AS \"Failures\", count(DISTINCT \"UserId\") AS \"Users\" FROM _s1 GROUP BY \"Service\"),\n",
+      "     _s3 AS (SELECT * FROM _s2 ORDER BY \"Failures\" DESC NULLS LAST),\n",
+      "     _s4 AS (SELECT * FROM _s3 LIMIT 3)\n",
+      "SELECT * FROM _s4\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(duckdb_kql.to_sql(\"\"\"\n",
+    "    Requests\n",
+    "    | where Status >= 500 and Region has \"west\"\n",
+    "    | summarize Failures = count(), Users = dcount(UserId) by Service\n",
+    "    | sort by Failures desc\n",
+    "    | take 3\n",
+    "\"\"\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "58785e21",
+   "metadata": {},
+   "source": [
+    "Validate the syntax of queries."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "7754401b",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-14T00:22:07.030028Z",
+     "iopub.status.busy": "2026-08-14T00:22:07.029791Z",
+     "iopub.status.idle": "2026-08-14T00:22:07.035687Z",
+     "shell.execute_reply": "2026-08-14T00:22:07.033881Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "1:9: mismatched input '|' expecting {<EOF>, ';'}\n"
+     ]
+    }
+   ],
+   "source": [
+    "for diagnostic in duckdb_kql.validate(\"Requests | wehr Status == 500\"):\n",
+    "    print(diagnostic)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2a0aa6d2",
+   "metadata": {},
+   "source": [
+    "Translate KQL queries using the CLI, to run query translation as part of build pipelines for instance."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "ef8136f0",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-14T00:22:07.038043Z",
+     "iopub.status.busy": "2026-08-14T00:22:07.037826Z",
+     "iopub.status.idle": "2026-08-14T00:22:07.555577Z",
+     "shell.execute_reply": "2026-08-14T00:22:07.554223Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "-- Generated by duckdb-kql from demo.kql. Do not edit.\r\n",
+      "--\r\n",
+      "-- Run with TimeZone set to UTC:  SET TimeZone='UTC';\r\n",
+      "-- KQL datetimes are UTC, and DuckDB reads the session zone when casting\r\n",
+      "-- text without an offset. Without it, datetimes are silently shifted\r\n",
+      "-- rather than rejected.\r\n",
+      "\r\n",
+      "WITH _s0 AS (SELECT * FROM \"Requests\"),\r\n",
+      "     _s1 AS (SELECT * FROM _s0 WHERE (\"Status\" >= CAST(500 AS BIGINT))),\r\n",
+      "     _s2 AS (SELECT \"Service\" AS \"Service\", count(*) AS \"Errors\" FROM _s1 GROUP BY \"Service\")\r\n",
+      "SELECT * FROM _s2\r\n"
+     ]
+    }
+   ],
+   "source": [
+    "!duckdb-kql demo.kql"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fd8ed70c",
+   "metadata": {},
+   "source": [
+    "## Next steps\n",
+    "\n",
+    "Documentation:\n",
+    "- **[Getting started](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/getting-started.md)**\n",
+    "- **[API reference](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/api.md)**\n",
+    "- **[KQL support matrix](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/kql-support.md)**\n",
+    "- **[Kusto SDK compatibility](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/kusto-client.md)**\n",
+    "- **[Build-time translation](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/cli.md)**.\n",
+    "\n",
+    "Found a query that returns something different from Kusto?\n",
+    "[Open an issue](https://github.com/mmaitre314/duckdb-kql/issues)."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}