PostBOUND 0.22.0__tar.gz → 0.22.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. {postbound-0.22.0 → postbound-0.22.1}/PKG-INFO +1 -1
  2. {postbound-0.22.0 → postbound-0.22.1}/PostBOUND.egg-info/PKG-INFO +1 -1
  3. {postbound-0.22.0 → postbound-0.22.1}/PostBOUND.egg-info/SOURCES.txt +1 -0
  4. {postbound-0.22.0 → postbound-0.22.1}/postbound/duckdb/_duckdb.py +34 -4
  5. {postbound-0.22.0 → postbound-0.22.1}/postbound/qal/_formatter.py +29 -14
  6. {postbound-0.22.0 → postbound-0.22.1}/pyproject.toml +1 -1
  7. postbound-0.22.1/tests/test_duckdb.py +107 -0
  8. {postbound-0.22.0 → postbound-0.22.1}/LICENSE.txt +0 -0
  9. {postbound-0.22.0 → postbound-0.22.1}/PostBOUND.egg-info/dependency_links.txt +0 -0
  10. {postbound-0.22.0 → postbound-0.22.1}/PostBOUND.egg-info/requires.txt +0 -0
  11. {postbound-0.22.0 → postbound-0.22.1}/PostBOUND.egg-info/top_level.txt +0 -0
  12. {postbound-0.22.0 → postbound-0.22.1}/README.md +0 -0
  13. {postbound-0.22.0 → postbound-0.22.1}/postbound/__init__.py +0 -0
  14. {postbound-0.22.0 → postbound-0.22.1}/postbound/__init__.pyi +0 -0
  15. {postbound-0.22.0 → postbound-0.22.1}/postbound/_base.py +0 -0
  16. {postbound-0.22.0 → postbound-0.22.1}/postbound/_core.py +0 -0
  17. {postbound-0.22.0 → postbound-0.22.1}/postbound/_hints.py +0 -0
  18. {postbound-0.22.0 → postbound-0.22.1}/postbound/_ipython.py +0 -0
  19. {postbound-0.22.0 → postbound-0.22.1}/postbound/_pipelines.py +0 -0
  20. {postbound-0.22.0 → postbound-0.22.1}/postbound/_qep.py +0 -0
  21. {postbound-0.22.0 → postbound-0.22.1}/postbound/_stages.py +0 -0
  22. {postbound-0.22.0 → postbound-0.22.1}/postbound/bench.py +0 -0
  23. {postbound-0.22.0 → postbound-0.22.1}/postbound/db/__init__.py +0 -0
  24. {postbound-0.22.0 → postbound-0.22.1}/postbound/db/_cache.py +0 -0
  25. {postbound-0.22.0 → postbound-0.22.1}/postbound/db/_db.py +0 -0
  26. {postbound-0.22.0 → postbound-0.22.1}/postbound/db/_stats.py +0 -0
  27. {postbound-0.22.0 → postbound-0.22.1}/postbound/duckdb/__init__.py +0 -0
  28. {postbound-0.22.0 → postbound-0.22.1}/postbound/mysql.py +0 -0
  29. {postbound-0.22.0 → postbound-0.22.1}/postbound/opt/__init__.py +0 -0
  30. {postbound-0.22.0 → postbound-0.22.1}/postbound/opt/__init__.pyi +0 -0
  31. {postbound-0.22.0 → postbound-0.22.1}/postbound/opt/_cardinalities.py +0 -0
  32. {postbound-0.22.0 → postbound-0.22.1}/postbound/opt/_dynprog.py +0 -0
  33. {postbound-0.22.0 → postbound-0.22.1}/postbound/opt/_enumeration.py +0 -0
  34. {postbound-0.22.0 → postbound-0.22.1}/postbound/opt/_helpers.py +0 -0
  35. {postbound-0.22.0 → postbound-0.22.1}/postbound/opt/_native.py +0 -0
  36. {postbound-0.22.0 → postbound-0.22.1}/postbound/opt/_randomized.py +0 -0
  37. {postbound-0.22.0 → postbound-0.22.1}/postbound/parser.py +0 -0
  38. {postbound-0.22.0 → postbound-0.22.1}/postbound/postgres/__init__.py +0 -0
  39. {postbound-0.22.0 → postbound-0.22.1}/postbound/postgres/_config.py +0 -0
  40. {postbound-0.22.0 → postbound-0.22.1}/postbound/postgres/_ctl.py +0 -0
  41. {postbound-0.22.0 → postbound-0.22.1}/postbound/postgres/_explain.py +0 -0
  42. {postbound-0.22.0 → postbound-0.22.1}/postbound/postgres/_pg.py +0 -0
  43. {postbound-0.22.0 → postbound-0.22.1}/postbound/qal/__init__.py +0 -0
  44. {postbound-0.22.0 → postbound-0.22.1}/postbound/qal/_qal.py +0 -0
  45. {postbound-0.22.0 → postbound-0.22.1}/postbound/relalg.py +0 -0
  46. {postbound-0.22.0 → postbound-0.22.1}/postbound/train/__init__.py +0 -0
  47. {postbound-0.22.0 → postbound-0.22.1}/postbound/train/_train.py +0 -0
  48. {postbound-0.22.0 → postbound-0.22.1}/postbound/transform.py +0 -0
  49. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/__init__.py +0 -0
  50. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/__init__.pyi +0 -0
  51. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/_df.py +0 -0
  52. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/_errors.py +0 -0
  53. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/collections.py +0 -0
  54. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/dicts.py +0 -0
  55. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/jsonize.py +0 -0
  56. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/logging.py +0 -0
  57. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/misc.py +0 -0
  58. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/num.py +0 -0
  59. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/nx.py +0 -0
  60. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/proc.py +0 -0
  61. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/stats.py +0 -0
  62. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/system.py +0 -0
  63. {postbound-0.22.0 → postbound-0.22.1}/postbound/util/typing.py +0 -0
  64. {postbound-0.22.0 → postbound-0.22.1}/postbound/validation.py +0 -0
  65. {postbound-0.22.0 → postbound-0.22.1}/postbound/vis/__init__.py +0 -0
  66. {postbound-0.22.0 → postbound-0.22.1}/postbound/vis/__init__.pyi +0 -0
  67. {postbound-0.22.0 → postbound-0.22.1}/postbound/vis/fdl.py +0 -0
  68. {postbound-0.22.0 → postbound-0.22.1}/postbound/vis/graphs.py +0 -0
  69. {postbound-0.22.0 → postbound-0.22.1}/postbound/vis/optimizer.py +0 -0
  70. {postbound-0.22.0 → postbound-0.22.1}/postbound/vis/plots.py +0 -0
  71. {postbound-0.22.0 → postbound-0.22.1}/postbound/vis/trees.py +0 -0
  72. {postbound-0.22.0 → postbound-0.22.1}/postbound/workloads.py +0 -0
  73. {postbound-0.22.0 → postbound-0.22.1}/setup.cfg +0 -0
  74. {postbound-0.22.0 → postbound-0.22.1}/tests/test_benchmarking.py +0 -0
  75. {postbound-0.22.0 → postbound-0.22.1}/tests/test_core.py +0 -0
  76. {postbound-0.22.0 → postbound-0.22.1}/tests/test_docs.py +0 -0
  77. {postbound-0.22.0 → postbound-0.22.1}/tests/test_postgres.py +0 -0
  78. {postbound-0.22.0 → postbound-0.22.1}/tests/test_qal.py +0 -0
  79. {postbound-0.22.0 → postbound-0.22.1}/tests/test_relalg.py +0 -0
  80. {postbound-0.22.0 → postbound-0.22.1}/tests/test_util.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: PostBOUND
3
- Version: 0.22.0
3
+ Version: 0.22.1
4
4
  Summary: PostBOUND is a research framework to prototype and benchmark database query optimizers
5
5
  Author-email: Rico Bergmann <rico.bergmann1@tu-dresden.de>
6
6
  License-Expression: Apache-2.0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: PostBOUND
3
- Version: 0.22.0
3
+ Version: 0.22.1
4
4
  Summary: PostBOUND is a research framework to prototype and benchmark database query optimizers
5
5
  Author-email: Rico Bergmann <rico.bergmann1@tu-dresden.de>
6
6
  License-Expression: Apache-2.0
@@ -71,6 +71,7 @@ postbound/vis/trees.py
71
71
  tests/test_benchmarking.py
72
72
  tests/test_core.py
73
73
  tests/test_docs.py
74
+ tests/test_duckdb.py
74
75
  tests/test_postgres.py
75
76
  tests/test_qal.py
76
77
  tests/test_relalg.py
@@ -500,11 +500,41 @@ class DuckDBStatistics(StatisticsCatalog):
500
500
 
501
501
  def _bind_node_to_table(scan_node: dict, *, query: SqlQuery) -> TableReference | None:
502
502
  tables = query.tables()
503
- relname = scan_node.get("extra_info", {}).get("Table", "")
503
+ relname: str = scan_node.get("extra_info", {}).get("Table", "")
504
504
  if not relname:
505
505
  return None
506
506
 
507
- candidate_tables = [tab for tab in tables if tab.full_name == relname]
507
+ # DuckDB reports fully qualified table names in the scan node, while the query might reference just the table name
508
+ # or a schema-qualified name. We try our best to match these differences.
509
+ # The code below is pretty ugly, but works for now ¯\_(ツ)_/¯
510
+ n_comps = relname.count(".")
511
+ match n_comps:
512
+ case 0:
513
+ candidate_tables = [tab for tab in tables if tab.full_name == relname]
514
+ case 1:
515
+ schema, name = relname.split(".")
516
+ needle = TableReference(name, schema=schema)
517
+ candidate_tables = [tab for tab in tables if tab.drop_alias() == needle]
518
+ if not candidate_tables:
519
+ needle = TableReference(name)
520
+ candidate_tables = [tab for tab in tables if tab.drop_alias() == needle]
521
+ case 2:
522
+ cat, schema, name = relname.split(".")
523
+ needle = TableReference(name, schema=schema, catalog=cat)
524
+ candidate_tables = [tab for tab in tables if tab.drop_alias() == needle]
525
+ if not candidate_tables:
526
+ needle = TableReference(name, schema=schema)
527
+ candidate_tables = [tab for tab in tables if tab.drop_alias() == needle]
528
+ if not candidate_tables:
529
+ needle = TableReference(name)
530
+ candidate_tables = [tab for tab in tables if tab.drop_alias() == needle]
531
+ case _:
532
+ warnings.warn(
533
+ f"Unexpected table format '{relname}'. Only binding based on final name component", stacklevel=2
534
+ )
535
+ needle = relname.split(".")[-1]
536
+ candidate_tables = [tab for tab in tables if tab.full_name == needle]
537
+
508
538
  if not candidate_tables:
509
539
  return None
510
540
  elif len(candidate_tables) == 1:
@@ -655,7 +685,7 @@ class DuckDBOptimizer(OptimizerInterface):
655
685
 
656
686
  raw_explain = result_set[1]
657
687
  parsed = json.loads(raw_explain)
658
- return parse_duckdb_plan(parsed[0], query=query)
688
+ return parse_duckdb_plan(parsed, query=query)
659
689
 
660
690
  def parse_plan(self, plan: ResultSet, *, query: SqlQuery | None = None) -> QueryPlan | None:
661
691
  # Similar to the Postgres implementation of parse_plan(), we try to be graceful
@@ -814,7 +844,7 @@ class DuckDBHintService(HintService):
814
844
 
815
845
  def format_query(self, query: SqlQuery) -> str:
816
846
  # DuckDB uses the Postgres SQL dialect, so this part is easy..
817
- return qal.format_quick(query, flavor="postgres")
847
+ return qal.format_quick(query, flavor="duckdb")
818
848
 
819
849
  def supports_hint(self, hint: PhysicalOperator | HintType) -> bool:
820
850
  return hint in {
@@ -59,7 +59,7 @@ from ._qal import (
59
59
  DefaultIndent = 2
60
60
  """The default amount of whitespace that is used to indent specific parts of the SQL query."""
61
61
 
62
- SqlDialect = Literal["vanilla", "postgres"]
62
+ SqlDialect = Literal["vanilla", "postgres", "duckdb"]
63
63
  """The different flavors of SQL syntax that are supported by the formatter."""
64
64
 
65
65
 
@@ -156,16 +156,31 @@ class FormattingCaseExpression(CaseExpression):
156
156
 
157
157
 
158
158
  def _quick_format_explain(explain_clause: Explain, *, flavor: SqlDialect) -> list[str]:
159
- if flavor != "postgres":
160
- return [str(explain_clause)]
159
+ match flavor:
160
+ case "vanilla":
161
+ return [str(explain_clause)]
162
+
163
+ case "postgres":
164
+ options = ["SETTINGS", "SUMMARY", "VERBOSE"]
165
+ if explain_clause.analyze:
166
+ options.append("ANALYZE")
167
+ options.append("FORMAT JSON")
161
168
 
162
- options = ["SETTINGS", "SUMMARY", "VERBOSE"]
163
- if explain_clause.analyze:
164
- options.append("ANALYZE")
165
- options.append("FORMAT JSON")
169
+ args = ", ".join(options)
170
+ return [f"EXPLAIN ({args})"]
166
171
 
167
- args = ", ".join(options)
168
- return [f"EXPLAIN ({args})"]
172
+ case "duckdb":
173
+ options = []
174
+ if explain_clause.analyze:
175
+ options.append("ANALYZE")
176
+ options.append("FORMAT JSON")
177
+
178
+ args = ", ".join(options)
179
+ return [f"EXPLAIN ({args})"]
180
+
181
+ case _:
182
+ warnings.warn("Unknown SQL flavor for EXPLAIN clauses. Falling back to naive formatting", stacklevel=2)
183
+ return [str(explain_clause)]
169
184
 
170
185
 
171
186
  def _quick_format_cte(cte_clause: CommonTableExpression, *, flavor: SqlDialect) -> list[str]:
@@ -547,7 +562,7 @@ def _quick_format_limit(limit_clause: Limit, *, flavor: SqlDialect) -> list[str]
547
562
  else:
548
563
  return []
549
564
 
550
- case "postgres" if limit_clause.fetch_direction in {"first", "next"}:
565
+ case "postgres" | "duckdb" if limit_clause.fetch_direction in {"first", "next"}:
551
566
  if limit_clause.limit and limit_clause.offset:
552
567
  return [
553
568
  f"LIMIT {limit_clause.limit}",
@@ -559,7 +574,7 @@ def _quick_format_limit(limit_clause: Limit, *, flavor: SqlDialect) -> list[str]
559
574
  return [f"OFFSET {limit_clause.offset}"]
560
575
  return []
561
576
 
562
- case "postgres" if limit_clause.fetch_direction in {"prior", "last"}:
577
+ case "postgres" | "duckdb" if limit_clause.fetch_direction in {"prior", "last"}:
563
578
  warnings.warn(
564
579
  "Postgres does not support FETCH PRIOR and FETCH LAST. Falling back to naive formatting", stacklevel=2
565
580
  )
@@ -673,9 +688,9 @@ def _expression_prettifier[T: SqlExpression](
673
688
  indentation=indentation,
674
689
  )
675
690
  return (
676
- target(replaced_cast, typ, type_params=params)
677
- if flavor == "vanilla"
678
- else _PostgresCastExpression(replaced_cast, typ, type_params=params, array_type=array)
691
+ _PostgresCastExpression(replaced_cast, typ, type_params=params, array_type=array)
692
+ if flavor == "postgres"
693
+ else target(replaced_cast, typ, type_params=params)
679
694
  )
680
695
 
681
696
  case MathExpression(op, lhs, rhs):
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "PostBOUND"
7
- version = "0.22.0"
7
+ version = "0.22.1"
8
8
  authors = [{ name = "Rico Bergmann", email = "rico.bergmann1@tu-dresden.de" }]
9
9
  description = "PostBOUND is a research framework to prototype and benchmark database query optimizers"
10
10
  readme = "README.md"
@@ -0,0 +1,107 @@
1
+ """Tests for `postbound.duckdb` -- the DuckDB backend, run against a real in-memory DuckDB (via quacklab).
2
+
3
+ All tests here are tier 1 (`embedded`): they need a real DuckDB engine, but no server or database file, because
4
+ the behaviours under test are about whether DuckDB *accepts* the SQL that PostBOUND generates. A double would
5
+ share the backend's assumptions about DuckDB's dialect and could only confirm a bug, not catch it. The synthetic
6
+ schema is created per test, so nothing is downloaded or written to disk.
7
+
8
+ The pure formatting part of the EXPLAIN regression (the *duckdb* flavor of `format_quick`) is covered offline in
9
+ `tests/unit/test_qal_formatter.py`; the parsing of EXPLAIN output and the scan-to-table binding in
10
+ `tests/unit/test_duckdb.py`.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from collections.abc import Iterator
16
+ from pathlib import Path
17
+
18
+ import pytest
19
+
20
+ from postbound import ScanOperator, TableReference, parser, transform
21
+ from postbound.duckdb import DuckDBDatabase
22
+
23
+ pytestmark = pytest.mark.embedded
24
+
25
+ # -- fixtures -----------------------------------------------------------------------------------------------
26
+
27
+
28
+ def parse(sql: str):
29
+ return parser.parse_query(sql, bind_columns=False)
30
+
31
+
32
+ FILTER_QUERY = parse("SELECT * FROM r WHERE r.a = 1")
33
+
34
+
35
+ @pytest.fixture
36
+ def duckdb_instance() -> Iterator[DuckDBDatabase]:
37
+ """An in-memory DuckDB with a tiny table `r(a, b)`. The constructor does not register it on the pool."""
38
+ instance = DuckDBDatabase(Path(":memory:"))
39
+ instance.execute_query("CREATE TABLE r (a INTEGER, b INTEGER)")
40
+ instance.execute_query("INSERT INTO r VALUES (1, 10), (2, 20), (3, 30)")
41
+ yield instance
42
+ instance.close()
43
+
44
+
45
+ # -- regression tests --------------------------------------------------------------------------------------
46
+
47
+
48
+ def test_hint_service_formats_explain_queries_without_postgres_only_options(duckdb_instance: DuckDBDatabase) -> None:
49
+ """Regression guard for the v0.22.1 DuckDB EXPLAIN fix: `DuckDBHintService.format_query` used to call
50
+ `format_quick(..., flavor="postgres")`. Since v0.22.0 that flavor writes `EXPLAIN (SETTINGS, SUMMARY,
51
+ VERBOSE, FORMAT JSON)`, which DuckDB does not support, so the backend could not run any EXPLAIN query.
52
+ """
53
+ explain_query = transform.as_explain(FILTER_QUERY)
54
+
55
+ formatted = duckdb_instance.hinting().format_query(explain_query)
56
+
57
+ header = formatted.splitlines()[0]
58
+ assert header == "EXPLAIN (FORMAT JSON)"
59
+
60
+
61
+ def test_query_plan_of_a_parsed_query_runs_on_duckdb(duckdb_instance: DuckDBDatabase) -> None:
62
+ """Regression guard for the v0.22.1 DuckDB EXPLAIN fix: `DuckDBOptimizer.query_plan` wraps a `SqlQuery` in an
63
+ EXPLAIN and formats it through the hint service, which used the Postgres flavor and thereby emitted the
64
+ Postgres-only `SETTINGS`/`SUMMARY`/`VERBOSE` options. DuckDB rejected the statement (`NotImplementedException: Unimplemented explain type: settings`)
65
+ before planning even started. (Plain-string queries took a separate hand-written `EXPLAIN (FORMAT JSON)` path
66
+ and were unaffected, which is why this test passes a parsed query.)
67
+ """
68
+ plan = duckdb_instance.optimizer().query_plan(FILTER_QUERY)
69
+
70
+ assert plan.operator == ScanOperator.SequentialScan
71
+
72
+
73
+ def test_execute_query_runs_a_parsed_explain_query_on_duckdb(duckdb_instance: DuckDBDatabase) -> None:
74
+ """Regression guard for the v0.22.1 DuckDB EXPLAIN fix, on the `DuckDBDatabase.execute_query` path: it formats
75
+ every `SqlQuery` through the hint service as well, so executing an `EXPLAIN` / `EXPLAIN ANALYZE` query object
76
+ directly failed with the same `NotImplementedException` as `query_plan`.
77
+ """
78
+ explain_queries = [transform.as_explain(FILTER_QUERY), transform.as_explain_analyze(FILTER_QUERY)]
79
+
80
+ result_sets = [duckdb_instance.execute_query(query, raw=True) for query in explain_queries]
81
+
82
+ assert [result_set[0][0] for result_set in result_sets] == ["physical_plan", "analyzed_plan"]
83
+
84
+
85
+ def test_analyze_plan_returns_the_measured_plan(duckdb_instance: DuckDBDatabase) -> None:
86
+ """Regression guard for the v0.22.1 DuckDB `analyze_plan` fix: `DuckDBOptimizer.analyze_plan` passed `parsed[0]`
87
+ to `parse_duckdb_plan`, assuming the JSON *list* that plain `EXPLAIN (FORMAT JSON)` returns. With ANALYZE,
88
+ DuckDB returns a single JSON *object* (a profiling root with the plan below `children`), so indexing it with `0`
89
+ raised a `KeyError` and no query could be analyzed.
90
+ """
91
+ plan = duckdb_instance.optimizer().analyze_plan(FILTER_QUERY)
92
+
93
+ assert plan.operator == ScanOperator.SequentialScan
94
+ assert plan.actual_cardinality == 1
95
+
96
+
97
+ def test_query_plan_binds_scan_nodes_to_their_tables(duckdb_instance: DuckDBDatabase) -> None:
98
+ """Regression guard for the v0.22.1 DuckDB table-binding fix, end to end: `_bind_node_to_table` compared the
99
+ `Table` entry of a scan node with `TableReference.full_name` by plain string equality, but DuckDB reports fully
100
+ qualified names (`memory.main.r` here) while the query references just `r`. Every scan node stayed unbound, so
101
+ `query_plan` returned plans without any tables. The offline tests in `tests/unit/test_duckdb.py` pin the captured
102
+ output; this one guards against DuckDB changing the reported name format underneath them.
103
+ """
104
+ plan = duckdb_instance.optimizer().query_plan(FILTER_QUERY)
105
+
106
+ assert plan.base_table == TableReference("r")
107
+ assert plan.tables() == {TableReference("r")}
File without changes
File without changes
File without changes
File without changes
File without changes