Registry / database / mongoose-atlas-search

mongoose-atlas-search

JSON →
library1.0.12jsnpmunverified

A customizable Mongoose plugin (v1.0.12) that transparently converts standard Mongoose find() queries into aggregation pipelines leveraging MongoDB Atlas Search indexes. Designed for Atlas deployments on MongoDB 4.2+, it can either overwrite Model.find() or add a separate .search() method. Requires manual Atlas Search index creation. Stable release; low update cadence.

database
npm install mongoose-atlas-search
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · MONGOOSE-ATLAS-SEA
M
mongoose-atlas-search
databasejavascriptv1.0.12
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export (atlasPlugin)
✓ const atlasPlugin = require('mongoose-atlas-search');
✗ import atlasPlugin from 'mongoose-atlas-search';
Package does not ship ESM; use CommonJS require() with default import.
initialize
✓ atlasPlugin.initialize({ model, overwriteFind: true, searchKey: 'search', ... });
✗ atlasPlugin.initialize({ overWrite: true });
Option 'overwriteFind' is misspelled in documentation; must match the documented key exactly.
TypeScript types
✓ import type { AtlasPluginOptions } from 'mongoose-atlas-search';
Types are shipped; use import type for type-only imports or import atlasPlugin from 'mongoose-atlas-search' (but note CJS-only).

Load the plugin, initialize it on a Mongoose model with a custom search function, then call find() with a searchKey to trigger Atlas Search aggregation.

const mongoose = require('mongoose'); const atlasPlugin = require('mongoose-atlas-search'); // Connect to MongoDB Atlas (must have Atlas Search enabled) mongoose.connect('mongodb+srv://cluster0.xxxxx.mongodb.net/mydb', { user: process.env.DB_USER ?? '', pass: process.env.DB_PASS ?? '' }); const UserSchema = new mongoose.Schema({ name: String, email: String, language: String }, { collection: 'users' }); const UserModel = mongoose.model('User', UserSchema); atlasPlugin.initialize({ model: UserModel, overwriteFind: true, searchKey: 'search', searchFunction: query => ({ wildcard: { query: `${query}*`, path: 'name', allowAnalyzedField: true } }) }); (async () => { // Uses Atlas Search aggregation const result = await UserModel.find({ search: 'test' }); console.log(result); // Standard find (no search key) const normal = await UserModel.find({ name: 'test' }); console.log(normal); })();
Debug
Known issues
breakingAtlas Search indexes must be created manually before using the plugin.
fix
Create an Atlas Search index in the Atlas UI or via the Atlas API on the target collection with appropriate mappings.
affects: >=0.0.0
gotchaPlugin only works with MongoDB Atlas clusters (4.2+). Not compatible with local MongoDB or MongoDB replicas without Atlas Search.
fix
Ensure your connection targets an Atlas cluster with Search enabled. Use non-Atlas deployments of Mongoose without this plugin.
affects: >=0.0.0
gotchaoverwriteFind option defaults to true. If set to false, the method .search(query, projection, opts) is added instead of overwriting find().
fix
Read the documentation: set overwriteFind: false and use Model.search() explicitly when needed.
affects: >=0.0.0
deprecatedThe package uses CommonJS only (no ESM support).
fix
Use require() instead of import. If using ES modules, consider using dynamic import or switching packages.
affects: >=0.0.0
gotchasearchFunction option must return an object that is valid for the $search aggregation stage. Wrong return structure causes aggregation failure.
fix
Ensure the returned object has a valid Atlas Search operator (e.g., { wildcard: { ... } }) and that path fields exist in the Atlas Search index.
affects: >=0.0.0
Errors
Common errors & fixes
TypeError: atlasPlugin.initialize is not a function
Using ES module import on a CJS-only package.
fix
Use const atlasPlugin = require('mongoose-atlas-search'); instead of import.
MongoError: unknown top level operator: $search
The aggregation pipeline uses $search but the MongoDB server does not have Atlas Search enabled or is not an Atlas cluster.
fix
Connect to an Atlas cluster with Atlas Search enabled on MongoDB 4.2+.
Error: Cannot read property 'model' of undefined
initialize() called without options object or model option is missing.
fix
Call atlasPlugin.initialize({ model: YourModel, ... }) with a valid Mongoose model.
MongoDB Atlas Search index not found for collection: users
No Atlas Search index created on the collection that the model points to.
fix
Create a Search index via Atlas UI with the correct name (default is 'default') or match the index name used in searchFunction.
Upgrade
Version history
1.0.12latest on npm
Audit
Dependencies
mongooserequiredpeer dependency required as the plugin interacts with Mongoose models and schema
Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/rocknrolla777/mongoose-atlas-search ↗
packagemongoose-atlas-search ↗
homepagehttps://github.com/rocknrolla777/mongoose-atlas-search#readme ↗
mongoose-atlas-search — npm install mongoose-atlas-search · libregistry