Add support for filtering to queryNearest

[mackinleysmith]

This PR adds filtering support to the queryNearest method, allowing users to filter results using the same filter builder API available in query. This addresses the feature request in #17 and the discussion in the Discord thread.

Changes

• Extended queryNearest signature: The method now accepts an options object that can include both maxDistance and filter parameters, while maintaining backwards compatibility with the existing numeric maxDistance parameter.
• Filter builder support: Users can now apply the same filter conditions available in query:
  • eq() - equality filters
  • in() - value in a set filters
  • gte() / lt() - sort key range filters
• Backend implementation: Updated nearestPoints query to accept filtering conditions and sorting intervals, passing them through to ClosestPointQuery.
• Documentation: Updated README with examples showing the new filtering capabilities.

Example Usage

const result = await geospatial.queryNearest(
  ctx,
  { latitude: 40.7813, longitude: -73.9737 },
  maxResults,
  {
    maxDistance: 10000,
    filter: (q) => q.eq("category", "coffee"),
  },
);

Benefits

• Filtering helps constrain the search space and can speed up lookups
• Consistent API with the existing query method
• Backwards compatible - existing code using numeric maxDistance continues to work
• Enables use cases like finding nearest points matching specific criteria (e.g., "nearest coffee shops" or "nearest available books")

Testing

• Added tests for must and should filter conditions in pointQuery.test.ts
• Verified sort key interval filtering works correctly
• Existing tests continue to pass

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[ianmacartney]

I’m planning to drop the cjs path and that statement entirely soon. Sorry it bit you!

…

On Thu, Nov 6, 2025 at 8:54 AM MacKinley Smith ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In package.json <#23 (comment)>: > @@ -23,8 +23,8 @@ "scripts": { "build": "npm run build:esm && npm run build:cjs", "build:go": "cd src/s2-bindings && python build.py", - "build:esm": "tsc --project ./esm.json && echo '{\\n \"type\": \"module\"\\n}' > dist/esm/package.json", - "build:cjs": "tsc --project ./commonjs.json && echo '{\\n \"type\": \"commonjs\"\\n}' > dist/commonjs/package.json", + "build:esm": "tsc --project ./esm.json && echo -e '{\n \"type\": \"module\"\n}' > dist/esm/package.json", Oof... turns out that echo -e is not supported on macOS, so I'm updating this to use a node script for full cross platform support. Another option is to use printf, but that might lose compatibility with Windows. I sure am shaving yaks today. — Reply to this email directly, view it on GitHub <#23 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW64KT5JNGJV4M4EOOL33N4NZAVCNFSM6AAAAACLHWDVKSVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTIMRZGM3DANRTGU> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[mackinleysmith]

Thank you for the approval, @sethconve! I have resolved the merge conflict on this branch and also opened another PR for my follow-on work to optimize the server-side aspect of this, #25. Please let me know if there's anything I can do to be helpful with getting this across the finish line. Cheers!

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/get-convex/geospatial/@convex-dev/geospatial@23

commit: 8bfaa6d

[ianmacartney]

@mackinleysmith am I understanding correctly that #25 is basically a replacement for this branch? any reason to merge both?

[ianmacartney]

main has been updated to a new flow without cjs - so hopefully the new dev workflow works for you? Let us know if you hit any snags. rm -r example/node_modules; mv example/.env.local ./; might be necessary

[mackinleysmith]

@ianmacartney yeah, #25 contains this branch so merging that one would be sufficient, so long as we're in agreement on that being the best approach for the database side of this. I tried to organize it so that this PR contains the interface level changes and that one contains query level optimization to better support it, but ran into some limitations with trying to give you guys an easy time reviewing them in isolation. Sorry about that!

As for the new cjs-less flow, it seems to be working for me! I was able to upgrade my applications after merging master into my fork and was able to remove the customizations i introduced in package.json on this branch. Thanks for fixing that!