Add support for scisql_s2PtInCircle spatial join

Previously spatial joins were limited to scisql_angSep constructs. This
allows queries to be expressed in equivalent scisql_s2PtInCircle form.
Previous constraints remain (coordinate pairs must come from different
table refs, but their columns must come from the same table ref, both
column pairs must be found in director tables, and the directors must
have the same partitioning).

This includes a minor refactor to split checks for the two scisql
functions into separate helper functions.

Author: malensek

src/qana/RelationGraph.cc

@@ -280,10 +280,10 @@ size_t addEqEdge(std::string const& ca, std::string const& cb, bool outer, Verte
     return 0;
 }
 
-/// `getAngSepFunc` returns a pointer to the IR node for the `scisql_angSep`
-/// call embedded in the given value expression if there is one, and null
-/// otherwise.
-FuncExpr::Ptr getAngSepFunc(ValueExprPtr const& ve) {
+/// `getFunc` returns a pointer to the IR node for the call to the function
+/// with the given name and parameter count embedded in the given value
+/// expression if there is one, and null otherwise.
+FuncExpr::Ptr getFunc(ValueExprPtr const& ve, std::string const& name, size_t numParams) {
     LOGS(_log, LOG_LVL_TRACE, __FUNCTION__);
     FuncExpr::Ptr fe;
     if (!ve || ve->getFactorOps().size() != 1) {
@@ -294,12 +294,107 @@ FuncExpr::Ptr getAngSepFunc(ValueExprPtr const& ve) {
         return fe;
     }
     fe = vf->getFuncExpr();
-    if (!fe || fe->getName() != "scisql_angSep" || fe->params.size() != 4) {
+    if (!fe || fe->getName() != name || fe->params.size() != numParams) {
         return FuncExpr::Ptr();
     }
     return fe;
 }
 
+/// Helper to retrieve a scisql_angSep function from the given value expression
+FuncExpr::Ptr getAngSepFunc(ValueExprPtr const& ve) { return getFunc(ve, "scisql_angSep", 4); }
+
+/// Helper to retrieve a scisql_s2PtInCircle function from the given value expression
+FuncExpr::Ptr getPtInCircleFunc(ValueExprPtr const& ve) { return getFunc(ve, "scisql_s2PtInCircle", 5); }
+
+/**
+ * @brief Get `scisql_angSep` call and numeric threshold in the given comparison predicate.
+ *
+ * Handles `scisql_angSep(lon1, lat1, lon2, lat2) OP threshold` in either operand order.
+ *
+ * @param cp The comparison predicate to inspect.
+ * @return std::pair<FuncExpr::Ptr, double> Embedded scisql_angSep() and the threshold it
+ *         is compared against, or {nullptr, NaN} if inadmissable.
+ * @throws QueryNotEvaluableError if the threshold is a numeric constant but is negative.
+ */
+std::pair<FuncExpr::Ptr, double> getAngSepJoin(CompPredicate const& cp) {
+    FuncExpr::Ptr fe;
+    double angSep = std::numeric_limits<double>::quiet_NaN();
+    switch (cp.op) {
+        case query::CompPredicate::LESS_THAN_OP:  // fallthrough
+        case query::CompPredicate::LESS_THAN_OR_EQUALS_OP:
+            fe = getAngSepFunc(cp.left);
+            angSep = cp.right->getNumericConst();
+            break;
+        case query::CompPredicate::GREATER_THAN_OP:  // fallthrough
+        case query::CompPredicate::GREATER_THAN_OR_EQUALS_OP:
+            angSep = cp.left->getNumericConst();
+            fe = getAngSepFunc(cp.right);
+            break;
+        case query::CompPredicate::EQUALS_OP:
+        case query::CompPredicate::NULL_SAFE_EQUALS_OP:
+        case query::CompPredicate::NOT_EQUALS_OP:
+        case query::CompPredicate::NOT_EQUALS_OP_ALT:
+            // While this doesn't make much sense numerically (floating
+            // point numbers are being tested for equality), it is
+            // technically evaluable.
+            fe = getAngSepFunc(cp.left);
+            if (!fe) {
+                angSep = cp.left->getNumericConst();
+                fe = getAngSepFunc(cp.right);
+            } else {
+                angSep = cp.right->getNumericConst();
+            }
+            break;
+        default:
+            throw QueryNotEvaluableError("Unhandled comparison operator:" + std::to_string(cp.op));
+    }
+
+    if (fe && angSep < 0.0) {
+        throw QueryNotEvaluableError(
+                "scisql_angSep() comparison threshold must be a non-negative "
+                "number, got " +
+                std::to_string(angSep));
+    }
+    return {fe, angSep};
+}
+
+/**
+ * @brief Get `scisql_s2PtInCircle` call and its radius embedded in the given comparison predicate.
+ *
+ * @param cp The comparison predicate to inspect.
+ * @return std::pair<FuncExpr::Ptr, double> Embedded scisql_s2PtInCircle() and its radius or {nullptr, NaN} if
+ *         the predicate is not admissible or the radius is not a numeric constant.
+ * @throws QueryNotEvaluableError if the radius is a numeric constant but is negative
+ */
+std::pair<FuncExpr::Ptr, double> getPtInCircleJoin(CompPredicate const& cp) {
+    auto const notFound = std::make_pair(FuncExpr::Ptr(), std::numeric_limits<double>::quiet_NaN());
+    if (cp.op != query::CompPredicate::EQUALS_OP) return notFound;
+    FuncExpr::Ptr fe = getPtInCircleFunc(cp.left);
+    double comparisonValue = std::numeric_limits<double>::quiet_NaN();
+    if (fe) {
+        comparisonValue = cp.right->getNumericConst();
+    } else {
+        fe = getPtInCircleFunc(cp.right);
+        if (!fe) {
+            return notFound;
+        }
+        comparisonValue = cp.left->getNumericConst();
+    }
+
+    if (comparisonValue != 1.0) {
+        // scisql_s2PtInCircle() only returns 0 or 1, and this is only admissable when = 1.
+        return notFound;
+    }
+
+    double const radius = fe->params.back()->getNumericConst();
+    if (radius < 0.0) {
+        throw QueryNotEvaluableError("scisql_s2PtInCircle() radius must be a non-negative number, got " +
+                                     std::to_string(radius));
+    }
+
+    return {fe, radius};
+}
+
 /// `getEqColumnRefs` returns the pair of column references in the equality
 /// predicate embedded in the given boolean factor. If that is not what
 /// the given boolean term corresponds to, a pair of nulls is returned instead.
@@ -523,6 +618,7 @@ size_t RelationGraph::_addSpEdges(BoolTerm::Ptr bt) {
         }
         return numEdges;
     }
+
     // Look for a BoolFactor containing a single CompPredicate.
     BoolFactor::Ptr bf = std::dynamic_pointer_cast<BoolFactor>(bt);
     if (!bf || bf->_terms.size() != 1) {
@@ -532,46 +628,20 @@ size_t RelationGraph::_addSpEdges(BoolTerm::Ptr bt) {
     if (!cp) {
         return 0;
     }
-    // Try to extract a scisql_angSep() call and a numeric constant
-    // from the comparison predicate.
-    FuncExpr::Ptr fe;
-    double angSep = std::numeric_limits<double>::quiet_NaN();
-    switch (cp->op) {
-        case query::CompPredicate::LESS_THAN_OP:  // fallthrough
-        case query::CompPredicate::LESS_THAN_OR_EQUALS_OP:
-            fe = getAngSepFunc(cp->left);
-            angSep = cp->right->getNumericConst();
-            break;
-        case query::CompPredicate::GREATER_THAN_OP:  // fallthrough
-        case query::CompPredicate::GREATER_THAN_OR_EQUALS_OP:
-            angSep = cp->left->getNumericConst();
-            fe = getAngSepFunc(cp->right);
-            break;
-        case query::CompPredicate::EQUALS_OP:
-        case query::CompPredicate::NULL_SAFE_EQUALS_OP:
-        case query::CompPredicate::NOT_EQUALS_OP:
-        case query::CompPredicate::NOT_EQUALS_OP_ALT:
-            // While this doesn't make much sense numerically (floating
-            // point numbers are being tested for equality), it is
-            // technically evaluable.
-            fe = getAngSepFunc(cp->left);
-            if (!fe) {
-                angSep = cp->left->getNumericConst();
-                fe = getAngSepFunc(cp->right);
-            } else {
-                angSep = cp->right->getNumericConst();
-            }
-            break;
-        default:
-            throw QueryNotEvaluableError("Unhandled comparison operator:" + std::to_string(cp->op));
-    }
+
+    // Try to extract a scisql_angSep() and numeric threshold from the comparison predicate.
+    std::pair<FuncExpr::Ptr, double> const angSepJoin = getAngSepJoin(*cp);
+
+    // If that fails, try equivalent point in circle: scisql_s2PtInCircle(lon1, lat1, lon2, lat2, radius) = 1.
+    auto const [fe, angSep] = angSepJoin.first ? angSepJoin : getPtInCircleJoin(*cp);
+
     if (!fe || boost::math::isnan(angSep)) {
-        // The scisql_angSep() call and/or numeric constant is missing,
-        // or the comparison operator is invalid (e.g.
-        // "angSep < scisql_angSep(...)")
+        // Not angSep or PtInCircle; give up
         return 0;
     }
-    // Extract column references from fe
+
+    // Extract column references from fe. Both scisql_angSep() and scisql_s2PtInCircle() take two
+    // coordinate pairs as their first four arguments.
     ValueExprPtrVector::const_iterator j = fe->params.begin();
     ColumnRef::Ptr cr[4];
     Vertex* v[4];