Registry / database / mongodb-collection-sample

mongodb-collection-sample

JSON →
library5.0.0jsnpmunverified

Samples documents from MongoDB collections using native $sample aggregation (MongoDB ≥3.1.6) or client-side reservoir sampling for older versions. Version 5.0.0 is stable and maintains backward compatibility. Key differentiator: automatic fallback between server-side and client-side sampling based on MongoDB version and sample size relative to collection count, avoiding blocking sorts. Supports options like query filter, sample size, projection, raw BSON, sort, maxTimeMS, and value promotion.

database
npm install mongodb-collection-sample
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · MONGODB-COLLECTION
M
mongodb-collection-sample
databasejavascriptv5.0.0
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.

sample
✓ const sample = require('mongodb-collection-sample');
✗ import sample from 'mongodb-collection-sample'
This package uses CommonJS and does not ship ESM; default import will not work in Node.js without transpilation.
MongoClient
✓ const { MongoClient } = require('mongodb');
✗ import { MongoClient } from 'mongodb'; // works in ESM but require is typical for CJS
The mongodb driver v3+ supports ESM, but this package expects a db object from the driver.
sample (stream)
✓ const stream = sample(db, 'collection', { size: 10 });
✗ const result = await sample(db, 'collection', { size: 10 });
The function returns a readable stream, not a promise. Use stream events ('data', 'end', 'error') or pipe.

Connects to MongoDB, samples 5 documents from a collection using a readable stream.

const sample = require('mongodb-collection-sample'); const { MongoClient } = require('mongodb'); async function main() { const client = new MongoClient('mongodb://localhost:27017', { useUnifiedTopology: true }); await client.connect(); const db = client.db('test'); const stream = sample(db, 'mycollection', { size: 5 }); stream.on('data', doc => console.log(doc)); stream.on('error', err => console.error(err)); stream.on('end', () => { console.log('Sampling complete'); client.close(); }); } main().catch(console.error);
Debug
Known issues
gotchaThe function returns a stream, not a promise. Do not await it.
fix
Use event listeners ('data', 'end', 'error') or pipe to a writable stream.
affects: all
gotchaFor MongoDB >=3.1.6, the native $sample stage is used but may fall back to reservoir sampling if sample size >5% of collection count.
fix
Review the package's fallback logic for performance; consider using native $sample if collection is large.
affects: all
gotchaThe query option must be a valid MongoDB filter object; passing an empty string or invalid type may cause unexpected behavior.
fix
Ensure query is an object, e.g., { status: 'active' }, or omit it.
affects: all
Errors
Common errors & fixes
TypeError: sample is not a function
Attempting to import as default when CommonJS require was expected.
fix
Use `const sample = require('mongodb-collection-sample');` instead of `import sample from ...`
TypeError: db.collection is not a function
The first argument to sample() must be a database object (from MongoClient.db()), not a client or a collection.
fix
Call `const db = client.db('databaseName');` and pass `db`.
Error: Cannot find module 'lodash'
lodash is a required peer dependency but not installed.
fix
Run `npm install lodash` alongside this package.
Upgrade
Version history
5.0.0latest on npm
Audit
Dependencies
lodashrequiredUsed internally for range and random operations; the package requires it as a peer dependency at runtime.
mongodbrequiredRequired to provide a connected MongoClient instance; the sample function expects a db object from the mongodb driver.
Agent activity
9 hits · last 30 days
node
8
Resources
githubgit://github.com/mongodb-js/mongodb-collection-sample ↗
packagemongodb-collection-sample ↗
homepagehttps://github.com/mongodb-js/mongodb-collection-sample ↗
mongodb-collection-sample — npm install mongodb-collection-sample · libregistry