From 5c6c419d185b54c9454a658efc565ed5031d7316 Mon Sep 17 00:00:00 2001 From: zhangfengcdt Date: Fri, 12 Sep 2025 07:23:08 -0700 Subject: [PATCH 1/4] docs: Add barrier function documentation and use it in KNN join example --- docs/reference/sql-joins.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/reference/sql-joins.md b/docs/reference/sql-joins.md index 1752ba27..125b43fc 100644 --- a/docs/reference/sql-joins.md +++ b/docs/reference/sql-joins.md @@ -52,3 +52,27 @@ FROM cities AS cities_l INNER JOIN cities AS cities_r ON ST_KNN(cities_l.geometry, cities_r.geometry, 5, false) ``` + +## Optimization Barrier + +Use the `barrier` function to prevent filter pushdown and control predicate evaluation order in complex spatial joins. This function creates an optimization barrier by evaluating boolean expressions at runtime. + +### Example + +Control the evaluation order of predicates in a KNN join to ensure the spatial operation is performed before filtering. + +```sql +-- Without barrier: optimizer may push down predicates before the KNN join +SELECT * +FROM restaurants r +INNER JOIN hotels h ON ST_KNN(h.geometry, r.geometry, 3, false) +WHERE r.rating > 4.0 AND h.stars >= 3; + +-- With barrier: ensures the KNN join completes before filtering +SELECT * +FROM restaurants r +INNER JOIN hotels h ON ST_KNN(h.geometry, r.geometry, 3, false) +WHERE barrier('r_rating > 4.0 AND h_stars >= 3', + 'r_rating', r.rating, + 'h_stars', h.stars); +``` From 5f96d283245bc5bf9e66391aba204348970573d9 Mon Sep 17 00:00:00 2001 From: zhangfengcdt Date: Fri, 12 Sep 2025 07:26:41 -0700 Subject: [PATCH 2/4] update sql formats --- docs/reference/sql-joins.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/docs/reference/sql-joins.md b/docs/reference/sql-joins.md index 125b43fc..18e0fe82 100644 --- a/docs/reference/sql-joins.md +++ b/docs/reference/sql-joins.md @@ -59,20 +59,17 @@ Use the `barrier` function to prevent filter pushdown and control predicate eval ### Example -Control the evaluation order of predicates in a KNN join to ensure the spatial operation is performed before filtering. +Find the 3 nearest high-rated restaurants to luxury hotels, ensuring the KNN join completes before filtering. ```sql --- Without barrier: optimizer may push down predicates before the KNN join -SELECT * -FROM restaurants r -INNER JOIN hotels h ON ST_KNN(h.geometry, r.geometry, 3, false) -WHERE r.rating > 4.0 AND h.stars >= 3; - --- With barrier: ensures the KNN join completes before filtering -SELECT * -FROM restaurants r -INNER JOIN hotels h ON ST_KNN(h.geometry, r.geometry, 3, false) -WHERE barrier('r_rating > 4.0 AND h_stars >= 3', - 'r_rating', r.rating, - 'h_stars', h.stars); +SELECT + h.name AS hotel, + r.name AS restaurant, + r.rating +FROM hotels AS h +INNER JOIN restaurants AS r +ON ST_KNN(h.geometry, r.geometry, 3, false) +WHERE barrier('rating > 4.0 AND stars >= 4', + 'rating', r.rating, + 'stars', h.stars) ``` From ea8f16d2b3c672d5b3980c6d9a76252e6cf6e852 Mon Sep 17 00:00:00 2001 From: zhangfengcdt Date: Fri, 12 Sep 2025 07:29:15 -0700 Subject: [PATCH 3/4] added a clear syntax explanation --- docs/reference/sql-joins.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/reference/sql-joins.md b/docs/reference/sql-joins.md index 18e0fe82..2d156d10 100644 --- a/docs/reference/sql-joins.md +++ b/docs/reference/sql-joins.md @@ -57,6 +57,12 @@ ON ST_KNN(cities_l.geometry, cities_r.geometry, 5, false) Use the `barrier` function to prevent filter pushdown and control predicate evaluation order in complex spatial joins. This function creates an optimization barrier by evaluating boolean expressions at runtime. +The `barrier` function takes a boolean expression as a string, followed by pairs of variable names and their values that will be substituted into the expression: + +```sql +barrier(expression, var_name1, var_value1, var_name2, var_value2, ...) +``` + ### Example Find the 3 nearest high-rated restaurants to luxury hotels, ensuring the KNN join completes before filtering. From f6313e159f1a1079817d15ab115e6e2f73baf8cd Mon Sep 17 00:00:00 2001 From: zhangfengcdt Date: Fri, 12 Sep 2025 08:47:00 -0700 Subject: [PATCH 4/4] add details explanation for using it in knn join examples --- docs/reference/sql-joins.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/reference/sql-joins.md b/docs/reference/sql-joins.md index 2d156d10..3d437439 100644 --- a/docs/reference/sql-joins.md +++ b/docs/reference/sql-joins.md @@ -63,6 +63,11 @@ The `barrier` function takes a boolean expression as a string, followed by pairs barrier(expression, var_name1, var_value1, var_name2, var_value2, ...) ``` +The placement of filters relative to KNN joins changes the semantic meaning of the query: + +- **Filter before KNN**: First filters the data, then finds K nearest neighbors from the filtered subset. This answers "What are the K nearest high-rated restaurants?" +- **Filter after KNN**: First finds K nearest neighbors from all data, then filters those results. This answers "Of the K nearest restaurants, which ones are high-rated?" + ### Example Find the 3 nearest high-rated restaurants to luxury hotels, ensuring the KNN join completes before filtering. @@ -79,3 +84,5 @@ WHERE barrier('rating > 4.0 AND stars >= 4', 'rating', r.rating, 'stars', h.stars) ``` + +With the barrier function, this query first finds the 3 nearest restaurants to each hotel (regardless of rating), then filters to keep only those pairs where the restaurant has rating > 4.0 and the hotel has stars >= 4. Without the barrier, an optimizer might push the filters down, changing the query to first filter for high-rated restaurants and luxury hotels, then find the 3 nearest among those filtered sets.