Skip to content

update query terminology #671

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
abnegate merged 1 commit into from
Aug 26, 2025
Merged

update query terminology #671

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/Database/Adapter/MariaDB.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1715,13 +1715,13 @@ protected function handleSpatialQueries(Query $query, array &$binds, string $att
$binds[":{$placeholder}_0"] = $this->convertArrayToWKT($query->getValues()[0]);
return "NOT ST_Crosses({$alias}.{$attribute}, ST_GeomFromText(:{$placeholder}_0))";

case Query::TYPE_DISTANCE:
case Query::TYPE_DISTANCE_EQUAL:
$distanceParams = $query->getValues()[0];
$binds[":{$placeholder}_0"] = $this->convertArrayToWKT($distanceParams[0]);
$binds[":{$placeholder}_1"] = $distanceParams[1];
return "ST_Distance({$alias}.{$attribute}, ST_GeomFromText(:{$placeholder}_0)) = :{$placeholder}_1";

case Query::TYPE_NOT_DISTANCE:
case Query::TYPE_DISTANCE_NOT_EQUAL:
$distanceParams = $query->getValues()[0];
$binds[":{$placeholder}_0"] = $this->convertArrayToWKT($distanceParams[0]);
$binds[":{$placeholder}_1"] = $distanceParams[1];
Expand Down
4 changes: 2 additions & 2 deletions src/Database/Adapter/Postgres.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1811,13 +1811,13 @@ protected function handleSpatialQueries(Query $query, array &$binds, string $att
$binds[":{$placeholder}_0"] = $this->convertArrayToWKT($query->getValues()[0]);
return "NOT ST_Crosses({$alias}.{$attribute}, ST_GeomFromText(:{$placeholder}_0))";

case Query::TYPE_DISTANCE:
case Query::TYPE_DISTANCE_EQUAL:
$distanceParams = $query->getValues()[0];
$binds[":{$placeholder}_0"] = $this->convertArrayToWKT($distanceParams[0]);
$binds[":{$placeholder}_1"] = $distanceParams[1];
return "ST_DWithin({$alias}.{$attribute}, ST_GeomFromText(:{$placeholder}_0), :{$placeholder}_1)";

case Query::TYPE_NOT_DISTANCE:
case Query::TYPE_DISTANCE_NOT_EQUAL:
$distanceParams = $query->getValues()[0];
$binds[":{$placeholder}_0"] = $this->convertArrayToWKT($distanceParams[0]);
$binds[":{$placeholder}_1"] = $distanceParams[1];
Expand Down
28 changes: 14 additions & 14 deletions src/Database/Query.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,8 @@ class Query
// General spatial method constants (for spatial-only operations)
public const TYPE_CROSSES = 'crosses';
public const TYPE_NOT_CROSSES = 'notCrosses';
public const TYPE_DISTANCE = 'distance';
public const TYPE_NOT_DISTANCE = 'notDistance';
public const TYPE_DISTANCE_EQUAL = 'distanceEqual';
public const TYPE_DISTANCE_NOT_EQUAL = 'distanceNotEqual';
public const TYPE_DISTANCE_GREATER_THAN = 'distanceGreaterThan';
public const TYPE_DISTANCE_LESS_THAN = 'distanceLessThan';
public const TYPE_INTERSECTS = 'intersects';
Expand Down Expand Up @@ -80,8 +80,8 @@ class Query
self::TYPE_NOT_ENDS_WITH,
self::TYPE_CROSSES,
self::TYPE_NOT_CROSSES,
self::TYPE_DISTANCE,
self::TYPE_NOT_DISTANCE,
self::TYPE_DISTANCE_EQUAL,
self::TYPE_DISTANCE_NOT_EQUAL,
self::TYPE_DISTANCE_GREATER_THAN,
self::TYPE_DISTANCE_LESS_THAN,
self::TYPE_INTERSECTS,
Expand Down Expand Up @@ -261,8 +261,8 @@ public static function isMethod(string $value): bool
self::TYPE_NOT_ENDS_WITH,
self::TYPE_CROSSES,
self::TYPE_NOT_CROSSES,
self::TYPE_DISTANCE,
self::TYPE_NOT_DISTANCE,
self::TYPE_DISTANCE_EQUAL,
self::TYPE_DISTANCE_NOT_EQUAL,
self::TYPE_INTERSECTS,
self::TYPE_NOT_INTERSECTS,
self::TYPE_OVERLAPS,
Expand All @@ -285,8 +285,8 @@ public function isSpatialQuery(): bool
return match ($this->method) {
self::TYPE_CROSSES,
self::TYPE_NOT_CROSSES,
self::TYPE_DISTANCE,
self::TYPE_NOT_DISTANCE,
self::TYPE_DISTANCE_EQUAL,
self::TYPE_DISTANCE_NOT_EQUAL,
self::TYPE_DISTANCE_GREATER_THAN,
self::TYPE_DISTANCE_LESS_THAN,
self::TYPE_INTERSECTS,
Expand Down Expand Up @@ -896,27 +896,27 @@ public function setOnArray(bool $bool): void
// Spatial query methods

/**
* Helper method to create Query with distance method
* Helper method to create Query with distanceEqual method
*
* @param string $attribute
* @param array<mixed> $values
* @return Query
*/
public static function distance(string $attribute, array $values): self
public static function distanceEqual(string $attribute, array $values): self
{
return new self(self::TYPE_DISTANCE, $attribute, $values);
return new self(self::TYPE_DISTANCE_EQUAL, $attribute, $values);
}

/**
* Helper method to create Query with notDistance method
* Helper method to create Query with distanceNotEqual method
*
* @param string $attribute
* @param array<mixed> $values
* @return Query
*/
public static function notDistance(string $attribute, array $values): self
public static function distanceNotEqual(string $attribute, array $values): self
{
return new self(self::TYPE_NOT_DISTANCE, $attribute, $values);
return new self(self::TYPE_DISTANCE_NOT_EQUAL, $attribute, $values);
}

/**
Expand Down
4 changes: 2 additions & 2 deletions src/Database/Validator/Queries.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,8 +108,8 @@ public function isValid($value): bool
Query::TYPE_OR,
Query::TYPE_CROSSES,
Query::TYPE_NOT_CROSSES,
Query::TYPE_DISTANCE,
Query::TYPE_NOT_DISTANCE,
Query::TYPE_DISTANCE_EQUAL,
Query::TYPE_DISTANCE_NOT_EQUAL,
Query::TYPE_DISTANCE_GREATER_THAN,
Query::TYPE_DISTANCE_LESS_THAN,
Query::TYPE_INTERSECTS,
Expand Down
4 changes: 2 additions & 2 deletions src/Database/Validator/Query/Filter.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -259,8 +259,8 @@ public function isValid($value): bool

return $this->isValidAttributeAndValues($attribute, $value->getValues(), $method);

case Query::TYPE_DISTANCE:
case Query::TYPE_NOT_DISTANCE:
case Query::TYPE_DISTANCE_EQUAL:
case Query::TYPE_DISTANCE_NOT_EQUAL:
case Query::TYPE_DISTANCE_GREATER_THAN:
case Query::TYPE_DISTANCE_LESS_THAN:
if (count($value->getValues()) !== 1 || !is_array($value->getValues()[0]) || count($value->getValues()[0]) !== 2) {
Expand Down
42 changes: 21 additions & 21 deletions tests/e2e/Adapter/Scopes/SpatialTests.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,8 +131,8 @@ public function testSpatialTypeDocuments(): void
$pointQueries = [
'equals' => Query::equal('pointAttr', [[6.0, 6.0]]),
'notEquals' => Query::notEqual('pointAttr', [[1.0, 1.0]]),
'distance' => Query::distance('pointAttr', [[[5.0, 5.0], 1.4142135623730951]]),
'notDistance' => Query::notDistance('pointAttr', [[[1.0, 1.0], 0.0]]),
'distanceEqual' => Query::distanceEqual('pointAttr', [[[5.0, 5.0], 1.4142135623730951]]),
'distanceNotEqual' => Query::distanceNotEqual('pointAttr', [[[1.0, 1.0], 0.0]]),
'intersects' => Query::intersects('pointAttr', [[6.0, 6.0]]),
'notIntersects' => Query::notIntersects('pointAttr', [[1.0, 1.0]])
];
Expand Down Expand Up @@ -425,15 +425,15 @@ public function testSpatialOneToMany(): void
], Database::PERMISSION_READ);
$this->assertEmpty($extremelyFar);

// Equal-distance semantics: distance (<=) and notDistance (>), threshold exactly at 0
// Equal-distanceEqual semantics: distanceEqual (<=) and distanceNotEqual (>), threshold exactly at 0
$equalZero = $database->find($child, [
Query::distance('coord', [[[10.0, 10.0], 0.0]])
Query::distanceEqual('coord', [[[10.0, 10.0], 0.0]])
], Database::PERMISSION_READ);
$this->assertNotEmpty($equalZero);
$this->assertEquals('p1', $equalZero[0]->getId());

$notEqualZero = $database->find($child, [
Query::notDistance('coord', [[[10.0, 10.0], 0.0]])
Query::distanceNotEqual('coord', [[[10.0, 10.0], 0.0]])
], Database::PERMISSION_READ);
$this->assertNotEmpty($notEqualZero);
$this->assertEquals('p2', $notEqualZero[0]->getId());
Expand Down Expand Up @@ -530,15 +530,15 @@ public function testSpatialManyToOne(): void
], Database::PERMISSION_READ);
$this->assertEmpty($veryFar);

// Equal-distance semantics: distance (<=) and notDistance (>), threshold exactly at 0
// Equal-distanceEqual semantics: distanceEqual (<=) and distanceNotEqual (>), threshold exactly at 0
$equalZero = $database->find($child, [
Query::distance('coord', [[[20.0, 20.0], 0.0]])
Query::distanceEqual('coord', [[[20.0, 20.0], 0.0]])
], Database::PERMISSION_READ);
$this->assertNotEmpty($equalZero);
$this->assertEquals('s1', $equalZero[0]->getId());

$notEqualZero = $database->find($child, [
Query::notDistance('coord', [[[20.0, 20.0], 0.0]])
Query::distanceNotEqual('coord', [[[20.0, 20.0], 0.0]])
], Database::PERMISSION_READ);
$this->assertNotEmpty($notEqualZero);
$this->assertEquals('s2', $notEqualZero[0]->getId());
Expand Down Expand Up @@ -598,7 +598,7 @@ public function testSpatialManyToMany(): void
]));
$this->assertInstanceOf(Document::class, $d1);

// Spatial query on "drivers" using point distance
// Spatial query on "drivers" using point distanceEqual
$near = $database->find($a, [
Query::distanceLessThan('home', [[[30.0, 30.0], 0.5]])
], Database::PERMISSION_READ);
Expand Down Expand Up @@ -635,15 +635,15 @@ public function testSpatialManyToMany(): void
], Database::PERMISSION_READ);
$this->assertEmpty($moderatelyFar);

// Equal-distance semantics: distance (<=) and notDistance (>), threshold exactly at 0
// Equal-distanceEqual semantics: distanceEqual (<=) and distanceNotEqual (>), threshold exactly at 0
$equalZero = $database->find($a, [
Query::distance('home', [[[30.0, 30.0], 0.0]])
Query::distanceEqual('home', [[[30.0, 30.0], 0.0]])
], Database::PERMISSION_READ);
$this->assertNotEmpty($equalZero);
$this->assertEquals('d1', $equalZero[0]->getId());

$notEqualZero = $database->find($a, [
Query::notDistance('home', [[[30.0, 30.0], 0.0]])
Query::distanceNotEqual('home', [[[30.0, 30.0], 0.0]])
], Database::PERMISSION_READ);
$this->assertEmpty($notEqualZero);

Expand Down Expand Up @@ -1156,14 +1156,14 @@ public function testComplexGeometricShapes(): void
], Database::PERMISSION_READ);
$this->assertNotEmpty($touchingLine);

// Test distance queries between shapes
// Test distanceEqual queries between shapes
$nearCenter = $database->find($collectionName, [
Query::distanceLessThan('circle_center', [[[10, 5], 5.0]]) // Points within 5 units of first center
], Database::PERMISSION_READ);
$this->assertNotEmpty($nearCenter);
$this->assertEquals('rect1', $nearCenter[0]->getId());

// Test distance queries to find nearby shapes
// Test distanceEqual queries to find nearby shapes
$nearbyShapes = $database->find($collectionName, [
Query::distanceLessThan('circle_center', [[[40, 4], 15.0]]) // Points within 15 units of second center
], Database::PERMISSION_READ);
Expand Down Expand Up @@ -1205,16 +1205,16 @@ public function testComplexGeometricShapes(): void
], Database::PERMISSION_READ);
$this->assertCount(1, $farFromOrigin);

// Equal-distance semantics for circle_center
// rect1 is exactly at [10,5], so distance 0
// Equal-distanceEqual semantics for circle_center
// rect1 is exactly at [10,5], so distanceEqual 0
$equalZero = $database->find($collectionName, [
Query::distance('circle_center', [[[10, 5], 0.0]])
Query::distanceEqual('circle_center', [[[10, 5], 0.0]])
], Database::PERMISSION_READ);
$this->assertNotEmpty($equalZero);
$this->assertEquals('rect1', $equalZero[0]->getId());

$notEqualZero = $database->find($collectionName, [
Query::notDistance('circle_center', [[[10, 5], 0.0]])
Query::distanceNotEqual('circle_center', [[[10, 5], 0.0]])
], Database::PERMISSION_READ);
$this->assertNotEmpty($notEqualZero);
$this->assertEquals('rect2', $notEqualZero[0]->getId());
Expand Down Expand Up @@ -1332,7 +1332,7 @@ public function testSpatialQueryCombinations(): void
], Database::PERMISSION_READ);
$this->assertCount(0, $farFromTimesSquare);

// Test ordering by distance from a specific point
// Test ordering by distanceEqual from a specific point
$orderedByDistance = $database->find($collectionName, [
Query::distanceLessThan('location', [[[40.7829, -73.9654], 0.01]]), // Within ~1km
Query::limit(10)
Expand Down Expand Up @@ -1696,14 +1696,14 @@ public function testSptialAggregation(): void
$this->assertInstanceOf(Document::class, $b);
$this->assertInstanceOf(Document::class, $c);

// COUNT with spatial distance filter
// COUNT with spatial distanceEqual filter
$queries = [
Query::distanceLessThan('loc', [[[10.0, 10.0], 0.1]])
];
$this->assertEquals(2, $database->count($collectionName, $queries));
$this->assertCount(2, $database->find($collectionName, $queries));

// SUM with spatial distance filter
// SUM with spatial distanceEqual filter
$sumNear = $database->sum($collectionName, 'score', $queries);
$this->assertEquals(10 + 20, $sumNear);

Expand Down