Mongoose

Mongoose 建構函式。

mongoose 模組的 exports 物件是此類別的實例。大多數應用程式只會使用這一個實例。

範例

const mongoose = require('mongoose');
mongoose instanceof mongoose.Mongoose; // true

// Create a new Mongoose instance with its own `connect()`, `set()`, `model()`, etc.
const m = new mongoose.Mongoose();

Mongoose Aggregate 建構函式

Mongoose CastError 建構函式

Mongoose Collection 建構函式

Mongoose Connection 建構函式

為使用者層級公開連線狀態

Mongoose Date SchemaType。

範例

const schema = new Schema({ test: Date });
schema.path('test') instanceof mongoose.Date; // true

Mongoose Decimal128 SchemaType。用於在結構描述中宣告應為 128 位元十進位浮點數的路徑。請勿使用此項來建立新的 Decimal128 實例，請改用 mongoose.Types.Decimal128。

範例

const vehicleSchema = new Schema({ fuelLevel: mongoose.Decimal128 });

Mongoose Document 建構函式。

Mongoose DocumentProvider 建構函式。Mongoose 使用者不應直接使用此項

MongooseError 建構函式。

Mongoose Mixed SchemaType。用於在結構描述中宣告 Mongoose 的變更追蹤、轉換和驗證應忽略的路徑。

範例

const schema = new Schema({ arbitrary: mongoose.Mixed });

Mongoose Model 建構函式。

Mongoose 建構函式

mongoose 模組的 exports 是此類別的實例。

範例

const mongoose = require('mongoose');
const mongoose2 = new mongoose.Mongoose();

Mongoose Number SchemaType。用於在結構描述中宣告 Mongoose 應轉換為數字的路徑。

範例

const schema = new Schema({ num: mongoose.Number });
// Equivalent to:
const schema = new Schema({ num: 'number' });

Mongoose ObjectId SchemaType。用於在結構描述中宣告應為 MongoDB ObjectIds 的路徑。請勿使用此項來建立新的 ObjectId 實例，請改用 mongoose.Types.ObjectId。

範例

const childSchema = new Schema({ parentId: mongoose.ObjectId });

Mongoose Query 建構函式。

為使用者層級公開連線狀態

Mongoose Schema 建構函式

範例

const mongoose = require('mongoose');
const Schema = mongoose.Schema;
const CatSchema = new Schema(..);

Mongoose SchemaType 建構函式

用於結構描述類型選項的建構函式

各種 Mongoose SchemaType。

注意

為了向後相容性，這是 mongoose.Schema.Types 的別名。

各種 Mongoose 類型。

範例

const mongoose = require('mongoose');
const array = mongoose.Types.Array;

類型

• Array
• Buffer
• 嵌入式
• DocumentArray
• Decimal128
• ObjectId
• Map
• Subdocument

使用此公開存取 ObjectId 類型，我們可以按需建構 ID。

const ObjectId = mongoose.Types.ObjectId;
const id1 = new ObjectId;

Mongoose VirtualType 建構函式

開啟預設的 Mongoose 連線。

範例

mongoose.connect('mongodb://user:pass@127.0.0.1:port/database');

// replica sets
const uri = 'mongodb://user:pass@127.0.0.1:port,anotherhost:port,yetanother:port/mydatabase';
mongoose.connect(uri);

// with options
mongoose.connect(uri, options);

// Using `await` throws "MongooseServerSelectionError: Server selection timed out after 30000 ms"
// if Mongoose can't connect.
const uri = 'mongodb://nonexistent.domain:27000';
await mongoose.connect(uri);

Mongoose 模組的預設連線。相當於 mongoose.connections[0]，請參閱 connections。

範例

const mongoose = require('mongoose');
mongoose.connect(...);
mongoose.connection.on('error', cb);

這是預設用於使用 mongoose.model 建立的每個模型的連線。

若要建立新的連線，請使用 createConnection()。

包含與此 Mongoose 實例相關聯的所有 連線 的陣列。預設情況下，有 1 個連線。呼叫 createConnection() 會將連線新增至此陣列。

範例

const mongoose = require('mongoose');
mongoose.connections.length; // 1, just the default connection
mongoose.connections[0] === mongoose.connection; // true

mongoose.createConnection('mongodb://127.0.0.1:27017/test');
mongoose.connections.length; // 2

建立 Connection 實例。

每個 connection 實例都會對應到單一資料庫。此方法在管理多個資料庫連線時很有用。

傳遞的選項會優先於連線字串中包含的選項。

範例

// with mongodb:// URI
db = mongoose.createConnection('mongodb://user:pass@127.0.0.1:port/database');

// and options
const opts = { db: { native_parser: true }}
db = mongoose.createConnection('mongodb://user:pass@127.0.0.1:port/database', opts);

// replica sets
db = mongoose.createConnection('mongodb://user:pass@127.0.0.1:port,anotherhost:port,yetanother:port/database');

// and options
const opts = { replset: { strategy: 'ping', rs_name: 'testSet' }}
db = mongoose.createConnection('mongodb://user:pass@127.0.0.1:port,anotherhost:port,yetanother:port/database', opts);

// initialize now, connect later
db = mongoose.createConnection();
await db.openUri('mongodb://127.0.0.1:27017/database');

從預設連線中移除名為 name 的模型（如果存在）。您可以使用此函式來清除您在測試中建立的任何模型，以防止 OverwriteModelErrors。

等同於 mongoose.connection.deleteModel(name)。

範例

mongoose.model('User', new Schema({ name: String }));
console.log(mongoose.model('User')); // Model object
mongoose.deleteModel('User');
console.log(mongoose.model('User')); // undefined

// Usually useful in a Mocha `afterEach()` hook
afterEach(function() {
  mongoose.deleteModel(/.+/); // Delete every model
});

並行在所有連線上執行 .close()。

具有 get() 和 set() 的物件，包含此 Mongoose 實例用來與資料庫通訊的基礎驅動程式。驅動程式是一個 Mongoose 特有的介面，定義了諸如 find() 等函式。

取得 mongoose 選項

範例

mongoose.get('test') // returns the 'test' value

如果給定的值是 Mongoose ObjectId（使用 instanceof）或是給定的值是 24 個字元的十六進位字串（這是 ObjectId 最常用的字串表示法），則傳回 true。

此函式類似於 isValidObjectId()，但更嚴格，因為 isValidObjectId() 會為 Mongoose 可以轉換為 ObjectId 的任何值傳回 true。這包括 Mongoose 文件、任何長度為 12 的字串以及任何數字。isObjectIdOrHexString() 僅對 ObjectId 實例或 24 個字元的十六進位字串傳回 true，並且會為數字、文件和長度為 12 的字串傳回 false。

範例

mongoose.isObjectIdOrHexString(new mongoose.Types.ObjectId()); // true
mongoose.isObjectIdOrHexString('62261a65d66c6be0a63c051f'); // true

mongoose.isObjectIdOrHexString('0123456789ab'); // false
mongoose.isObjectIdOrHexString(6); // false
mongoose.isObjectIdOrHexString(new User({ name: 'test' })); // false
mongoose.isObjectIdOrHexString({ test: 42 }); // false

如果 Mongoose 可以將給定的值轉換為 ObjectId，則傳回 true，否則傳回 false。

範例

mongoose.isValidObjectId(new mongoose.Types.ObjectId()); // true
mongoose.isValidObjectId('0123456789ab'); // true
mongoose.isValidObjectId(6); // true
mongoose.isValidObjectId(new User({ name: 'test' })); // true

mongoose.isValidObjectId({ test: 42 }); // false

定義模型或檢索模型。

在 mongoose 實例上定義的模型，對由同一 mongoose 實例建立的所有連線都可用。

如果您使用相同的名稱但不同的綱要呼叫 mongoose.model() 兩次，則會收到 OverwriteModelError。如果您使用相同的名稱和相同的綱要呼叫 mongoose.model()，則會取回相同的綱要。

範例

const mongoose = require('mongoose');

// define an Actor model with this mongoose instance
const schema = new Schema({ name: String });
mongoose.model('Actor', schema);

// create a new connection
const conn = mongoose.createConnection(..);

// create Actor model
const Actor = conn.model('Actor', schema);
conn.model('Actor') === Actor; // true
conn.model('Actor', schema) === Actor; // true, same schema
conn.model('Actor', schema, 'actors') === Actor; // true, same schema and collection name

// This throws an `OverwriteModelError` because the schema is different.
conn.model('Actor', new Schema({ name: String }));

當沒有傳遞 collection 引數時，Mongoose 使用模型名稱。如果您不喜歡此行為，可以傳遞集合名稱、使用 mongoose.pluralize() 或設定綱要的集合名稱選項。

範例

const schema = new Schema({ name: String }, { collection: 'actor' });

// or

schema.set('collection', 'actor');

// or

const collectionName = 'actor';
const M = mongoose.model('Actor', schema, collectionName);

傳回在此 Mongoose 實例上建立的模型名稱陣列。

注意

不包括使用 connection.model() 建立的模型名稱。

Mongoose 使用的 mquery 查詢產生器。

Mongoose 使用此函式來取得設定時間戳記時的目前時間。您可以使用諸如 Sinon 之類的工具來存根此函式以進行測試。

接收一個物件，並從該物件中刪除值與 undefined 嚴格相等的任何鍵。此函式對於查詢篩選很有用，因為 Mongoose 將 TestModel.find({ name: undefined }) 視為 TestModel.find({ name: null })。

範例

const filter = { name: 'John', age: undefined, status: 'active' };
mongoose.omitUndefined(filter); // { name: 'John', status: 'active' }
filter; // { name: 'John', status: 'active' }

await UserModel.findOne(mongoose.omitUndefined(filter));

在 post() 中介軟體中使用此函式來取代結果

範例

schema.post('find', function(res) {
  // Normally you have to modify `res` in place. But with
  // `overwriteMiddlewarResult()`, you can make `find()` return a
  // completely different value.
  return mongoose.overwriteMiddlewareResult(res.filter(doc => !doc.isDeleted));
});

宣告在所有綱要上執行的全域外掛程式。

等同於在您建立的每個綱要上呼叫 .plugin(fn)。

用於將集合名稱轉換為複數的函式的 getter/setter。

透過將任何具有以 $ 開頭的屬性的巢狀物件包裝在 $eq 中，以對抗 查詢選擇器注入攻擊來清理查詢篩選器。

const obj = { username: 'val', pwd: { $ne: null } };
sanitizeFilter(obj);
obj; // { username: 'val', pwd: { $eq: { $ne: null } } });

設定 mongoose 選項

key 可以用作物件來一次設定多個選項。如果一個選項拋出錯誤，則仍然會評估其他選項。

範例

mongoose.set('test', value) // sets the 'test' option to `value`

mongoose.set('debug', true) // enable logging collection methods + arguments to the console/file

mongoose.set('debug', function(collectionName, methodName, ...methodArgs) {}); // use custom function to log collection methods + arguments

mongoose.set({ debug: true, autoIndex: false }); // set multiple options at once

目前支援的選項有

• allowDiskUse：設定為 true 以將 allowDiskUse 設定為 true，預設用於所有彙總操作。
• applyPluginsToChildSchemas：預設為 true。設定為 false 可跳過將全域外掛程式套用至子綱要
• applyPluginsToDiscriminators：預設為 false。設定為 true 可將全域外掛程式套用至辨別器綱要。通常不需要這樣做，因為外掛程式會套用至基本綱要，而辨別器會從基本綱要複製所有中介軟體、方法、靜態和屬性。
• autoCreate：設定為 true 可讓 Mongoose 在您使用 mongoose.model() 或 conn.model() 建立模型時自動呼叫 Model.createCollection()。這對於測試交易、變更串流和其他需要集合存在的功能很有用。
• autoIndex：預設為 true。設定為 false 可停用與此 Mongoose 實例相關聯的所有模型的自動索引建立。
• bufferCommands：啟用/停用所有連線和模型的 mongoose 緩衝機制
• bufferTimeoutMS：如果 bufferCommands 開啟，此選項會設定 Mongoose 緩衝在拋出錯誤之前將等待的最長時間。如果未指定，Mongoose 將使用 10000（10 秒）。
• cloneSchemas：預設為 false。設定為 true 可在編譯為模型之前 clone() 所有綱要。
• debug：如果為 true，則將 mongoose 發送給 MongoDB 的操作列印到主控台。如果傳遞了可寫入串流，則會記錄到該串流，而沒有色彩化。如果傳遞了回呼函式，它將接收集合名稱、方法名稱，然後接收傳遞給該方法的所有引數。例如，如果您想要複製預設記錄，則可以從回呼輸出 Mongoose: ${collectionName}.${methodName}(${methodArgs.join(', ')})。
• id：如果為 true，則會將 id 虛擬新增至所有綱要，除非在每個綱要的基礎上覆寫。
• timestamps.createdAt.immutable：預設為 true。如果為 false，則會將 createdAt 欄位變更為 immutable: false，這表示您可以更新 createdAt
• maxTimeMS：如果設定，則會將 maxTimeMS 附加到每個查詢
• objectIdGetter：預設為 true。Mongoose 會將一個名為 _id 的 getter 新增至 MongoDB ObjectId，為了方便使用 populate，會傳回 this。將此設定為 false 可移除 getter。
• overwriteModels：設定為 true 可預設為覆寫呼叫 mongoose.model() 時具有相同名稱的模型，而不是拋出 OverwriteModelError。
• returnOriginal：如果為 false，則會將預設的 returnOriginal 選項變更為 findOneAndUpdate()、findByIdAndUpdate 和 findOneAndReplace() 為 false。這等同於預設將 findOneAndX() 呼叫的 new 選項設定為 true。如需詳細資訊，請閱讀我們的findOneAndUpdate() 教學。
• runValidators：預設為 false。設定為 true 可預設為所有驗證器啟用更新驗證器。
• sanitizeFilter：預設為 false。設定為 true 可啟用查詢篩選器的清理，以對抗查詢選擇器注入攻擊，方法是將任何具有以 $ 開頭的屬性的巢狀物件包裝在 $eq 中。
• selectPopulatedPaths：預設為 true。設定為 false 可選擇退出 Mongoose 將您 populate() 的所有欄位新增至您的 select()。綱要層級選項 selectPopulatedPaths 會覆寫此選項。
• strict：預設為 true，可以是 false、true 或 'throw'。設定綱要的預設嚴格模式。
• strictQuery：預設為 false。可以是 false、true 或 'throw'。設定綱要的預設 strictQuery 模式。
• toJSON：預設為 { transform: true, flattenDecimals: true }。覆寫預設物件為 toJSON()，以決定 Mongoose 文件如何由 JSON.stringify() 序列化
• toObject：預設為 { transform: true, flattenDecimals: true }。覆寫預設物件為 toObject()

覆寫此 Mongoose 實例使用的目前驅動程式。驅動程式是一個 Mongoose 特有的介面，定義了諸如 find() 等函式。

在 pre() 中介軟體中使用此函式，以跳過呼叫封裝函式。

範例

schema.pre('save', function() {
  // Will skip executing `save()`, but will execute post hooks as if
  // `save()` had executed with the result `{ matchedCount: 0 }`
  return mongoose.skipMiddlewareFunction({ matchedCount: 0 });
});

需要 MongoDB >= 3.6.0。 啟動一個 MongoDB 會話，以獲得諸如因果一致性、可重試寫入和 交易等好處。

調用 mongoose.startSession() 等同於調用 mongoose.connection.startSession()。會話的作用域限定在一個連接上，因此調用 mongoose.startSession() 會在預設的 mongoose 連接上啟動一個會話。

同步此連接註冊的所有模型的索引。

告知 sanitizeFilter() 在過濾潛在的 查詢選擇器注入攻擊時，跳過給定的物件。當您有已知的查詢選擇器想要使用時，請使用此方法。

const obj = { username: 'val', pwd: trusted({ $type: 'string', $eq: 'my secret' }) };
sanitizeFilter(obj);

// Note that `sanitizeFilter()` did not add `$eq` around `$type`.
obj; // { username: 'val', pwd: { $type: 'string', $eq: 'my secret' } });

Mongoose 版本

範例

console.log(mongoose.version); // '5.x.x'