feat: add subquery support for WHERE col IN (SELECT ...)

- Parser: detect SELECT inside IN() parentheses and recursively parse
- Parser: paren-depth tracking for nested subqueries (e.g., inner IN)
- Parser: param binding skips subquery conditions (no bind param consumption)
- Executor: _resolve_subqueries() pre-executes inner queries once before filtering
- SQL_SPEC.md: document partial subquery support with constraints
- Tests: 7 new tests (parser + executor subquery scenarios)

Author: yeongseon

docs/SQL_SPEC.md

@@ -28,7 +28,7 @@ database engine.
 The following SQL features are **rejected at parse time** with `ValueError`:
 
 - `JOIN` (any variant: INNER, LEFT, RIGHT, CROSS, NATURAL)
-- Subqueries (scalar, correlated, or in FROM)
+- Subqueries except `WHERE col IN (SELECT single_col FROM table [WHERE ...])`
 - Common Table Expressions (CTEs / `WITH`)
 - `UNION` / `INTERSECT` / `EXCEPT`
 - Window functions (`OVER`, `PARTITION BY`)
@@ -299,6 +299,7 @@ DELETE FROM table [WHERE conditions]
 | `IS NULL` | `WHERE name IS NULL` | NULL check |
 | `IS NOT NULL` | `WHERE name IS NOT NULL` | Non-NULL check |
 | `IN` | `WHERE name IN ('Alice', 'Bob')` | Set membership |
+| `IN` subquery | `WHERE id IN (SELECT id FROM admins WHERE role = 'admin')` | Set membership from subquery |
 | `BETWEEN` | `WHERE score BETWEEN 70 AND 90` | Inclusive range |
 | `LIKE` | `WHERE name LIKE 'A%'` | Pattern matching |
 
@@ -316,6 +317,9 @@ Example: `WHERE name LIKE 'A%'` matches "Alice", "Ann", "A".
 - Values must be parenthesized: `IN (1, 2, 3)` or `IN ('a', 'b')`
 - Empty IN list raises `ValueError`
 - Supports placeholder binding: `IN (?, ?, ?)`
+- Supports single-column subqueries: `IN (SELECT id FROM admins)`
+- Subquery form supports optional inner WHERE: `IN (SELECT id FROM admins WHERE role = 'admin')`
+- Subquery limits: single-column SELECT only, non-correlated only, no scalar subqueries, no FROM-subqueries
 
 #### 7.2.3 BETWEEN Clause
 
@@ -334,7 +338,7 @@ Example: `WHERE name LIKE 'A%'` matches "Alice", "Ann", "A".
   - `a OR b AND c` = `a OR (b AND c)`
 - `NOT` operator is **not supported**.
 - Parenthesized expressions in WHERE (e.g., `WHERE (x = 1)`) are **not supported** 
-  and raise `ValueError`. Exception: parentheses in `IN (...)` are allowed.
+  and raise `ValueError`. Exceptions: parentheses in `IN (...)` literal lists and `IN (SELECT ...)` are allowed.
 
 ### 7.4 Type Coercion
 
@@ -454,9 +458,12 @@ where_expr    = condition { ("AND" | "OR") condition } ;
 condition     = column operator value
               | column "IS" [ "NOT" ] "NULL"
               | column "IN" "(" value_list ")"
+              | column "IN" "(" subquery_select ")"
               | column "BETWEEN" value "AND" value
               | column "LIKE" pattern ;
 
+subquery_select = "SELECT" column "FROM" table [ "WHERE" where_expr ] ;
+
 operator      = "=" | "==" | "!=" | "<>" | ">" | ">=" | "<" | "<=" ;
 direction     = "ASC" | "DESC" ;
 value         = string | number | "NULL" | "?" ;

src/excel_dbapi/executor.py

@@ -240,6 +240,7 @@ def _execute_select(
         columns = parsed["columns"]
         where = parsed.get("where")
         if where:
+            self._resolve_subqueries(where)
             rows = [row for row in rows if self._matches_where(row, where)]
 
         group_by: list[str] | None = parsed.get("group_by")
@@ -307,6 +308,13 @@ def _execute_select(
             lastrowid=None,
         )
 
+    def _resolve_subqueries(self, where: dict[str, Any]) -> None:
+        for condition in where.get("conditions", []):
+            value = condition.get("value")
+            if isinstance(value, dict) and value.get("type") == "subquery":
+                subquery_result = self.execute(value["query"])
+                condition["value"] = tuple(row[0] for row in subquery_result.rows if row)
+
     def _execute_aggregate_select(
         self,
         action: str,

src/excel_dbapi/parser.py

@@ -229,7 +229,10 @@ def _values_to_bind_from_condition(condition: Dict[str, Any]) -> List[Any]:
     if operator in {"IS", "IS NOT"}:
         return []
     if operator == "IN":
-        return list(condition["value"])
+        value = condition["value"]
+        if isinstance(value, dict) and value.get("type") == "subquery":
+            return []
+        return list(value)
     if operator == "BETWEEN":
         low, high = condition["value"]
         return [low, high]
@@ -243,7 +246,10 @@ def _apply_bound_values_to_condition(
     if operator in {"IS", "IS NOT"}:
         return 0
     if operator == "IN":
-        size = len(condition["value"])
+        value = condition["value"]
+        if isinstance(value, dict) and value.get("type") == "subquery":
+            return 0
+        size = len(value)
         condition["value"] = tuple(bound_values[offset : offset + size])
         return size
     if operator == "BETWEEN":
@@ -344,7 +350,19 @@ def _parse_where_expression(
                 raise ValueError("Invalid WHERE clause format")
             in_start = index + 2
             in_end = in_start
-            while in_end < len(tokens) and ")" not in tokens[in_end]:
+            paren_depth = 0
+            while in_end < len(tokens):
+                token = tokens[in_end]
+                if token == "(":
+                    paren_depth += 1
+                elif token == ")":
+                    if paren_depth == 0:
+                        raise ValueError(
+                            "Invalid WHERE clause format: malformed IN clause"
+                        )
+                    paren_depth -= 1
+                    if paren_depth == 0:
+                        break
                 in_end += 1
             if in_end >= len(tokens):
                 raise ValueError(
@@ -361,21 +379,32 @@ def _parse_where_expression(
                     "Invalid WHERE clause format: IN clause cannot be empty"
                 )
 
-            parsed_values = tuple(
-                _parse_value(token) for token in _split_csv(raw_values)
-            )
-            if len(parsed_values) == 0:
-                raise ValueError(
-                    "Invalid WHERE clause format: IN clause cannot be empty"
+            raw_tokens = raw_values.split()
+            if raw_tokens and raw_tokens[0].upper() == "SELECT":
+                subquery_parsed = _parse_select(raw_values, params=None)
+                conditions.append(
+                    {
+                        "column": column,
+                        "operator": "IN",
+                        "value": {"type": "subquery", "query": subquery_parsed},
+                    }
                 )
+            else:
+                parsed_values = tuple(
+                    _parse_value(token) for token in _split_csv(raw_values)
+                )
+                if len(parsed_values) == 0:
+                    raise ValueError(
+                        "Invalid WHERE clause format: IN clause cannot be empty"
+                    )
 
-            conditions.append(
-                {
-                    "column": column,
-                    "operator": "IN",
-                    "value": parsed_values,
-                }
-            )
+                conditions.append(
+                    {
+                        "column": column,
+                        "operator": "IN",
+                        "value": parsed_values,
+                    }
+                )
             index = in_end + 1
         elif operator == "LIKE":
             if index + 2 >= len(tokens):

tests/test_executor.py

@@ -62,6 +62,25 @@ def _create_users_workbook(path: Path) -> None:
     workbook.save(path)
 
 
+def _create_users_admins_workbook(path: Path) -> None:
+    workbook = Workbook()
+
+    users = workbook.active
+    assert users is not None
+    users.title = "users"
+    users.append(["id", "name"])
+    users.append([1, "Alice"])
+    users.append([2, "Bob"])
+    users.append([3, "Charlie"])
+
+    admins = workbook.create_sheet("admins")
+    admins.append(["id", "role"])
+    admins.append([1, "admin"])
+    admins.append([3, "editor"])
+
+    workbook.save(path)
+
+
 def test_executor_distinct_removes_duplicates_and_preserves_order(tmp_path: Path):
     file_path = tmp_path / "distinct_order.xlsx"
     _create_select_workbook(file_path)
@@ -305,3 +324,40 @@ def test_order_by_rejects_aggregate_with_expression_arg(tmp_path: Path):
 
     with pytest.raises(ValueError, match="Unsupported aggregate expression"):
         SharedExecutor(engine).execute(parsed)
+
+
+def test_subquery_in_where(tmp_path: Path):
+    file_path = tmp_path / "subquery_in_where.xlsx"
+    _create_users_admins_workbook(file_path)
+
+    engine = OpenpyxlBackend(str(file_path))
+    parsed = parse_sql("SELECT id, name FROM users WHERE id IN (SELECT id FROM admins)")
+    results = SharedExecutor(engine).execute(parsed)
+
+    assert results.rows == [(1, "Alice"), (3, "Charlie")]
+
+
+def test_subquery_returns_empty(tmp_path: Path):
+    file_path = tmp_path / "subquery_empty.xlsx"
+    _create_users_admins_workbook(file_path)
+
+    engine = OpenpyxlBackend(str(file_path))
+    parsed = parse_sql(
+        "SELECT id, name FROM users WHERE id IN (SELECT id FROM admins WHERE role = 'root')"
+    )
+    results = SharedExecutor(engine).execute(parsed)
+
+    assert results.rows == []
+
+
+def test_subquery_with_where(tmp_path: Path):
+    file_path = tmp_path / "subquery_with_where.xlsx"
+    _create_users_admins_workbook(file_path)
+
+    engine = OpenpyxlBackend(str(file_path))
+    parsed = parse_sql(
+        "SELECT id, name FROM users WHERE id IN (SELECT id FROM admins WHERE role = 'admin')"
+    )
+    results = SharedExecutor(engine).execute(parsed)
+
+    assert results.rows == [(1, "Alice")]

tests/test_parser.py

@@ -80,6 +80,37 @@ def test_parse_select_with_order_limit_and_conditions():
     assert parsed["where"]["conditions"][0]["operator"] == ">="
 
 
+def test_parse_subquery_in_where():
+    result = parse_sql("SELECT * FROM users WHERE id IN (SELECT id FROM admins)")
+    condition = result["where"]["conditions"][0]
+    assert condition["operator"] == "IN"
+    assert condition["value"]["type"] == "subquery"
+    assert condition["value"]["query"]["action"] == "SELECT"
+    assert condition["value"]["query"]["table"] == "admins"
+
+
+def test_parse_subquery_with_where():
+    result = parse_sql(
+        "SELECT * FROM users WHERE id IN (SELECT id FROM admins WHERE role = 'admin')"
+    )
+    subquery = result["where"]["conditions"][0]["value"]["query"]
+    assert subquery["where"] is not None
+
+
+def test_parse_subquery_with_nested_in_parentheses():
+    result = parse_sql(
+        "SELECT * FROM users WHERE id IN (SELECT id FROM admins WHERE level IN (1, 2))"
+    )
+    subquery = result["where"]["conditions"][0]["value"]["query"]
+    assert subquery["where"] is not None
+
+
+def test_parse_subquery_preserves_literal_in():
+    result = parse_sql("SELECT * FROM users WHERE id IN (1, 2, 3)")
+    condition = result["where"]["conditions"][0]
+    assert condition["value"] == (1, 2, 3)
+
+
 def test_parse_update_with_or_where():
     parsed = parse_sql("UPDATE Sheet1 SET name = 'A' WHERE id = 1 OR id = 2")
     assert parsed["where"]["conjunctions"] == ["OR"]