fix: harden JOIN semantics — NULL key exclusion, type coercion, column validation, AS alias support, doc fixes

Author: yeongseon

docs/SQL_SPEC.md

@@ -112,8 +112,8 @@ SELECT [DISTINCT] columns FROM table
 #### JOIN (two tables)
 
 ```
-SELECT qualified_columns FROM table [alias]
-  [INNER] JOIN table [alias] ON condition { AND condition }
+SELECT qualified_columns FROM table [ [AS] alias ]
+  [ INNER | LEFT [OUTER] ] JOIN table [ [AS] alias ] ON condition { AND condition }
   [WHERE conditions]
   [ORDER BY qualified_column [ASC|DESC]]
   [LIMIT n]
@@ -462,7 +462,7 @@ For UPDATE with WHERE:
 | Invalid LIMIT (non-integer) | `ValueError` | `LIMIT must be an integer` |
 | INSERT into headless sheet | `ValueError` | `Cannot insert into sheet without headers` |
 | Empty IN clause | `ValueError` | `IN clause cannot be empty` |
-| Unsupported JOIN variant | `ValueError` | `RIGHT JOIN is not supported...` |
+| Unsupported JOIN variant | `ValueError` | `Unsupported SQL syntax: {type} JOIN` |
 
 ---
 
@@ -500,9 +500,9 @@ column_list   = column { "," column } ;
 value_list    = value { "," value } ;
 column_def    = column [ type_name ] ;
 assignment    = column "=" value ;
-qualified_col  = [ table_or_alias "." ] column ;
-table_ref      = table [ alias ] ;
-join_clause    = [ "INNER" | "LEFT" ] "JOIN" table_ref "ON" join_cond { "AND" join_cond } ;
+qualified_col  = table_or_alias "." column ;
+table_ref      = table [ [ "AS" ] alias ] ;
+join_clause    = [ "INNER" | "LEFT" [ "OUTER" ] ] "JOIN" table_ref "ON" join_cond { "AND" join_cond } ;
 join_cond      = qualified_col "=" qualified_col ;
 alias          = identifier ;
 

src/excel_dbapi/executor.py

@@ -308,6 +308,70 @@ def _execute_join_select(
         left_sources = {str(from_source["table"]), str(from_source["ref"])}
         on_clauses = join_spec["on"]["clauses"]
 
+        # --- Column existence validation ---
+        # Build a mapping: source_ref -> set of valid column names
+        left_ref = str(from_source["ref"])
+        left_table_name = str(from_source["table"])
+        right_ref = str(right_source["ref"])
+        right_table_name = str(right_source["table"])
+        source_headers: dict[str, set[str]] = {}
+        for src in (left_ref, left_table_name):
+            source_headers[src] = set(left_headers)
+        for src in (right_ref, right_table_name):
+            source_headers[src] = set(right_headers)
+
+        def _validate_column_ref(source: str, name: str, context: str) -> None:
+            valid = source_headers.get(source)
+            if valid is None:
+                raise ValueError(f"Unknown source reference: {source}")
+            if name not in valid:
+                raise ValueError(
+                    f"Unknown column: {source}.{name}. "
+                    f"Available columns in '{source}': {sorted(valid)}"
+                )
+
+        # Validate SELECT columns
+        for column in parsed["columns"]:
+            if isinstance(column, dict) and column.get("type") == "column":
+                _validate_column_ref(str(column["source"]), str(column["name"]), "SELECT")
+
+        # Validate ON columns
+        for clause in on_clauses:
+            for side in ("left", "right"):
+                col = clause[side]
+                _validate_column_ref(str(col["source"]), str(col["name"]), "ON")
+
+        # Validate WHERE columns
+        where_raw = parsed.get("where")
+        if where_raw:
+            for condition in where_raw.get("conditions", []):
+                col_ref = str(condition.get("column", ""))
+                if "." in col_ref:
+                    src, col_name = col_ref.split(".", 1)
+                    _validate_column_ref(src, col_name, "WHERE")
+
+        # Validate ORDER BY column
+        order_by_raw = parsed.get("order_by")
+        if order_by_raw:
+            col_ref = str(order_by_raw["column"])
+            if "." in col_ref:
+                src, col_name = col_ref.split(".", 1)
+                _validate_column_ref(src, col_name, "ORDER BY")
+
+        # Sentinel: each NULL key gets a unique object so NULL != NULL per SQL standard.
+        _null_sentinel_counter = 0
+
+        def _normalize_key_value(val: Any) -> Any:
+            """Coerce key values for consistent hash matching."""
+            if val is None:
+                nonlocal _null_sentinel_counter
+                _null_sentinel_counter += 1
+                return object()  # unique, never equals another
+            num = self._to_number(val)
+            if num is not None:
+                return num
+            return val
+
         def build_key(
             row_ns: dict[str, Any],
             is_left_side: bool,
@@ -318,7 +382,8 @@ def build_key(
                 right_col = clause["right"]
                 left_is_left = str(left_col["source"]) in left_sources
                 selected = left_col if left_is_left == is_left_side else right_col
-                key_parts.append(self._resolve_join_column(row_ns, selected))
+                raw_val = self._resolve_join_column(row_ns, selected)
+                key_parts.append(_normalize_key_value(raw_val))
             return tuple(key_parts)
 
         right_hash: dict[tuple[Any, ...], list[dict[str, Any]]] = {}

src/excel_dbapi/parser.py

@@ -683,6 +683,11 @@ def _parse_select(
     token_index = from_index + 2
     if token_index < len(tokens):
         maybe_alias = tokens[token_index]
+        if maybe_alias.upper() == "AS":
+            token_index += 1
+            if token_index >= len(tokens):
+                raise ValueError("Expected alias after AS")
+            maybe_alias = tokens[token_index]
         if not _is_reserved_select_token(maybe_alias):
             from_entry["alias"] = maybe_alias
             from_entry["ref"] = maybe_alias
@@ -724,6 +729,11 @@ def _parse_select(
             }
             if token_index < len(tokens):
                 maybe_alias = tokens[token_index]
+                if maybe_alias.upper() == "AS":
+                    token_index += 1
+                    if token_index >= len(tokens):
+                        raise ValueError("Expected alias after AS")
+                    maybe_alias = tokens[token_index]
                 if not _is_reserved_select_token(maybe_alias):
                     join_source["alias"] = maybe_alias
                     join_source["ref"] = maybe_alias

tests/test_executor.py

@@ -542,3 +542,157 @@ def test_executor_join_missing_right_sheet(tmp_path: Path):
     )
     with pytest.raises(ValueError, match="not found"):
         SharedExecutor(engine).execute(parsed)
+
+
+def test_executor_join_null_keys_do_not_match(tmp_path: Path):
+    """NULL join keys must not match per SQL standard: NULL != NULL."""
+    file_path = tmp_path / "join_null_keys.xlsx"
+    workbook = Workbook()
+    left = workbook.active
+    assert left is not None
+    left.title = "left_t"
+    left.append(["id", "name"])
+    left.append([1, "Alice"])
+    left.append([None, "Bob"])  # NULL key
+    left.append([3, "Charlie"])
+
+    right = workbook.create_sheet("right_t")
+    right.append(["id", "role"])
+    right.append([1, "admin"])
+    right.append([None, "ghost"])  # NULL key
+    right.append([3, "editor"])
+    workbook.save(file_path)
+
+    engine = OpenpyxlBackend(str(file_path))
+    # INNER JOIN: NULL keys should NOT match
+    parsed = parse_sql(
+        "SELECT a.id, a.name, b.role FROM left_t a INNER JOIN right_t b ON a.id = b.id"
+    )
+    results = SharedExecutor(engine).execute(parsed)
+    # Bob should NOT appear — NULL != NULL
+    assert results.rows == [(1, "Alice", "admin"), (3, "Charlie", "editor")]
+
+
+def test_executor_left_join_null_keys_unmatched(tmp_path: Path):
+    """LEFT JOIN with NULL keys: left row with NULL key gets NULL-filled right columns."""
+    file_path = tmp_path / "left_join_null_keys.xlsx"
+    workbook = Workbook()
+    left = workbook.active
+    assert left is not None
+    left.title = "left_t"
+    left.append(["id", "name"])
+    left.append([1, "Alice"])
+    left.append([None, "Bob"])
+
+    right = workbook.create_sheet("right_t")
+    right.append(["id", "role"])
+    right.append([1, "admin"])
+    right.append([None, "ghost"])
+    workbook.save(file_path)
+
+    engine = OpenpyxlBackend(str(file_path))
+    parsed = parse_sql(
+        "SELECT a.id, a.name, b.role FROM left_t a LEFT JOIN right_t b ON a.id = b.id"
+    )
+    results = SharedExecutor(engine).execute(parsed)
+    # Bob (NULL key) has no match → right columns are None
+    assert results.rows == [(1, "Alice", "admin"), (None, "Bob", None)]
+
+
+def test_executor_join_numeric_string_coercion(tmp_path: Path):
+    """Join key '1' (string) should match 1 (int) via numeric coercion."""
+    file_path = tmp_path / "join_coercion.xlsx"
+    workbook = Workbook()
+    left = workbook.active
+    assert left is not None
+    left.title = "left_t"
+    left.append(["id", "name"])
+    left.append(["1", "Alice"])  # string '1'
+    left.append(["2", "Bob"])
+
+    right = workbook.create_sheet("right_t")
+    right.append(["id", "role"])
+    right.append([1, "admin"])  # int 1
+    right.append([2, "editor"])
+    workbook.save(file_path)
+
+    engine = OpenpyxlBackend(str(file_path))
+    parsed = parse_sql(
+        "SELECT a.id, a.name, b.role FROM left_t a INNER JOIN right_t b ON a.id = b.id"
+    )
+    results = SharedExecutor(engine).execute(parsed)
+    assert len(results.rows) == 2
+    assert results.rows[0][1] == "Alice"
+    assert results.rows[0][2] == "admin"
+
+
+def test_executor_join_unknown_select_column(tmp_path: Path):
+    """SELECT referencing non-existent column in JOIN query raises ValueError."""
+    file_path = tmp_path / "join_bad_col.xlsx"
+    workbook = Workbook()
+    left = workbook.active
+    assert left is not None
+    left.title = "users"
+    left.append(["id", "name"])
+    left.append([1, "Alice"])
+
+    right = workbook.create_sheet("admins")
+    right.append(["id", "role"])
+    right.append([1, "admin"])
+    workbook.save(file_path)
+
+    engine = OpenpyxlBackend(str(file_path))
+    # a.nonexistent doesn't exist in users sheet
+    parsed = parse_sql(
+        "SELECT a.nonexistent FROM users a INNER JOIN admins b ON a.id = b.id"
+    )
+    with pytest.raises(ValueError, match="Unknown column"):
+        SharedExecutor(engine).execute(parsed)
+
+
+def test_executor_join_unknown_on_column(tmp_path: Path):
+    """ON referencing non-existent column raises ValueError."""
+    file_path = tmp_path / "join_bad_on.xlsx"
+    workbook = Workbook()
+    left = workbook.active
+    assert left is not None
+    left.title = "users"
+    left.append(["id", "name"])
+    left.append([1, "Alice"])
+
+    right = workbook.create_sheet("admins")
+    right.append(["id", "role"])
+    right.append([1, "admin"])
+    workbook.save(file_path)
+
+    engine = OpenpyxlBackend(str(file_path))
+    parsed = parse_sql(
+        "SELECT a.id, b.id FROM users a INNER JOIN admins b ON a.id = b.nonexistent"
+    )
+    with pytest.raises(ValueError, match="Unknown column"):
+        SharedExecutor(engine).execute(parsed)
+
+
+def test_executor_join_with_as_alias(tmp_path: Path):
+    """JOIN with AS keyword in alias (SQLAlchemy compatibility)."""
+    file_path = tmp_path / "join_as_alias.xlsx"
+    workbook = Workbook()
+    left = workbook.active
+    assert left is not None
+    left.title = "users"
+    left.append(["id", "name"])
+    left.append([1, "Alice"])
+    left.append([2, "Bob"])
+
+    right = workbook.create_sheet("admins")
+    right.append(["id", "role"])
+    right.append([1, "admin"])
+    workbook.save(file_path)
+
+    engine = OpenpyxlBackend(str(file_path))
+    # Use 'AS' keyword in both FROM and JOIN aliases
+    parsed = parse_sql(
+        "SELECT a.id, a.name, b.role FROM users AS a INNER JOIN admins AS b ON a.id = b.id"
+    )
+    results = SharedExecutor(engine).execute(parsed)
+    assert results.rows == [(1, "Alice", "admin")]

tests/test_parser.py

@@ -518,3 +518,35 @@ def test_parse_join_rejects_having():
 def test_parse_join_rejects_distinct():
     with pytest.raises(ValueError, match="DISTINCT is not supported with JOIN"):
         parse_sql("SELECT DISTINCT a.id FROM t1 a JOIN t2 b ON a.id = b.id")
+
+
+def test_parse_join_with_as_alias_from():
+    """FROM table AS alias should be accepted."""
+    result = parse_sql("SELECT a.id, b.id FROM t1 AS a JOIN t2 AS b ON a.id = b.id")
+    assert result["from"]["alias"] == "a"
+    assert result["from"]["ref"] == "a"
+    assert result["joins"][0]["source"]["alias"] == "b"
+    assert result["joins"][0]["source"]["ref"] == "b"
+
+
+def test_parse_join_with_as_alias_mixed():
+    """Mix of AS alias and bare alias should be accepted."""
+    result = parse_sql("SELECT a.id, b.id FROM t1 AS a JOIN t2 b ON a.id = b.id")
+    assert result["from"]["alias"] == "a"
+    assert result["joins"][0]["source"]["alias"] == "b"
+
+
+def test_parse_from_as_alias_single_table():
+    """FROM table AS alias without JOIN should be accepted."""
+    result = parse_sql("SELECT id FROM users AS u")
+    assert result["from"]["alias"] == "u"
+    assert result["from"]["ref"] == "u"
+
+
+def test_parse_left_outer_join_with_as():
+    """LEFT OUTER JOIN with AS alias should be accepted."""
+    result = parse_sql(
+        "SELECT a.id, b.id FROM t1 AS a LEFT OUTER JOIN t2 AS b ON a.id = b.id"
+    )
+    assert result["joins"][0]["type"] == "LEFT"
+    assert result["joins"][0]["source"]["alias"] == "b"