pytrilogy 0.3.332__tar.gz → 0.3.333__tar.gz

{pytrilogy-0.3.332 → pytrilogy-0.3.333}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytrilogy
-Version: 0.3.332
+Version: 0.3.333
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9

{pytrilogy-0.3.332 → pytrilogy-0.3.333}/trilogy/__init__.py

@@ -7,7 +7,7 @@ if TYPE_CHECKING:
     from trilogy.executor import Executor
     from trilogy.parser import parse
 
-__version__ = "0.3.332"
+__version__ = "0.3.333"
 
 __all__ = [
     "CONFIG",

{pytrilogy-0.3.332 → pytrilogy-0.3.333}/trilogy/dialect/base.py

@@ -38,6 +38,7 @@ from trilogy.core.enums import (
     FunctionClass,
     FunctionType,
     GroupMode,
+    JoinType,
     Modifier,
     Ordering,
     PersistMode,
@@ -191,8 +192,12 @@ def nullable_from_str(value: object) -> bool:
     return str(value).strip().upper() != "NO"
 
 
-def null_wrapper(lval: str, rval: str, modifiers: list[Modifier]) -> str:
-
+def null_wrapper(
+    lval: str, rval: str, modifiers: list[Modifier], jointype: JoinType | None = None
+) -> str:
+    # ``jointype`` is the join this key belongs to. The base expansion is legal
+    # under every join type and ignores it; dialects that restrict what a FULL
+    # OUTER JOIN's ON clause may contain (BigQuery) key off it.
     if Modifier.NULLABLE in modifiers:
         return f"({lval} = {rval} or ({lval} is null and {rval} is null))"
     return f"{lval} = {rval}"

{pytrilogy-0.3.332 → pytrilogy-0.3.333}/trilogy/dialect/bigquery.py

@@ -1,3 +1,4 @@
+import re
 from collections.abc import Callable, Iterable
 from typing import TYPE_CHECKING, ClassVar
 
@@ -7,6 +8,8 @@ from trilogy.constants import logger
 from trilogy.core.enums import (
     AddressType,
     FunctionType,
+    JoinType,
+    Modifier,
     UnnestMode,
 )
 from trilogy.core.models.core import (
@@ -22,6 +25,7 @@ from trilogy.dialect.base import (
     TableColumn,
     safe_quote,
 )
+from trilogy.dialect.base import null_wrapper as base_null_wrapper
 from trilogy.dialect.bigquery_engine import BigQueryConnection
 from trilogy.dialect.bigquery_staging import BigQueryPythonStaging
 
@@ -57,6 +61,47 @@ def render_geo_transform(args: list[str]) -> str:
     return f"{args[0]}"
 
 
+# A bare column reference, quoted the way every join key this module renders is
+# (`alias`.`column`, or a bare `column` when the key is the rendering branch's
+# own). Anything else -- a COALESCE over several sources, a CAST, a function --
+# is an expression as far as BigQuery's join planner is concerned.
+FIELD_REFERENCE = re.compile(r"`[^`]+`(?:\.`[^`]+`)*")
+
+
+def null_wrapper(
+    lval: str, rval: str, modifiers: list[Modifier], jointype: JoinType | None = None
+) -> str:
+    """Null-safe join key, in a shape BigQuery's FULL join planner accepts.
+
+    A FULL OUTER JOIN's ON clause must contain "an equality of fields from both
+    sides of the join". A top-level ``X = Y`` satisfies that whatever X and Y
+    are, but the base dialect's null-safe expansion
+    ``(l = r or (l is null and r is null))`` is an OR, and BigQuery only reads
+    an OR back as a join key while *both* operands are plain fields -- an
+    expression on either side is rejected, as is ``IS NOT DISTINCT FROM``. The
+    expression case is the ordinary one: a key merged across several
+    row-preserving sources renders as ``coalesce(a.x, b.x, c.x) = d.x``.
+
+    ``TO_JSON_STRING`` on both sides restores a top-level equality and is
+    null-safe for free (NULL encodes as bare ``null``, the string 'null' as
+    ``"null"``). It costs a computed hash-join key, so field-keyed joins keep
+    the cheaper expansion. Encoded FLOAT64s compare textually, so NaN matches
+    itself and ``-0.0`` stops matching ``0.0``; a float join key is
+    pathological, and the alternative is a query that does not run.
+
+    Only FULL is restricted, and only the OR form -- everything else falls
+    through to the base wrapper. Details, and the planner fixes that would make
+    this dead code, in ``docs/handoff_bigquery_full_join_merged_keys.md``.
+    """
+    if (
+        jointype is JoinType.FULL
+        and Modifier.NULLABLE in modifiers
+        and not (FIELD_REFERENCE.fullmatch(lval) and FIELD_REFERENCE.fullmatch(rval))
+    ):
+        return f"TO_JSON_STRING({lval}) = TO_JSON_STRING({rval})"
+    return base_null_wrapper(lval, rval, modifiers, jointype)
+
+
 FUNCTION_MAP = {
     FunctionType.COUNT: lambda x, types: f"count({x[0]})",
     FunctionType.SUM: lambda x, types: f"sum({x[0]})",
@@ -213,6 +258,7 @@ class BigqueryDialect(BaseDialect):
         **FUNCTION_GRAIN_MATCH_MAP,
     }
     QUOTE_CHARACTER = "`"
+    NULL_WRAPPER = staticmethod(null_wrapper)
     SQL_TEMPLATE = BQ_SQL_TEMPLATE
     CREATE_TABLE_SQL_TEMPLATE = BQ_CREATE_TABLE_SQL_TEMPLATE
     UNNEST_MODE = UnnestMode.CROSS_JOIN_UNNEST

{pytrilogy-0.3.332 → pytrilogy-0.3.333}/trilogy/dialect/common.py

@@ -20,6 +20,10 @@ from trilogy.core.models.execute import (
     _datasource_column_for_concept,
 )
 
+# Renders one join key. The join type is passed because dialects may restrict
+# what a given join's ON clause can contain (BigQuery, FULL joins).
+NullWrapper = Callable[[str, str, list[Modifier], JoinType], str]
+
 
 def render_unnest(
     unnest_mode: UnnestMode,
@@ -259,7 +263,7 @@ def _build_joinkeys(
     quote_character: str,
     render_expr_func: Callable,
     use_map: dict[str, set[str]],
-    null_wrapper: Callable[[str, str, list[Modifier]], str],
+    null_wrapper: NullWrapper,
 ) -> list[str]:
     if not join.joinkey_pairs:
         return ["1=1"]
@@ -298,6 +302,7 @@ def _build_joinkeys(
                             for pair in pairs
                             for modifier in _collect_modifiers(pair, join)
                         ],
+                        join.jointype,
                     )
                 )
                 continue
@@ -324,6 +329,7 @@ def _build_joinkeys(
                         unique_renders[0],
                         right_render,
                         _collect_modifiers(sub_pairs[0], join),
+                        join.jointype,
                     )
                 )
     return result or ["1=1"]
@@ -344,7 +350,7 @@ def render_join(
     ],
     cte: CTE,
     use_map: dict[str, set[str]],
-    null_wrapper: Callable[[str, str, list[Modifier]], str],
+    null_wrapper: NullWrapper,
     unnest_mode: UnnestMode = UnnestMode.CROSS_APPLY,
 ) -> str | None:
     if isinstance(join, InstantiatedUnnestJoin):

{pytrilogy-0.3.332 → pytrilogy-0.3.333}/trilogy/dialect/duckdb.py

@@ -22,6 +22,7 @@ from trilogy.core.enums import (
     AddressType,
     FunctionType,
     GroupMode,
+    JoinType,
     Modifier,
     UnnestMode,
 )
@@ -37,6 +38,7 @@ def null_wrapper(
     lval: str,
     rval: str,
     modifiers: list[Modifier],
+    jointype: JoinType | None = None,
 ) -> str:
 
     if Modifier.NULLABLE in modifiers:

{pytrilogy-0.3.332 → pytrilogy-0.3.333}/trilogy/dialect/mysql.py

@@ -8,6 +8,7 @@ from trilogy.core.enums import (
     CreateMode,
     DatePart,
     FunctionType,
+    JoinType,
     Modifier,
     Ordering,
 )
@@ -73,7 +74,9 @@ def render_ordering(rendered: str, order: Ordering) -> str:
     return f"{rendered} {direction}"
 
 
-def null_safe_join_key(lval: str, rval: str, modifiers: list[Modifier]) -> str:
+def null_safe_join_key(
+    lval: str, rval: str, modifiers: list[Modifier], jointype: JoinType | None = None
+) -> str:
     # `<=>` is MySQL's null-safe equality. The base dialect's OR-expansion is
     # equivalent but never index-assisted, and every lowered FULL join emits one
     # of these per key.

{pytrilogy-0.3.332 → pytrilogy-0.3.333}/trilogy/scripts/dependency/Cargo.lock

@@ -535,7 +535,7 @@ dependencies = [
 
 [[package]]
 name = "trilogy-parser"
-version = "0.3.332"
+version = "0.3.333"
 dependencies = [
  "clap",
  "pathdiff",

{pytrilogy-0.3.332 → pytrilogy-0.3.333}/trilogy/scripts/dependency/Cargo.toml

@@ -4,7 +4,7 @@ name = "trilogy-parser"
 # crates.io releases ride the same stream (see pythonpublish.yml), so a
 # published crate version always corresponds to the pytrilogy release
 # whose grammar it carries.
-version = "0.3.332"
+version = "0.3.333"
 edition = "2021"
 description = "Parser and import/datasource dependency resolver for the Trilogy language"
 license = "MIT"