Insert Documents

该页面提供了 MongoDB 中插入操作的示例。

Creating a Collection

如果该集合当前不存在，则插入操作将创建该集合。

插入单个文档

3.2 版中的新功能。

Mongo Shell

Compass

Python

Java (Sync)

Node.js

PHP

Motor

Java (Async)

Perl

Ruby

Scala

db.collection.insertOne() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, MongoDB adds the _id field with an ObjectId value to the new document. See Insert Behavior.

db.inventory.insertOne(
   { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } }
)

You can run the operation in the web shell below:

MongoDB Web Shell
insertOne() returns a document that includes the newly inserted document's _id field value. For an example of a return document, see db.collection.insertOne() reference.

To insert a single document using MongoDB Compass:

Navigate to the collection you wish to insert the document into:
In the left-hand MongoDB Compass navigation pane, click the database to which your target collection belongs.
- From the database view, click the target collection name.
Click the Insert Document button:

For each field in the document, select the field type and fill in the field name and value. Add fields by clicking the last line number, then clicking Add Field After …
For Object types, add nested fields by clicking the last field's number and selecting Add Field After …
For Array types, add additional elements to the array by clicking the last element's line number and selecting Add Array Element After …
Once all fields have been filled out, click Insert.

The following example inserts a new document into the test.inventory collection:
../../_images/compass-insert-document-inventory.png

Note

MongoDB Compass generates the _id field and its value automatically. The generated ObjectId consists of a unique randomly generated hexadecimal value.

You can change this value prior to inserting your document so long as it remains unique and is a valid ObjectId . For more information on the _id field, see _id Field.

pymongo.collection.Collection.insert_one() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the PyMongo driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

db.inventory.insert_one(
    {"item": "canvas",
     "qty": 100,
     "tags": ["cotton"],
     "size": {"h": 28, "w": 35.5, "uom": "cm"}})

insert_one() returns an instance of pymongo.results.InsertOneResult whose inserted_id field contains the _id of the newly inserted document.

com.mongodb.client.MongoCollection.insertOne inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

Document canvas = new Document("item", "canvas")
        .append("qty", 100)
        .append("tags", singletonList("cotton"));

Document size = new Document("h", 28)
        .append("w", 35.5)
        .append("uom", "cm");
canvas.put("size", size);

collection.insertOne(canvas);

Collection.insertOne() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the Node.js driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

await db.collection('inventory').insertOne({
  item: 'canvas',
  qty: 100,
  tags: ['cotton'],
  size: { h: 28, w: 35.5, uom: 'cm' }
});

insertOne() returns a promise that provides a result . The result.insertedId promise contains the _id of the newly inserted document.

MongoDB\Collection::insertOne() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the PHP driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

$insertOneResult = $db->inventory->insertOne([
    'item' => 'canvas',
    'qty' => 100,
    'tags' => ['cotton'],
    'size' => ['h' => 28, 'w' => 35.5, 'uom' => 'cm'],
]);

Upon successful insert, the insertOne() method returns an instance of MongoDB\InsertOneResult whose getInsertedId() method returns the _id of the newly inserted document.

motor.motor_asyncio.AsyncIOMotorCollection.insert_one() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the Motor driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

await db.inventory.insert_one(
    {"item": "canvas",
     "qty": 100,
     "tags": ["cotton"],
     "size": {"h": 28, "w": 35.5, "uom": "cm"}})

insert_one() returns an instance of pymongo.results.InsertOneResult whose inserted_id field contains the _id of the newly inserted document.

com.mongodb.reactivestreams.client.MongoCollection.insertOne inserts a single document into a collection with the Java Reactive Streams Driver:

{ item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } }

The following example inserts the document above into the inventory collection. If the document does not specify an _id field, the driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

Document canvas = new Document("item", "canvas")
        .append("qty", 100)
        .append("tags", singletonList("cotton"));

Document size = new Document("h", 28)
        .append("w", 35.5)
        .append("uom", "cm");
canvas.put("size", size);

Publisher<Success> insertOnePublisher = collection.insertOne(canvas);

com.mongodb.reactivestreams.client.MongoCollection.insertOne returns a Publisher object. The Publisher inserts the document into a collection when subscribers request data.

IMongoCollection.InsertOne() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the C# driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

var document = new BsonDocument
{
    { "item", "canvas" },
    { "qty", 100 },
    { "tags", new BsonArray { "cotton" } },
    { "size", new BsonDocument { { "h", 28 }, { "w", 35.5 }, { "uom", "cm" } } }
};
collection.InsertOne(document);

MongoDB::Collection::insert_one() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the Perl driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

$db->coll("inventory")->insert_one(
    {
        item => "canvas",
        qty  => 100,
        tags => ["cotton"],
        size => { h => 28, w => 35.5, uom => "cm" }
    }
);

Upon successful insert, the insert_one() method returns an instance of MongoDB::InsertOneResult whose inserted_id attribute contains the _id of the newly inserted document.

Mongo::Collection#insert_one() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the Ruby driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

client[:inventory].insert_one({ item: 'canvas',
                                qty: 100,
                                tags: [ 'cotton' ],
                                size: { h: 28, w: 35.5, uom: 'cm' } })

Upon successful insert, the insert_one() method returns an instance of Mongo::Operation::Result, whose inserted_id attribute contains the _id of the newly inserted document.

collection.insertOne() inserts a single document into a collection.

The following example inserts a new document into the inventory collection. If the document does not specify an _id field, the Scala driver adds the _id field with an ObjectId value to the new document. See Insert Behavior.

collection.insertOne(
  Document("item" -> "canvas", "qty" -> 100, "tags" -> Seq("cotton"), "size" -> Document("h" -> 28, "w" -> 35.5, "uom" -> "cm"))
).execute()

Upon successful insert, the collection.insertOne() method returns an instance of collection.insertOne().results(); whose inserted_id attribute contains the _id of the newly inserted document.

要检索刚刚插入的文档，查询集合：

Mongo Shell

Compass

Python

Java (Sync)

Node.js

PHP

Motor

Java (Async)

Perl

Ruby

Scala

db.inventory.find( { item: "canvas" } )

../../_images/compass-query-collection.png

Specify a filter in the MongoDB Compass query bar and click Find to execute the query.

The above filter specifies that MongoDB Compass only return documents where the item field is equal to canvas .

For more information on the MongoDB Compass Query Bar, see the Compass Query Bar documentation.

cursor = db.inventory.find({"item": "canvas"})

FindIterable<Document> findIterable = collection.find(eq("item", "canvas"));

const cursor = db.collection('inventory').find({ item: 'canvas' });

$cursor = $db->inventory->find(['item' => 'canvas']);

cursor = db.inventory.find({"item": "canvas"})

FindPublisher<Document> findPublisher = collection.find(eq("item", "canvas"));

var filter = Builders<BsonDocument>.Filter.Eq("item", "canvas");
var result = collection.Find(filter).ToList();

$cursor = $db->coll("inventory")->find( { item => "canvas" } );

client[:inventory].find(item: 'canvas')

val observable = collection.find(equal("item", "canvas"))

插入多个文档

Mongo Shell

Compass

Python

Java (Sync)

Node.js

PHP

Motor

Java (Async)

Perl

Ruby

Scala

New in version 3.2.

db.collection.insertMany() can insert multiple documents into a collection. Pass an array of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, MongoDB adds the _id field with an ObjectId value to each document. See Insert Behavior.

db.inventory.insertMany([
   { item: "journal", qty: 25, tags: ["blank", "red"], size: { h: 14, w: 21, uom: "cm" } },
   { item: "mat", qty: 85, tags: ["gray"], size: { h: 27.9, w: 35.5, uom: "cm" } },
   { item: "mousepad", qty: 25, tags: ["gel", "blue"], size: { h: 19, w: 22.85, uom: "cm" } }
])

You can run the operation in the web shell below:

MongoDB Web Shell
insertMany() returns a document that includes the newly inserted documents _id field values. See the reference for an example.

To retrieve the inserted documents, query the collection:

db.inventory.find( {} )

Currently, MongoDB Compass does not support inserting multiple documents in a single operation.
../../_images/compass-select-all.png

New in version 3.2.

pymongo.collection.Collection.insert_many() can insert multiple documents into a collection. Pass an iterable of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the PyMongo driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

db.inventory.insert_many([
    {"item": "journal",
     "qty": 25,
     "tags": ["blank", "red"],
     "size": {"h": 14, "w": 21, "uom": "cm"}},
    {"item": "mat",
     "qty": 85,
     "tags": ["gray"],
     "size": {"h": 27.9, "w": 35.5, "uom": "cm"}},
    {"item": "mousepad",
     "qty": 25,
     "tags": ["gel", "blue"],
     "size": {"h": 19, "w": 22.85, "uom": "cm"}}])

insert_many() returns an instance of pymongo.results.InsertManyResult whose inserted_ids field is a list containing the _id of each newly inserted document.

To retrieve the inserted documents, query the collection:

cursor = db.inventory.find({})

New in version 3.2.

com.mongodb.client.MongoCollection.insertMany can insert multiple documents into a collection. Pass a list of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

Document journal = new Document("item", "journal")
        .append("qty", 25)
        .append("tags", asList("blank", "red"));

Document journalSize = new Document("h", 14)
        .append("w", 21)
        .append("uom", "cm");
journal.put("size", journalSize);

Document mat = new Document("item", "mat")
        .append("qty", 85)
        .append("tags", singletonList("gray"));

Document matSize = new Document("h", 27.9)
        .append("w", 35.5)
        .append("uom", "cm");
mat.put("size", matSize);

Document mousePad = new Document("item", "mousePad")
        .append("qty", 25)
        .append("tags", asList("gel", "blue"));

Document mousePadSize = new Document("h", 19)
        .append("w", 22.85)
        .append("uom", "cm");
mousePad.put("size", mousePadSize);

collection.insertMany(asList(journal, mat, mousePad));

To retrieve the inserted documents, query the collection:

FindIterable<Document> findIterable = collection.find(new Document());

New in version 3.2.

Collection.insertMany() can insert multiple documents into a collection. Pass an array of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the Node.js driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

await db.collection('inventory').insertMany([
  {
    item: 'journal',
    qty: 25,
    tags: ['blank', 'red'],
    size: { h: 14, w: 21, uom: 'cm' }
  },
  {
    item: 'mat',
    qty: 85,
    tags: ['gray'],
    size: { h: 27.9, w: 35.5, uom: 'cm' }
  },
  {
    item: 'mousepad',
    qty: 25,
    tags: ['gel', 'blue'],
    size: { h: 19, w: 22.85, uom: 'cm' }
  }
]);

insertMany() returns a promise that provides a result . The result.insertedIds field contains an array with the _id of each newly inserted document.

To retrieve the inserted documents, query the collection:

const cursor = db.collection('inventory').find({});

New in version 3.2.

MongoDB\Collection::insertMany() can insert multiple documents into a collection. Pass an array of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the PHP driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

$insertManyResult = $db->inventory->insertMany([
    [
        'item' => 'journal', 
        'qty' => 25,
        'tags' => ['blank', 'red'],
        'size' => ['h' => 14, 'w' => 21, 'uom' => 'cm'],
    ],
    [
        'item' => 'mat', 
        'qty' => 85,
        'tags' => ['gray'],
        'size' => ['h' => 27.9, 'w' => 35.5, 'uom' => 'cm'],
    ],
    [
        'item' => 'mousepad', 
        'qty' => 25,
        'tags' => ['gel', 'blue'],
        'size' => ['h' => 19, 'w' => 22.85, 'uom' => 'cm'],
    ],
]);

Upon successful insert, the insertMany() method returns an instance of MongoDB\InsertManyResult whose getInsertedIds() method returns the _id of each newly inserted document.

To retrieve the inserted documents, query the collection:

$cursor = $db->inventory->find([]);

motor.motor_asyncio.AsyncIOMotorCollection.insert_many() can insert multiple documents into a collection. Pass an iterable of documents to the method.

await db.inventory.insert_many([
    {"item": "journal",
     "qty": 25,
     "tags": ["blank", "red"],
     "size": {"h": 14, "w": 21, "uom": "cm"}},
    {"item": "mat",
     "qty": 85,
     "tags": ["gray"],
     "size": {"h": 27.9, "w": 35.5, "uom": "cm"}},
    {"item": "mousepad",
     "qty": 25,
     "tags": ["gel", "blue"],
     "size": {"h": 19, "w": 22.85, "uom": "cm"}}])

insert_many() returns an instance of pymongo.results.InsertManyResult whose inserted_ids field is a list containing the _id of each newly inserted document.

To retrieve the inserted documents, query the collection:

cursor = db.inventory.find({})

New in version 3.2.

com.mongodb.reactivestreams.client.MongoCollection.html.insertMany inserts the following documents with the Java Reactive Streams Driver:

{ item: "journal", qty: 25, tags: ["blank", "red"], size: { h: 14, w: 21, uom: "cm" } }
{ item: "mat", qty: 85, tags: ["gray"], size: { h: 27.9, w: 35.5, uom: "cm" } }
{ item: "mousepad", qty: 25, tags: ["gel", "blue"], size: { h: 19, w: 22.85, uom: "cm" } }

Document journal = new Document("item", "journal")
        .append("qty", 25)
        .append("tags", asList("blank", "red"));

Document journalSize = new Document("h", 14)
        .append("w", 21)
        .append("uom", "cm");
journal.put("size", journalSize);

Document mat = new Document("item", "mat")
        .append("qty", 85)
        .append("tags", singletonList("gray"));

Document matSize = new Document("h", 27.9)
        .append("w", 35.5)
        .append("uom", "cm");
mat.put("size", matSize);

Document mousePad = new Document("item", "mousePad")
        .append("qty", 25)
        .append("tags", asList("gel", "blue"));

Document mousePadSize = new Document("h", 19)
        .append("w", 22.85)
        .append("uom", "cm");
mousePad.put("size", mousePadSize);

Publisher<Success> insertManyPublisher = collection.insertMany(asList(journal, mat, mousePad));

com.mongodb.reactivestreams.client.MongoCollection.html.insertMany returns a Publisher object. The Publisher inserts the document into a collection when subscribers request data.

To retrieve the inserted documents, query the collection:

FindPublisher<Document> findPublisher = collection.find(new Document());

New in version 3.2.

IMongoCollection.InsertMany() can insert multiple documents into a collection. Pass an enumerable collection of documents to the method.

var documents = new BsonDocument[]
{
    new BsonDocument
    {
        { "item", "journal" },
        { "qty", 25 },
        { "tags", new BsonArray { "blank", "red" } },
        { "size", new BsonDocument { { "h", 14 }, { "w", 21 }, {  "uom", "cm"} } }
    },
    new BsonDocument
    {
        { "item", "mat" },
        { "qty", 85 },
        { "tags", new BsonArray { "gray" } },
        { "size", new BsonDocument { { "h", 27.9 }, { "w", 35.5 }, {  "uom", "cm"} } }
    },
    new BsonDocument
    {
        { "item", "mousepad" },
        { "qty", 25 },
        { "tags", new BsonArray { "gel", "blue" } },
        { "size", new BsonDocument { { "h", 19 }, { "w", 22.85 }, {  "uom", "cm"} } }
    },
};
collection.InsertMany(documents);

To retrieve the inserted documents, query the collection:

var filter = Builders<BsonDocument>.Filter.Empty;
var result = collection.Find(filter).ToList();

New in version 3.2.

MongoDB::Collection::insert_many() can insert multiple documents into a collection. Pass an array reference of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the Perl driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

$db->coll("inventory")->insert_many(
    [
        {
            item => "journal",
            qty  => 25,
            tags => [ "blank", "red" ],
            size => { h => 14, w => 21, uom => "cm" }
        },
        {
            item => "mat",
            qty  => 85,
            tags => ["gray"],
            size => { h => 27.9, w => 35.5, uom => "cm" }
        },
        {
            item => "mousepad",
            qty  => 25,
            tags => [ "gel", "blue" ],
            size => { h => 19, w => 22.85, uom => "cm" }
        }
    ]
);

Upon successful insert, the insert_many() method returns an instance of MongoDB::InsertManyResult whose inserted_ids attribute is a list containing the _id of each newly inserted document.

To retrieve the inserted documents, query the collection:

$cursor = $db->coll("inventory")->find( {} );

New in version 3.2.

Mongo::Collection#insert_many() can insert multiple documents into a collection. Pass an array of documents to the method.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the Ruby driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

client[:inventory].insert_many([{ item: 'journal',
                                  qty: 25,
                                  tags: ['blank', 'red'],
                                  size: { h: 14, w: 21, uom: 'cm' }
                                },
                                { item: 'mat',
                                  qty: 85,
                                  tags: ['gray'],
                                  size: { h: 27.9, w: 35.5, uom: 'cm' }
                                },
                                { item: 'mousepad',
                                  qty: 25,
                                  tags: ['gel', 'blue'],
                                  size: { h: 19, w: 22.85, uom: 'cm' }
                                }
                               ])

Upon successful insert, the insert_many() method returns an instance of Mongo::BulkWrite::Result whose inserted_ids attribute is a list containing the _id of each newly inserted document.

To retrieve the inserted documents, query the collection:

client[:inventory].find({})

New in version 3.2.

collection.insertMany() can insert multiple documents into a collection.

The following example inserts three new documents into the inventory collection. If the documents do not specify an _id field, the Scala driver adds the _id field with an ObjectId value to each document. See Insert Behavior.

collection.insertMany(Seq(
  Document("item" -> "journal", "qty" -> 25, "tags" -> Seq("blank", "red"), "size" -> Document("h" -> 14, "w" -> 21, "uom" -> "cm")),
  Document("item" -> "mat", "qty" -> 85, "tags" -> Seq("gray"), "size" -> Document("h" -> 27.9, "w" -> 35.5, "uom" -> "cm")),
  Document("item" -> "mousepad", "qty" -> 25, "tags" -> Seq("gel", "blue"), "size" -> Document("h" -> 19, "w" -> 22.85, "uom" -> "cm"))
)).execute()

Upon successful insert, the insertMany() method returns an Observable with a type parameter indicating when the operation has completed or with either a com.mongodb.DuplicateKeyException or com.mongodb.MongoException .

To retrieve the inserted documents, query the collection:

var findObservable = collection.find(Document())

Insert Behavior

Collection Creation

如果该集合当前不存在，则插入操作将创建该集合。

_id Field

在 MongoDB 中，存储在集合中的每个文档都需要一个唯一的_id字段，该字段充当primary key。如果插入的文档省略_id字段，则 MongoDB 驱动程序会自动为_id字段生成ObjectId。

这也适用于通过对upsert: true的更新操作插入的文档。

Atomicity

MongoDB 中的所有写操作都是单个文档级别的原子操作。有关 MongoDB 和原子性的更多信息，请参阅原子性和 Transaction

Write Acknowledgement

对于写入问题，您可以指定从 MongoDB 请求的写入操作的确认级别。有关详细信息，请参见Write Concern。

Mongo Shell

Python

Java (Sync)

Node.js

PHP

Motor

Java (Async)

Perl

Ruby

Scala