New Feature / Enhancement Checklist
Current Limitation
Parse Server's MongoDB adapter transparently creates a 2d geospatial index the first time a geo distance query ($nearSphere / $geoNear) runs against a field that has no geo index. This happens at query (read) time, inside a .catch on the failed find in MongoCollection.find() (src/Adapters/Storage/Mongo/MongoCollection.js):
// Does a find with "smart indexing".
// Currently this just means, if it needs a geoindex and there is
// none, then build the geoindex.
// This could be improved a lot but it's not clear if that's a good
// idea. Or even if this behavior is a good idea.
The code comment itself questions whether this behavior is a good idea. It has several problems:
- Fragile detection. It decides whether to act, and which field to index, by inspecting the MongoDB error code and error message text. This just caused a High-severity regression: MongoDB 8.3 shortened the "no geo index" error message and dropped the
field=<name> token it relied on, so every geo distance query on an un-indexed field failed with a generic "internal server error" (fixed separately, but the root fragility remains).
- Reads cause writes. A read operation silently triggers a DDL/index build. On a large collection this can cause an unexpected, blocking foreground index build, added load, and surprising latency — triggered by an ordinary query.
- Requires write privileges for a read path and can conflict with managed/hardened deployments where index creation is intentionally controlled.
- Inconsistent across adapters. The Postgres adapter does not do this, so geo behavior differs by database backend.
- Bypasses explicit index management. Parse Server already supports declaring indexes via the schema (
indexes), which is the appropriate, predictable place to manage them.
Feature / Enhancement Description
Remove the implicit, on-demand 2d geospatial index creation from MongoCollection.find() in the next major release. Geo indexes should be managed explicitly rather than materialized as a side effect of a query.
Example Use
- A geo distance query on a field with a geo index works exactly as today.
- A geo distance query on a field without a geo index returns a clear, actionable Parse error (e.g. indicating a geospatial index is required on that field) instead of silently creating one — or the query engine is invoked only after an explicitly-declared index exists.
Alternatives / Suggested Implementation
- Remove the
.catch auto-index path in MongoCollection.find().
- Support declaring geo indexes via schema so users can provision the
2d index up front (predictable, at deploy/migration time rather than query time).
- Deprecation path: in a minor release before removal, log a deprecation warning whenever the auto-index path fires, so operators can pre-create the needed indexes before upgrading to the major that removes it.
- Migration guide: document the change and how to create the equivalent
2d index for existing apps that relied on the implicit behavior.
Additional context
The recent MongoDB 8.3 error-message change (which broke this path) is the concrete motivation: relying on server error-message text to drive index creation is inherently brittle. The near-term fix keeps the behavior working by reading the field from the query object instead of the error message, but the underlying "auto-create indexes at read time" design should be retired in the next major.
Historical origin of the behavior: #1913.
New Feature / Enhancement Checklist
Current Limitation
Parse Server's MongoDB adapter transparently creates a
2dgeospatial index the first time a geo distance query ($nearSphere/$geoNear) runs against a field that has no geo index. This happens at query (read) time, inside a.catchon the failed find inMongoCollection.find()(src/Adapters/Storage/Mongo/MongoCollection.js):The code comment itself questions whether this behavior is a good idea. It has several problems:
field=<name>token it relied on, so every geo distance query on an un-indexed field failed with a generic "internal server error" (fixed separately, but the root fragility remains).indexes), which is the appropriate, predictable place to manage them.Feature / Enhancement Description
Remove the implicit, on-demand
2dgeospatial index creation fromMongoCollection.find()in the next major release. Geo indexes should be managed explicitly rather than materialized as a side effect of a query.Example Use
Alternatives / Suggested Implementation
.catchauto-index path inMongoCollection.find().2dindex up front (predictable, at deploy/migration time rather than query time).2dindex for existing apps that relied on the implicit behavior.Additional context
The recent MongoDB 8.3 error-message change (which broke this path) is the concrete motivation: relying on server error-message text to drive index creation is inherently brittle. The near-term fix keeps the behavior working by reading the field from the query object instead of the error message, but the underlying "auto-create indexes at read time" design should be retired in the next major.
Historical origin of the behavior: #1913.