Skip to content

Added geospatial tests for $near #218

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
eerxuan merged 4 commits into from
May 27, 2026
Merged

Added geospatial tests for $near #218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ff0efac
Added geospatial tests for $near
May 21, 2026
d4cc5fd
moving minDistance and maxDistance tests cases to the dedicated folders
May 21, 2026
8d881ce
revised based on reviwer comments
May 26, 2026
36bec31
Merge branch 'main' into geospatial/near/tests
eerxuan May 27, 2026
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
13 changes: 13 additions & 0 deletions documentdb_tests/compatibility/tests/core/operator/query/geospatial/conftest.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
import pytest


@pytest.fixture
def geo_2dsphere(collection):
Copy link
Copy Markdown
Collaborator

@eerxuan eerxuan May 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I missed this, remember to keep each test case self-contained: has setup command and expected. So

pytestmark = pytest.mark.usefixtures("geo_2dsphere")

file level fixture breaks the pattern.

Also, you have fixture and inline create_index, which means this fixture is not flexible enough.

Please remove the fixture. We should have consistent format for index setup and collection setup.
We can create a similar index helpers as the CustomCollection etc. This can keep the self-contained test case pattern, and it is flexible enough so we can have TestCase specific index setup.

    CommandTestCase(
        "collation_null_uses_default",
        target_collection=CustomCollection(options={"collation": {"locale": "en", "strength": 2}}),
        docs=[{"_id": 1, "s": "abc"}, {"_id": 2, "s": "ABC"}, {"_id": 3, "s": "def"}],
        command=lambda ctx: {
            "count": ctx.collection,
            "query": {"s": "abc"},
            "collation": None,
        },
        expected={"n": 2, "ok": 1.0},
        msg="count with collation=null should use collection default collation",
    ),

"""Create a 2dsphere index on loc."""
collection.create_index([("loc", "2dsphere")])


@pytest.fixture
def geo_2d(collection):
"""Create a 2d index on loc."""
collection.create_index([("loc", "2d")])
Empty file added documentdb_tests/compatibility/tests/core/operator/query/geospatial/near/__init__.py
View file
Open in desktop
Empty file.
66 changes: 66 additions & 0 deletions ...ts/compatibility/tests/core/operator/query/geospatial/near/test_near_argument_handling.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
"""Tests for $near argument handling — valid GeoJSON structures, distance combinations."""

import pytest

from documentdb_tests.compatibility.tests.core.operator.query.utils.query_test_case import (
QueryTestCase,
)
from documentdb_tests.framework.assertions import assertSuccess
from documentdb_tests.framework.executor import execute_command
from documentdb_tests.framework.parametrize import pytest_params

pytestmark = pytest.mark.usefixtures("geo_2dsphere")

NYC_POINT = [-73.9667, 40.78]


GEOJSON_STRUCTURE_SUCCESS_TESTS: list[QueryTestCase] = [
QueryTestCase(
id="missing_type_defaults_to_point",
filter={"loc": {"$near": {"$geometry": {"coordinates": NYC_POINT}}}},
doc=[{"_id": 1, "loc": {"type": "Point", "coordinates": NYC_POINT}}],
expected=[{"_id": 1, "loc": {"type": "Point", "coordinates": NYC_POINT}}],
msg="Should accept $geometry without type field (defaults to Point)",
),
QueryTestCase(
id="valid_geojson_point",
filter={"loc": {"$near": {"$geometry": {"type": "Point", "coordinates": NYC_POINT}}}},
doc=[{"_id": 1, "loc": {"type": "Point", "coordinates": NYC_POINT}}],
expected=[{"_id": 1, "loc": {"type": "Point", "coordinates": NYC_POINT}}],
msg="Should accept valid GeoJSON Point",
),
QueryTestCase(
id="three_coordinates_altitude",
filter={
"loc": {"$near": {"$geometry": {"type": "Point", "coordinates": [-73.9667, 40.78, 0]}}}
},
doc=[{"_id": 1, "loc": {"type": "Point", "coordinates": NYC_POINT}}],
expected=[{"_id": 1, "loc": {"type": "Point", "coordinates": NYC_POINT}}],
msg="Should accept three coordinates (with altitude)",
),
QueryTestCase(
id="extra_field_in_geometry",
filter={
"loc": {
"$near": {
"$geometry": {
"type": "Point",
"coordinates": [0, 0],
"extra": "field",
}
}
}
},
doc=[{"_id": 1, "loc": {"type": "Point", "coordinates": [0, 0]}}],
expected=[{"_id": 1, "loc": {"type": "Point", "coordinates": [0, 0]}}],
msg="Should ignore extra fields inside $geometry",
),
]


@pytest.mark.parametrize("test", pytest_params(GEOJSON_STRUCTURE_SUCCESS_TESTS))
def test_near_valid_argument_handling(collection, test):
"""Verifies $near accepts valid GeoJSON structures."""
collection.insert_many(test.doc)
result = execute_command(collection, {"find": collection.name, "filter": test.filter})
assertSuccess(result, test.expected, msg=test.msg)
90 changes: 90 additions & 0 deletions ...tests/compatibility/tests/core/operator/query/geospatial/near/test_near_bson_validator.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
"""
Tests for $near BSON type validation.

Verifies that $near parameters reject invalid BSON types and accept valid ones.
"""

import pytest
from bson import Decimal128, Int64

from documentdb_tests.framework.assertions import assertFailureCode, assertSuccess
from documentdb_tests.framework.bson_type_validator import (
BsonType,
BsonTypeTestCase,
generate_bson_acceptance_test_cases,
generate_bson_rejection_test_cases,
)
from documentdb_tests.framework.error_codes import BAD_VALUE_ERROR
from documentdb_tests.framework.executor import execute_command

pytestmark = pytest.mark.usefixtures("geo_2dsphere")

GEOJSON_BSON_PARAMS = [
BsonTypeTestCase(
id="geometry",
msg="$geometry should reject non-object types",
keyword="$geometry",
valid_types=[BsonType.OBJECT],
valid_inputs={
BsonType.OBJECT: {"type": "Point", "coordinates": [0, 0]},
},
default_error_code=BAD_VALUE_ERROR,
),
BsonTypeTestCase(
id="coordinates",
msg="coordinates should reject non-numeric element types",
keyword="coordinates",
valid_types=[BsonType.DOUBLE, BsonType.INT, BsonType.LONG, BsonType.DECIMAL],
valid_inputs={
BsonType.DOUBLE: 0.0,
BsonType.INT: 0,
BsonType.LONG: Int64(0),
BsonType.DECIMAL: Decimal128("0"),
},
default_error_code=BAD_VALUE_ERROR,
),
]

GEOJSON_REJECTION = generate_bson_rejection_test_cases(GEOJSON_BSON_PARAMS)
GEOJSON_ACCEPTANCE = generate_bson_acceptance_test_cases(GEOJSON_BSON_PARAMS)


def _build_geojson_filter(spec, sample_value):
"""Build GeoJSON $near filter."""
if spec.keyword == "coordinates":
return {
"loc": {
"$near": {
"$geometry": {
"type": "Point",
"coordinates": [sample_value, sample_value],
}
}
}
}
return {"loc": {"$near": {"$geometry": sample_value}}}


@pytest.mark.parametrize("bson_type,sample_value,spec", GEOJSON_REJECTION)
def test_near_bson_type_rejected(collection, bson_type, sample_value, spec):
"""Verifies $near rejects invalid BSON types."""
result = execute_command(
collection,
{"find": collection.name, "filter": _build_geojson_filter(spec, sample_value)},
)
assertFailureCode(result, spec.expected_code(bson_type), msg=spec.msg)


@pytest.mark.parametrize("bson_type,sample_value,spec", GEOJSON_ACCEPTANCE)
def test_near_bson_type_accepted(collection, bson_type, sample_value, spec):
"""Verifies $near accepts valid BSON types."""
collection.insert_one({"_id": 1, "loc": {"type": "Point", "coordinates": [0, 0]}})
result = execute_command(
collection,
{"find": collection.name, "filter": _build_geojson_filter(spec, sample_value)},
)
assertSuccess(
result,
[{"_id": 1, "loc": {"type": "Point", "coordinates": [0, 0]}}],
msg=f"{spec.keyword} should accept {bson_type.value}",
)
142 changes: 142 additions & 0 deletions ...s/compatibility/tests/core/operator/query/geospatial/near/test_near_core_functionality.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
"""Tests for $near core functionality — nearest-first sorting, query interactions, nested fields."""
Comment thread
vic-tsang marked this conversation as resolved.

import pytest

from documentdb_tests.compatibility.tests.core.operator.query.utils.query_test_case import (
QueryTestCase,
)
from documentdb_tests.framework.assertions import assertSuccess
from documentdb_tests.framework.executor import execute_command
from documentdb_tests.framework.parametrize import pytest_params

GEOJSON_CORE_TESTS: list[QueryTestCase] = [
QueryTestCase(
id="basic_nearest_first",
filter={
"loc": {
"$near": {
"$geometry": {"type": "Point", "coordinates": [0, 0]},
}
}
},
doc=[
{"_id": 1, "loc": {"type": "Point", "coordinates": [5, 5]}},
{"_id": 2, "loc": {"type": "Point", "coordinates": [0, 0]}},
{"_id": 3, "loc": {"type": "Point", "coordinates": [1, 1]}},
],
expected=[
{"_id": 2, "loc": {"type": "Point", "coordinates": [0, 0]}},
{"_id": 3, "loc": {"type": "Point", "coordinates": [1, 1]}},
{"_id": 1, "loc": {"type": "Point", "coordinates": [5, 5]}},
],
msg="Should return documents sorted nearest to farthest",
),
]

VALID_INTERACTION_TESTS: list[QueryTestCase] = [
QueryTestCase(
id="near_inside_and",
filter={
"$and": [
{"loc": {"$near": {"$geometry": {"type": "Point", "coordinates": [0, 0]}}}},
{"category": "A"},
]
},
doc=[
{"_id": 1, "loc": {"type": "Point", "coordinates": [0, 0]}, "category": "A"},
{"_id": 2, "loc": {"type": "Point", "coordinates": [1, 1]}, "category": "B"},
{"_id": 3, "loc": {"type": "Point", "coordinates": [2, 2]}, "category": "A"},
],
expected=[
{"_id": 1, "loc": {"type": "Point", "coordinates": [0, 0]}, "category": "A"},
{"_id": 3, "loc": {"type": "Point", "coordinates": [2, 2]}, "category": "A"},
],
msg="Should work inside $and with additional filter",
),
QueryTestCase(
id="near_with_equality_other_field",
filter={
"loc": {"$near": {"$geometry": {"type": "Point", "coordinates": [0, 0]}}},
"category": "A",
},
doc=[
{"_id": 1, "loc": {"type": "Point", "coordinates": [0, 0]}, "category": "A"},
{"_id": 2, "loc": {"type": "Point", "coordinates": [1, 1]}, "category": "B"},
],
expected=[
{"_id": 1, "loc": {"type": "Point", "coordinates": [0, 0]}, "category": "A"},
],
msg="Should combine with equality on another field",
),
]


@pytest.mark.usefixtures("geo_2dsphere")
@pytest.mark.parametrize(
"test",
pytest_params(GEOJSON_CORE_TESTS + VALID_INTERACTION_TESTS),
)
def test_near_core(collection, test):
"""Verifies $near core functionality."""
collection.insert_many(test.doc)
result = execute_command(collection, {"find": collection.name, "filter": test.filter})
assertSuccess(result, test.expected, msg=test.msg)


@pytest.mark.usefixtures("geo_2dsphere")
def test_near_explicit_sort_overrides_distance(collection):
"""Verifies explicit sort overrides $near distance ordering."""
collection.insert_many(
[
{"_id": 1, "loc": {"type": "Point", "coordinates": [0, 0]}, "rank": 3},
{"_id": 2, "loc": {"type": "Point", "coordinates": [1, 0]}, "rank": 1},
{"_id": 3, "loc": {"type": "Point", "coordinates": [2, 0]}, "rank": 2},
]
)
result = execute_command(
collection,
{
"find": collection.name,
"filter": {"loc": {"$near": {"$geometry": {"type": "Point", "coordinates": [0, 0]}}}},
"sort": {"rank": 1},
},
)
assertSuccess(
result,
[
{"_id": 2, "loc": {"type": "Point", "coordinates": [1, 0]}, "rank": 1},
{"_id": 3, "loc": {"type": "Point", "coordinates": [2, 0]}, "rank": 2},
{"_id": 1, "loc": {"type": "Point", "coordinates": [0, 0]}, "rank": 3},
],
msg="Should sort by explicit field, overriding distance",
)


def test_near_nested_field(collection):
"""Verifies $near works on nested field path."""
collection.create_index([("address.location", "2dsphere")])
collection.insert_many(
[
{"_id": 1, "address": {"location": {"type": "Point", "coordinates": [0, 0]}}},
{"_id": 2, "address": {"location": {"type": "Point", "coordinates": [5, 5]}}},
]
)
result = execute_command(
collection,
{
"find": collection.name,
"filter": {
"address.location": {
"$near": {"$geometry": {"type": "Point", "coordinates": [0, 0]}}
}
},
},
)
assertSuccess(
result,
[
{"_id": 1, "address": {"location": {"type": "Point", "coordinates": [0, 0]}}},
{"_id": 2, "address": {"location": {"type": "Point", "coordinates": [5, 5]}}},
],
msg="Should work on nested field path",
)
Loading
Loading