batch-analytics 0.3.22__tar.gz → 0.3.23__tar.gz

{batch_analytics-0.3.22 → batch_analytics-0.3.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: batch-analytics
-Version: 0.3.22
+Version: 0.3.23
 Summary: PySpark batch analytics: Extract, Transform, Stage, and analytical modules (linear regression, correlation, PCA, t-test).
 Author: Litewave Analytics Team
 License: MIT

{batch_analytics-0.3.22 → batch_analytics-0.3.23}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "batch-analytics"
-version = "0.3.22"
+version = "0.3.23"
 description = "PySpark batch analytics: Extract, Transform, Stage, and analytical modules (linear regression, correlation, PCA, t-test)."
 readme = "README.md"
 requires-python = ">=3.8"

{batch_analytics-0.3.22 → batch_analytics-0.3.23}/src/batch_analytics/transform.py

@@ -192,6 +192,69 @@ def _normalize_staging_write_mode(raw: str) -> str:
     return "overwrite"
 
 
+def _ch_quoted_ident(name: str) -> str:
+    """ClickHouse identifier in ORDER BY (escape backticks)."""
+    return "`" + name.replace("`", "``") + "`"
+
+
+def _ch_order_by_key_expr(col: str, df: DataFrame) -> str:
+    """
+    Build one ORDER BY key expression. Spark nullable columns map to Nullable in CH; CH 25
+    rejects nullable sort keys unless ``allow_nullable_key`` is applied — the Spark connector
+    often does not forward ``tableProperty("settings.allow_nullable_key")`` into DDL.
+
+    Using ``assumeNotNull(col)`` yields a non-nullable key expression so CREATE TABLE succeeds.
+    Only wrap when Spark marks the field nullable (``assumeNotNull`` requires Nullable input).
+    """
+    q = _ch_quoted_ident(col)
+    for f in df.schema.fields:
+        if f.name == col:
+            if f.nullable:
+                return f"assumeNotNull({q})"
+            return q
+    return q
+
+
+def _strip_outer_tuple_parens(s: str) -> str:
+    """clickhouse-spark-runtime wraps ``order_by`` in parentheses; do not also wrap here."""
+    s = s.strip()
+    if len(s) >= 2 and s[0] == "(" and s[-1] == ")":
+        return s[1:-1].strip()
+    return s
+
+
+def _merge_tree_order_by_for_staging(df: DataFrame, config: BatchAnalyticsConfig) -> str:
+    """
+    ClickHouse 25+ rejects MergeTree DDL without ORDER BY. The Spark ClickHouse catalog
+    passes this via DataFrameWriterV2.tableProperty("order_by", ...).
+
+    **Important:** The connector emits ``ORDER BY (<order_by>)``. Do **not** wrap the value
+    in an extra ``(...)`` or ClickHouse sees ``ORDER BY ((...))`` and raises a syntax error.
+
+    Resolution order:
+    1. BATCH_CLICKHOUSE_STAGING_ORDER_BY — comma-separated key expressions (no outer parens);
+       one layer of surrounding ``(...)`` is stripped if present.
+    2. BATCH_DEDUP_COLUMNS / transform.dedup_columns — comma-separated, ``assumeNotNull`` when nullable.
+    3. First column of the staging DataFrame schema (same nullable rule).
+    """
+    explicit = os.environ.get("BATCH_CLICKHOUSE_STAGING_ORDER_BY", "").strip()
+    if explicit:
+        return _strip_outer_tuple_parens(explicit)
+    dedup = (config.transform.dedup_columns or "").strip()
+    if dedup:
+        cols = [c.strip() for c in dedup.split(",") if c.strip()]
+        if cols:
+            parts = [_ch_order_by_key_expr(c, df) for c in cols]
+            return ", ".join(parts)
+    names = [f.name for f in df.schema.fields]
+    if names:
+        return _ch_order_by_key_expr(names[0], df)
+    raise ValueError(
+        "Cannot derive MergeTree ORDER BY for staging: set BATCH_CLICKHOUSE_STAGING_ORDER_BY, "
+        "or BATCH_DEDUP_COLUMNS / dedup_columns, or ensure the DataFrame has columns."
+    )
+
+
 def stage_to_clickhouse(
     spark: SparkSession,
     df: DataFrame,
@@ -210,6 +273,15 @@ def stage_to_clickhouse(
     Fallback: legacy ``format("clickhouse")`` (older stacks), then JDBC (may fail on
     ClickHouse 25+ auto-DDL without ORDER BY).
 
+    **MergeTree ORDER BY** (required on ClickHouse 25+): set ``BATCH_CLICKHOUSE_STAGING_ORDER_BY``,
+    or rely on ``BATCH_DEDUP_COLUMNS`` / ``dedup_columns`` (comma-separated keys; no extra outer parens).
+
+    **Nullable sort keys**: (1) Dedup-derived ``ORDER BY`` uses ``assumeNotNull(`col`)`` when
+    Spark marks the field nullable. (2) The Spark connector often **does not** pass
+    ``tableProperty("settings.allow_nullable_key")`` into DDL, so we also set
+    ``engine`` to ``MergeTree() SETTINGS allow_nullable_key = 1``, which ClickHouse
+    applies to the created table.
+
     Write mode from BATCH_STAGING_WRITE_MODE (default overwrite = full replace).
     """
     n = df.count()
@@ -221,12 +293,21 @@ def stage_to_clickhouse(
     if cat:
         try:
             full_name = f"{cat}.{ch.database}.{tbl}"
+            order_by = _merge_tree_order_by_for_staging(df, config)
             logger.info(
-                "Staging to ClickHouse via catalog %s (mode=%s)",
+                "Staging to ClickHouse via catalog %s (mode=%s, order_by=%s)",
                 full_name,
                 mode,
+                order_by,
+            )
+            # MergeTree SETTINGS in ENGINE: connector often ignores tableProperty("settings.*")
+            # for CREATE TABLE; CH 25 then reports allow_nullable_key disabled.
+            _mt_engine = "MergeTree() SETTINGS allow_nullable_key = 1"
+            w2 = (
+                df.writeTo(full_name)
+                .tableProperty("engine", _mt_engine)
+                .tableProperty("order_by", order_by)
             )
-            w2 = df.writeTo(full_name)
             if mode == "overwrite":
                 w2.createOrReplace()
             else:

{batch_analytics-0.3.22 → batch_analytics-0.3.23}/src/batch_analytics.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: batch-analytics
-Version: 0.3.22
+Version: 0.3.23
 Summary: PySpark batch analytics: Extract, Transform, Stage, and analytical modules (linear regression, correlation, PCA, t-test).
 Author: Litewave Analytics Team
 License: MIT