Transpile INTERSECTS to binned equi-join in pure SQL for full-table joins — Closes #78

docs/dialect/spatial-operators.rst

@@ -99,6 +99,24 @@ Find all variants, with gene information where available:
    FROM variants v
    LEFT JOIN genes g ON v.interval INTERSECTS g.interval
 
+Deduplication Behavior
+~~~~~~~~~~~~~~~~~~~~~~
+
+Column-to-column ``INTERSECTS`` joins use a binned equi-join strategy internally: each interval is assigned to one or more fixed-width bins, and the join is performed on ``(chrom, bin)`` pairs. Because an interval that spans a bin boundary belongs to more than one bin, a single source row can match the same result row more than once. GIQL adds ``SELECT DISTINCT`` automatically to remove these duplicate rows.
+
+This deduplication is usually transparent, but it has one observable side effect: ``DISTINCT`` operates on the entire set of selected columns, so rows that are genuinely identical across every selected column will also be collapsed into one. This matters when a table contains duplicate source records with no distinguishing column.
+
+To prevent unintended deduplication, include any column that makes rows distinguishable — such as a primary key, name, or score — in the ``SELECT`` list:
+
+.. code-block:: sql
+
+   -- score distinguishes otherwise-identical rows
+   SELECT v.chrom, v.start, v.end, v.score, g.name
+   FROM variants v
+   INNER JOIN genes g ON v.interval INTERSECTS g.interval
+
+If all columns are identical across two source rows (including any unique identifier), those rows represent the same logical record and collapsing them is correct behavior.
+
 Related Operators
 ~~~~~~~~~~~~~~~~~
 

pyproject.toml

@@ -43,6 +43,7 @@ dev = [
     "pytest-cov>=4.0.0",
     "pytest>=7.0.0",
     "ruff>=0.1.0",
+    "datafusion>=52.3.0",
 ]
 docs = [
     "sphinx>=7.0",
@@ -82,6 +83,7 @@ bedtools = ">=2.31.0"
 pybedtools = ">=0.9.0"
 pytest = ">=7.0.0"
 pytest-cov = ">=4.0.0"
+datafusion = ">=43.0.0"
 duckdb = ">=1.4.0"
 pandas = ">=2.0.0"
 sqlglot = ">=20.0.0,<30"

src/giql/__init__.py

@@ -3,13 +3,15 @@
 A SQL dialect for genomic range queries.
 """
 
+from giql.constants import DEFAULT_BIN_SIZE
 from giql.table import Table
 from giql.transpile import transpile
 
 __version__ = "0.1.0"
 
 
 __all__ = [
+    "DEFAULT_BIN_SIZE",
     "Table",
     "transpile",
 ]

src/giql/constants.py

@@ -9,3 +9,6 @@
 DEFAULT_END_COL = "end"
 DEFAULT_STRAND_COL = "strand"
 DEFAULT_GENOMIC_COL = "interval"
+
+# Default bin size for INTERSECTS binned equi-join optimization
+DEFAULT_BIN_SIZE = 10_000