lexis-cli 0.4.2__py3-none-any.whl

lexis/__init__.py

@@ -0,0 +1,10 @@
+"""Lexis: Ossie-native semantic layer transpiler."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # The installed package's real version - set from the git tag at release time
+    # (see .github/workflows/publish.yml), from pyproject.toml otherwise.
+    __version__ = version("lexis-cli")
+except PackageNotFoundError:  # a source tree that was never installed
+    __version__ = "0.0.0.dev0"

lexis/_vendor/ossie/NOTICE.md

@@ -0,0 +1,14 @@
+Vendored from https://github.com/apache/ossie
+Path: python/src/ossie
+Commit: 89bb502bf8e00567c58c439f573bb869a3621a90
+License: Apache License 2.0 (c) The Apache Software Foundation
+
+This code is vendored (not installed as a dependency) because `apache-ossie`
+is not yet published to PyPI as of this writing. Once it is published,
+replace this vendored copy with a real `apache-ossie` dependency in
+pyproject.toml and delete this directory.
+
+Kept in sync with the `third_party/ossie` git submodule - after bumping it
+(`git submodule update --remote third_party/ossie`), run
+`scripts/sync_ossie_vendor.sh` to re-vendor models.py and refresh this file's
+commit pin.

lexis/_vendor/ossie/__init__.py

@@ -0,0 +1,44 @@
+"""Vendored copy of the Apache Ossie reference Python types.
+
+Source: https://github.com/apache/ossie
+        python/src/ossie (commit ddb19f1b135a61c65603f4823a3526e2fab00cf1)
+License: Apache-2.0 (c) The Apache Software Foundation
+Vendored because `apache-ossie` is not yet published to PyPI. Replace this
+package with the real dependency once it is published.
+"""
+
+from .models import (
+    OssieAIContext,
+    OssieAIContextObject,
+    OssieCustomExtension,
+    OssieDataset,
+    OssieDataType,
+    OssieDialect,
+    OssieDialectExpression,
+    OssieDimension,
+    OssieDocument,
+    OssieExpression,
+    OssieField,
+    OssieMetric,
+    OssieRelationship,
+    OssieSemanticModel,
+    OssieVendor,
+)
+
+__all__ = [
+    "OssieAIContext",
+    "OssieAIContextObject",
+    "OssieCustomExtension",
+    "OssieDataset",
+    "OssieDataType",
+    "OssieDialect",
+    "OssieDialectExpression",
+    "OssieDimension",
+    "OssieDocument",
+    "OssieExpression",
+    "OssieField",
+    "OssieMetric",
+    "OssieRelationship",
+    "OssieSemanticModel",
+    "OssieVendor",
+]

lexis/_vendor/ossie/models.py

@@ -0,0 +1,224 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from enum import Enum
+from typing import Any, Optional, Union
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class OssieDialect(str, Enum):
+    """Supported SQL and expression language dialects."""
+
+    ANSI_SQL = "ANSI_SQL"
+    SNOWFLAKE = "SNOWFLAKE"
+    MDX = "MDX"
+    MAQL = "MAQL"
+    TABLEAU = "TABLEAU"
+    DATABRICKS = "DATABRICKS"
+    BIGQUERY = "BIGQUERY"
+    THOUGHTSPOT = "THOUGHTSPOT"
+
+
+class OssieDataType(str, Enum):
+    """Portable logical data types for fields and metric results."""
+
+    STRING = "String"
+    INTEGER = "Integer"
+    DECIMAL = "Decimal"
+    FLOAT = "Float"
+    BOOLEAN = "Boolean"
+    DATE = "Date"
+    TIME = "Time"
+    DATE_TIME = "DateTime"
+    DATE_TIME_TZ = "DateTimeTz"
+    OPAQUE = "Opaque"
+
+
+_TEMPORAL_DATA_TYPES = frozenset(
+    {
+        OssieDataType.DATE,
+        OssieDataType.TIME,
+        OssieDataType.DATE_TIME,
+        OssieDataType.DATE_TIME_TZ,
+    }
+)
+
+
+class OssieVendor(str, Enum):
+    """Well-known vendor names for custom extensions."""
+
+    COMMON = "COMMON"
+    SNOWFLAKE = "SNOWFLAKE"
+    SALESFORCE = "SALESFORCE"
+    DBT = "DBT"
+    DATABRICKS = "DATABRICKS"
+    GOODDATA = "GOODDATA"
+    SEMANTIDO = "SEMANTIDO"
+    WISDOM = "WISDOM"
+
+
+class OssieAIContextObject(BaseModel):
+    """Structured AI context with instructions, synonyms, and examples."""
+
+    model_config = ConfigDict(frozen=True, extra="allow")
+
+    instructions: Optional[str] = None
+    synonyms: Optional[tuple[str, ...]] = None
+    examples: Optional[tuple[str, ...]] = None
+
+
+OssieAIContext = Union[str, OssieAIContextObject]
+
+
+class OssieCustomExtension(BaseModel):
+    """Vendor-specific metadata as a serialized JSON string."""
+
+    model_config = ConfigDict(frozen=True)
+
+    vendor_name: str
+    data: str
+
+
+class OssieDialectExpression(BaseModel):
+    """Expression in a specific dialect."""
+
+    model_config = ConfigDict(frozen=True)
+
+    dialect: OssieDialect
+    expression: str
+
+
+class OssieExpression(BaseModel):
+    """Expression definition with multi-dialect support."""
+
+    model_config = ConfigDict(frozen=True)
+
+    dialects: list[OssieDialectExpression]
+
+
+class OssieDimension(BaseModel):
+    """Dimension metadata on a field."""
+
+    model_config = ConfigDict(frozen=True)
+
+    is_time: Optional[bool] = None
+
+
+class OssieField(BaseModel):
+    """Row-level attribute for grouping, filtering, and metric expressions."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    expression: OssieExpression
+    dimension: Optional[OssieDimension] = None
+    label: Optional[str] = None
+    description: Optional[str] = None
+    datatype: Optional[OssieDataType] = None
+    ai_context: Optional[OssieAIContext] = None
+    custom_extensions: Optional[list[OssieCustomExtension]] = None
+
+    def is_time_dimension(self) -> bool:
+        """Return the field's effective temporal-dimension role.
+
+        A field must have dimension metadata to be a dimension. Within that
+        block, an explicit ``is_time`` value takes precedence; otherwise the
+        role defaults from a temporal ``datatype``.
+        """
+        if self.dimension is None:
+            return False
+        if self.dimension.is_time is not None:
+            return self.dimension.is_time
+        return self.datatype in _TEMPORAL_DATA_TYPES
+
+
+class OssieDataset(BaseModel):
+    """Logical dataset representing a business entity (fact or dimension table)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    source: str
+    primary_key: Optional[list[str]] = None
+    unique_keys: Optional[list[list[str]]] = None
+    description: Optional[str] = None
+    ai_context: Optional[OssieAIContext] = None
+    fields: Optional[list[OssieField]] = None
+    custom_extensions: Optional[list[OssieCustomExtension]] = None
+
+
+class OssieRelationship(BaseModel):
+    """Foreign key relationship between datasets."""
+
+    model_config = ConfigDict(frozen=True, populate_by_name=True)
+
+    name: str
+    from_dataset: str = Field(..., alias="from")
+    to: str
+    from_columns: list[str]
+    to_columns: list[str]
+    ai_context: Optional[OssieAIContext] = None
+    custom_extensions: Optional[list[OssieCustomExtension]] = None
+
+
+class OssieMetric(BaseModel):
+    """Quantitative measure defined on business data."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    expression: OssieExpression
+    description: Optional[str] = None
+    datatype: Optional[OssieDataType] = None
+    ai_context: Optional[OssieAIContext] = None
+    custom_extensions: Optional[list[OssieCustomExtension]] = None
+
+
+class OssieSemanticModel(BaseModel):
+    """Top-level container representing a complete semantic model."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    description: Optional[str] = None
+    ai_context: Optional[OssieAIContext] = None
+    datasets: list[OssieDataset]
+    relationships: Optional[list[OssieRelationship]] = None
+    metrics: Optional[list[OssieMetric]] = None
+    custom_extensions: Optional[list[OssieCustomExtension]] = None
+
+
+class OssieDocument(BaseModel):
+    """Root Ossie document."""
+
+    model_config = ConfigDict(frozen=True)
+
+    version: str = "0.2.0.dev0"
+    dialects: Optional[list[OssieDialect]] = None
+    vendors: Optional[list[OssieVendor]] = None
+    semantic_model: list[OssieSemanticModel]
+
+    def to_ossie_yaml(self, **kwargs: Any) -> str:
+        """Serialize to Ossie-compliant YAML (uses field aliases and excludes None values)."""
+        data = self.model_dump(by_alias=True, exclude_none=True, mode="json", **kwargs)
+        return yaml.dump(data, default_flow_style=False, sort_keys=False, allow_unicode=True)
+
+    def to_ossie_json(self, **kwargs: Any) -> str:
+        """Serialize to Ossie-compliant JSON (uses field aliases and excludes None values)."""
+        return self.model_dump_json(by_alias=True, exclude_none=True, **kwargs)

lexis/cli.py

@@ -0,0 +1,298 @@
+"""Lexis CLI: `lexis transpile <model.yaml> --target <target> ...`"""
+
+import os
+import re
+from contextlib import contextmanager
+from pathlib import Path
+
+import click
+
+from lexis.dispatch import TARGET_ALIASES, TARGETS
+from lexis.dispatch import transpile as dispatch_transpile
+from lexis.parser import load_ossie_document
+from lexis.resolved_model import ResolvedModel
+
+_SAFE_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+@click.group()
+def main() -> None:
+    """Lexis: transpile Ossie semantic models to warehouse SQL and BI/AI formats."""
+
+
+@main.command()
+@click.argument("model_path", type=click.Path(exists=True, dir_okay=False))
+@click.option("--target", type=click.Choice([*TARGETS, *TARGET_ALIASES]), required=True)
+@click.option("--metric", help="Metric name (required for SQL targets)")
+@click.option(
+    "--group-by",
+    multiple=True,
+    metavar="DATASET.FIELD",
+    help="Field to group by, e.g. item.i_category (SQL targets only, repeatable)",
+)
+@click.option(
+    "--out",
+    type=click.Path(),
+    help="Write output to a file (single-file targets) or a directory (multi-file "
+    "targets, e.g. sml) instead of stdout",
+)
+def transpile(model_path: str, target: str, metric: str | None, group_by: tuple[str, ...], out: str | None) -> None:
+    """Parse an Ossie model and emit it in the given TARGET format."""
+    document = load_ossie_document(model_path)
+    semantic_model = document.semantic_model[0]
+    model = ResolvedModel.build(semantic_model)
+
+    try:
+        result = dispatch_transpile(document, model, target, metric, list(group_by) or None)
+    except ValueError as exc:
+        raise click.UsageError(str(exc))
+
+    for warning in result.warnings:
+        click.echo(f"warning: {warning}", err=True)
+
+    if isinstance(result.content, dict):
+        if out:
+            out_dir = Path(out)
+            for filename, content in result.content.items():
+                path = out_dir / filename
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(content)
+            click.echo(f"Wrote {len(result.content)} file(s) to {out_dir}/", err=True)
+        else:
+            for filename, content in result.content.items():
+                click.echo(f"# --- {filename} ---")
+                click.echo(content)
+    elif out:
+        Path(out).write_text(result.content)
+        click.echo(f"Wrote {out}", err=True)
+    else:
+        click.echo(result.content)
+
+
+@main.group("import")
+def import_group() -> None:
+    """Import a third-party semantic model format into an Ossie document."""
+
+
+@import_group.command("sml")
+@click.argument("repo_dir", type=click.Path(exists=True, file_okay=False))
+@click.option("--out", type=click.Path(), required=True, help="Path to write the resulting Ossie YAML document")
+def import_sml(repo_dir: str, out: str) -> None:
+    """Parse an SML repo directory (REPO_DIR) into an Ossie YAML document."""
+    from lexis.sml._common import ConversionError
+    from lexis.sml.parse import parse_sml_repo
+
+    try:
+        result = parse_sml_repo(repo_dir)
+    except ConversionError as exc:
+        raise click.UsageError(str(exc))
+
+    for warning in result.warnings:
+        click.echo(f"warning: {warning}", err=True)
+
+    Path(out).write_text(result.document.to_ossie_yaml())
+    click.echo(f"Wrote {out}", err=True)
+
+
+@main.command("export-demo-dataset")
+@click.option("--out", type=click.Path(dir_okay=False), required=True, help="Path to write the .duckdb file")
+@click.option(
+    "--dataset",
+    type=click.Choice(["tpcds", "retail"]),
+    default="tpcds",
+    show_default=True,
+    help="Which bundled demo dataset to export: the small TPC-DS fixture, or the "
+    "larger retail analytics dataset (10,000 sales facts + returns)",
+)
+@click.option("--force", is_flag=True, help="Overwrite --out if it already exists")
+def export_demo_dataset_cmd(out: str, dataset: str, force: bool) -> None:
+    """Write a bundled demo dataset - the same data the web UI's "Demo dataset" run
+    mode uses - to a real .duckdb file, so it can be re-uploaded (Run tab's Upload
+    mode) or registered as a duckdb_file connection."""
+    try:
+        from lexis.demo_data import export_demo_dataset
+        from lexis.retail_demo_data import export_retail_demo_dataset
+    except ImportError as exc:
+        raise click.UsageError(
+            'exporting the demo dataset requires duckdb - install with `pip install "lexis-cli[mcp]"`'
+        ) from exc
+
+    exporter = export_retail_demo_dataset if dataset == "retail" else export_demo_dataset
+    try:
+        exporter(out, overwrite=force)
+    except FileExistsError as exc:
+        raise click.UsageError(f"{exc} (pass --force to overwrite)")
+
+    click.echo(f"Wrote {out}", err=True)
+
+
+@contextmanager
+def _demo_connection(model: ResolvedModel):
+    try:
+        from lexis.demo_data import build_tpcds_demo_connection
+        from lexis.retail_demo_data import build_retail_demo_connection
+    except ImportError as exc:
+        raise click.UsageError(
+            '--demo requires duckdb - install with `pip install "lexis-cli[mcp]"`'
+        ) from exc
+
+    # Pick the bundled demo whose fixture schema matches the model's `source`
+    # catalog. Unlike the API's `/run` endpoint (which checks demo-compatibility
+    # per request, for just the one metric being queried), we don't know which
+    # metric will be called until a tool call arrives, so we can't reject an
+    # individual incompatible metric up front - let it fail naturally with DuckDB's
+    # own "table/catalog not found" error when it's actually invoked.
+    catalogs = {ds.source.split(".", 1)[0] for ds in model.datasets.values()}
+    builder = build_retail_demo_connection if catalogs == {"retail"} else build_tpcds_demo_connection
+
+    con = builder()
+    try:
+        yield con
+    finally:
+        con.close()
+
+
+@contextmanager
+def _duckdb_file_connection(model: ResolvedModel, path: str):
+    try:
+        import duckdb
+    except ImportError as exc:
+        raise click.UsageError(
+            '--duckdb-file requires duckdb - install with `pip install "lexis-cli[mcp]"`'
+        ) from exc
+
+    catalogs = {ds.source.split(".", 1)[0] for ds in model.datasets.values()}
+    if len(catalogs) != 1:
+        raise click.UsageError(
+            "--duckdb-file requires every dataset in the model to share one catalog name "
+            f"in its `source`; found {sorted(catalogs)}"
+        )
+    catalog = catalogs.pop()
+    if not _SAFE_IDENTIFIER_RE.match(catalog):
+        raise click.UsageError(f"invalid catalog name in source: {catalog!r}")
+
+    con = duckdb.connect()
+    try:
+        con.execute(f"ATTACH '{path}' AS {catalog} (READ_ONLY)")
+        yield con
+    finally:
+        con.close()
+
+
+@contextmanager
+def _snowflake_connection(
+    account: str,
+    user: str,
+    password_env: str,
+    warehouse: str | None,
+    database: str | None,
+    schema: str | None,
+    role: str | None,
+):
+    try:
+        import snowflake.connector
+    except ImportError as exc:
+        raise click.UsageError(
+            '--snowflake-account requires snowflake-connector-python - install with '
+            '`pip install "lexis-cli[mcp]"`'
+        ) from exc
+
+    password = os.environ.get(password_env)
+    if not password:
+        raise click.UsageError(f"environment variable {password_env!r} (--snowflake-password-env) is not set")
+
+    con = snowflake.connector.connect(
+        account=account,
+        user=user,
+        password=password,
+        warehouse=warehouse,
+        database=database,
+        schema=schema,
+        role=role,
+    )
+    try:
+        yield con
+    finally:
+        con.close()
+
+
+@main.command("mcp-serve")
+@click.argument("model_path", type=click.Path(exists=True, dir_okay=False))
+@click.option("--demo", is_flag=True, help="Run against the bundled TPC-DS demo dataset")
+@click.option("--duckdb-file", type=click.Path(exists=True, dir_okay=False), help="Run against a local .duckdb file")
+@click.option("--snowflake-account", help="Run against Snowflake (requires --snowflake-user/-password-env)")
+@click.option("--snowflake-user")
+@click.option("--snowflake-password-env", help="Env var holding the Snowflake password")
+@click.option("--snowflake-warehouse")
+@click.option("--snowflake-database")
+@click.option("--snowflake-schema")
+@click.option("--snowflake-role")
+def mcp_serve(
+    model_path: str,
+    demo: bool,
+    duckdb_file: str | None,
+    snowflake_account: str | None,
+    snowflake_user: str | None,
+    snowflake_password_env: str | None,
+    snowflake_warehouse: str | None,
+    snowflake_database: str | None,
+    snowflake_schema: str | None,
+    snowflake_role: str | None,
+) -> None:
+    """Serve MODEL's metrics as live MCP tools over stdio (e.g. for Claude Desktop) -
+    one `query_<metric>` tool per metric, executed against the demo dataset, a local
+    DuckDB file, or Snowflake."""
+    try:
+        import anyio
+        from mcp.server.stdio import stdio_server
+    except ImportError as exc:
+        raise click.UsageError(
+            'mcp-serve requires the `mcp` package - install with `pip install "lexis-cli[mcp]"`'
+        ) from exc
+
+    if sum(bool(x) for x in (demo, duckdb_file, snowflake_account)) != 1:
+        raise click.UsageError("pass exactly one of --demo, --duckdb-file, or --snowflake-account")
+
+    document = load_ossie_document(model_path)
+    model = ResolvedModel.build(document.semantic_model[0])
+
+    from lexis import mcp_server as mcp_server_module
+    from lexis.transpilers.sql import DuckDBEmitter, SnowflakeEmitter
+
+    if demo:
+        con_cm, emitter = _demo_connection(model), DuckDBEmitter()
+    elif duckdb_file:
+        con_cm, emitter = _duckdb_file_connection(model, duckdb_file), DuckDBEmitter()
+    else:
+        if not (snowflake_user and snowflake_password_env):
+            raise click.UsageError("--snowflake-account requires --snowflake-user and --snowflake-password-env")
+        con_cm = _snowflake_connection(
+            snowflake_account,
+            snowflake_user,
+            snowflake_password_env,
+            snowflake_warehouse,
+            snowflake_database,
+            snowflake_schema,
+            snowflake_role,
+        )
+        emitter = SnowflakeEmitter()
+
+    with con_cm as con:
+
+        def execute(
+            metric: str,
+            group_by: list[str] | None,
+            time_grain: str | None = None,
+            time_field: str | None = None,
+        ) -> dict:
+            return mcp_server_module.run_metric_or_timeseries(
+                con, emitter, model, metric, group_by, time_grain, time_field
+            )
+
+        server = mcp_server_module.build_server(model, execute)
+
+        async def _run() -> None:
+            async with stdio_server() as (read_stream, write_stream):
+                await server.run(read_stream, write_stream, server.create_initialization_options())
+
+        anyio.run(_run)

lexis/demo_data.py

@@ -0,0 +1,87 @@
+"""Bundled TPC-DS-shaped demo dataset: small enough to build in-memory, real enough
+to exercise the join graph in `tests/fixtures/tpcds_semantic_model.yaml`. Shared by
+the CLI's `export-demo-dataset` command and lexis_api's "Demo dataset" run mode,
+so there's exactly one copy of the CREATE/INSERT statements.
+
+Requires the optional `duckdb` dependency - not one of the core `lexis` package's
+own dependencies, since the CLI's `transpile` command doesn't need it. Importing this
+module (rather than just the `lexis` package) is what opts a caller into that
+dependency; see `cli.py`'s lazy import in `export-demo-dataset`.
+"""
+
+from pathlib import Path
+
+import duckdb
+
+TPCDS_DEMO_SOURCES = {
+    "tpcds.public.store_sales",
+    "tpcds.public.customer",
+    "tpcds.public.item",
+    "tpcds.public.date_dim",
+}
+
+
+def build_tpcds_demo_connection(target: str = ":memory:") -> duckdb.DuckDBPyConnection:
+    """Attaches `target` (an in-memory database by default, or a real file path) under
+    catalog `tpcds`, so `tpcds.public.*`-sourced SQL runs against it unmodified - and
+    for a file `target`, closing the returned connection leaves that data on disk
+    (see `export_demo_dataset`, which is exactly this).
+
+    The `date_dim`/time-series rows use `ss_item_sk=12`/`ss_customer_sk=102`, which
+    deliberately don't match any `item`/`customer` row - so they're silently excluded
+    by the INNER JOINs in `test_demo_mode_matches_unit_test_result`'s Books/Electronics
+    query, and only show up for metrics that don't join those tables (e.g.
+    `total_sales`, grouped/drilled by date_dim's `d_date`).
+    """
+    con = duckdb.connect()
+    con.execute(f"ATTACH '{target}' AS tpcds")
+    con.execute("CREATE SCHEMA tpcds.public")
+    con.execute(
+        "CREATE TABLE tpcds.public.store_sales ("
+        "ss_sold_date_sk INT, ss_item_sk INT, ss_customer_sk INT, ss_store_sk INT, "
+        "ss_ext_sales_price DOUBLE, ss_net_profit DOUBLE)"
+    )
+    con.execute("CREATE TABLE tpcds.public.customer (c_customer_sk INT)")
+    con.execute(
+        "CREATE TABLE tpcds.public.item ("
+        "i_item_sk INT, i_item_id VARCHAR, i_item_desc VARCHAR, i_brand VARCHAR, "
+        "i_category VARCHAR, i_current_price DOUBLE)"
+    )
+    con.execute(
+        "CREATE TABLE tpcds.public.date_dim ("
+        "d_date_sk INT, d_date DATE, d_year INT, d_quarter_name VARCHAR, d_month_name VARCHAR)"
+    )
+    con.execute(
+        "INSERT INTO tpcds.public.store_sales VALUES "
+        "(1,10,100,1000,50.0,5.0),(1,11,101,1000,30.0,3.0),(2,10,100,1001,20.0,2.0),"
+        "(3,12,102,1000,40.0,4.0),(4,12,102,1000,60.0,6.0),(5,12,102,1000,25.0,2.5),(6,12,102,1000,35.0,3.5)"
+    )
+    con.execute("INSERT INTO tpcds.public.customer VALUES (100),(101)")
+    con.execute(
+        "INSERT INTO tpcds.public.item VALUES "
+        "(10,'ITEM-10','Wireless noise-cancelling headphones','SoundWave','Electronics',129.99),"
+        "(11,'ITEM-11','Hardcover mystery novel','Northwind Press','Books',14.99)"
+    )
+    con.execute(
+        "INSERT INTO tpcds.public.date_dim VALUES "
+        "(1,DATE '2023-01-15',2023,'2023Q1','January'),"
+        "(2,DATE '2023-04-20',2023,'2023Q2','April'),"
+        "(3,DATE '2023-07-10',2023,'2023Q3','July'),"
+        "(4,DATE '2023-10-05',2023,'2023Q4','October'),"
+        "(5,DATE '2024-01-18',2024,'2024Q1','January'),"
+        "(6,DATE '2024-04-22',2024,'2024Q2','April')"
+    )
+    return con
+
+
+def export_demo_dataset(path: str | Path, *, overwrite: bool = False) -> None:
+    """Write the demo dataset to a real .duckdb file at `path` - the same schema/rows
+    `build_tpcds_demo_connection()` builds in-memory, so the exported file can be
+    re-uploaded (the web UI's Upload run mode) or registered as a `duckdb_file`
+    connection and produce identical query results."""
+    path = Path(path)
+    if path.exists():
+        if not overwrite:
+            raise FileExistsError(f"{path} already exists")
+        path.unlink()
+    build_tpcds_demo_connection(target=str(path)).close()