Insert (Output Stage)
Description
insert() is a Data manipulation language (DML) stage that adds new documents
to Firestore. This stage can be attached to the end of a query to
insert the results of that query into a collection.
The insert() stage can take different arguments to determine the destination
collection and document ID:
insert(collectionName, documentIdExpression): Inserts documents into the specified collection, using the evaluated expression to determine the document ID.insert(collectionName): Inserts documents into the specified collection, automatically generating document IDs.insert(): Inserts documents, requiring a__name__field in the input document to determine the destination collection and document ID.
Examples
Insert static documents
The following example inserts new documents into the users collection,
using the id field from the input to define the document IDs:
Node.js
```js const results = await db.pipeline() .literals([ { foo: "bar", id: "doc1" }, { foo: "baz", id: "doc2" } ]) .insert({ collection: "users", documentId: field("id") }) .execute(); ```Java
```java Pipeline pipeline = db.pipeline() .literals( Map.of("foo", "bar", "id", "doc1"), Map.of("foo", "baz", "id", "doc2")) .insert(new Insert().withCollection("users").withDocumentId(field("id"))); pipeline.execute(); ```Behavior
The following sections describe the execution behavior, responses, and
restrictions for the insert() stage.
Evaluated Document ID Expression
The following example computes new document IDs using a string concatenation
expression stringConcat(...) and inserts the results
into new_users inside an explicit transaction:
Node.js
```js const results = await db.runTransaction(async (transaction) => { return transaction.execute( db.pipeline() .collection("users") .distinct(field("name")) .insert({ collection: "new_users", documentId: stringConcat(constant("new_"), field("name")), }) ); }); ```Java
```java Pipeline pipeline = db.pipeline() .collection("users") .distinct(field("name")) .insert(new Insert() .withCollection("new_users") .withDocumentId(stringConcat(constant("new_"), field("name")))); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```Document References (__name__)
The following example uses document references assigned to the __name__ field
to specify both destination collection and document ID:
Node.js
```js const results = await db.pipeline() .literals([ { __name__: db.doc("users/doc1"), foo: "bar" }, { __name__: db.doc("users/doc2"), foo: "baz" } ]) .insert() .execute(); ```Java
```java Pipeline pipeline = db.pipeline() .literals( Map.of("__name__", db.document("users/doc1"), "foo", "bar"), Map.of("__name__", db.document("users/doc2"), "foo", "baz")) .insert(new Insert()); pipeline.execute(); ```Auto-Generated IDs
The following example inserts new documents into the users collection,
allowing Firestore to auto-generate the document IDs:
Node.js
```js const results = await db.pipeline() .literals([ { foo: "bar" }, { foo: "baz" } ]) .insert({ collection: "users" }) .execute(); ```Java
```java Pipeline pipeline = db.pipeline() .literals( Map.of("foo", "bar"), Map.of("foo", "baz")) .insert(new Insert().withCollection("users")); pipeline.execute(); ```Insert Into a Subcollection
The insert() stage can be used to insert documents directly into a
subcollection using a full path.
Node.js
```js const results = await db.pipeline() .literals([ { title: "post1" }, { title: "post2" } ]) .insert({ collection: "users/u1/posts" }) .execute(); ```Java
```java Pipeline pipeline = db.pipeline() .literals( Map.of("title", "post1"), Map.of("title", "post2")) .insert(new Insert().withCollection("users/u1/posts")); pipeline.execute(); ```Insert Into a Different Collection
The insert() stage can read from one collection, apply transformations, and
write into another collection within a transaction:
Node.js
```js const results = await db.runTransaction(async (transaction) => { return transaction.execute( db.pipeline() .collection("source_coll") .where(field("active").equal(true)) .addFields(constant("val").as("new_field")) .insert({ collection: "target_coll" }) ); }); ```Java
```java Pipeline pipeline = db.pipeline() .collection("source_coll") .where(field("active").equal(true)) .addFields(constant("val").as("new_field")) .insert(new Insert().withCollection("target_coll")); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```Insert from Advanced Queries (Search and Find Nearest)
The insert() stage can be used with advanced query operations like search or
findNearest to write the matching documents into an output collection.
Node.js
```js const results = await db.runTransaction(async (transaction) => { return transaction.execute( db.pipeline() .collection("products") .search({ query: "shoes" }) .insert({ collection: "matched_products" }) ); }); ```Java
```java Pipeline pipeline = db.pipeline() .collection("products") .search(searchOptionsBuilder().query(documentMatches("shoes"))) .insert(new Insert().withCollection("matched_products")); db.runTransaction(transaction -> { transaction.execute(pipeline); return null; }); ```Response
The insert() stage always emits a single document like
{ documents_modified: 2 } describing how many documents were inserted.
Final Stage
The insert() stage must come at the end of a pipeline, no further stages can
be provided.
Transaction Required
The insert() stage requires a transaction. It must be run within an active
read-write transaction, or with the atomic (Node.js) or auto_commit option
set to true when starting a new transaction.
Already Exists
The insert() stage will fail with an ALREADY_EXISTS error if any document to
be inserted already exists in the destination.
Response
The response includes a summary of the number of documents modified. For example, the following response confirms that the pipeline modified three documents:
{documents_modified: 3L}
Limitations
DML stages can now be run within transactions. The
insert()andupsert()stages need to be run within a transaction in most cases.When executing a pipeline with DML stages within a new transaction, you can use the
atomicoption to automatically run within a transaction and commit upon successful execution of the pipeline.When running within a transaction, there are no restrictions on other stages (such as
where,addFields,union,findNearest, andaggregatesubqueries). Transactional DML operations are bounded by Firestore Enterprise edition transaction limits. Because transactions don't allow reads after the first write, you cannot call a DML pipeline multiple times within a single transaction or read documents after a DML pipeline executes. Attempting to execute a read after a DML write fails with aFAILED_PRECONDITIONerror:Cannot have reads after the first write in a Firestore transaction.When running outside of a transaction:
- Each document is updated independently of each other, and writes are not atomic across documents. The pipeline halts on the first error, allowing for partial success to occur.
- Advanced multi-query stages (
aggregate,distinct,unnest,find_nearest,union, joins, and subqueries) are not supported.
Under Firebase Security Rules, each batch of documents re-evaluates rules and executes lookups. If rules use
get()orexists(), the global 20-lookup limit is reached after writing approximately 200 documents, and the operation fails withPERMISSION_DENIED. Use Custom Claims instead ofget()/exists()lookups to avoid this limit.If the stage preceding the DML stage produces multiple documents with the same
__name__or evaluates to the same destination document ID, each mutation is processed sequentially:- For
upsert(...)andupdate(...): Multiple mutations targeting the same document follow "last one wins" semantics, where the last mutation processed determines the final state of the document. - For
delete(...): The first attempt deletes the document, and subsequent attempts for the same document are no-ops. - For
insert(...): The first attempt creates the document, and subsequent attempts targeting the same document ID fail with anALREADY_EXISTSerror.
- For
Transactional Execution
DML operations can be executed as part of a read-write transaction by either
providing an explicit transaction to the pipeline execution call or by using the
atomic option.
Firestore transactions require all reads to execute before any writes. Because
a DML pipeline executes writes, you cannot perform reads (such as document
lookups or query reads) after running a DML pipeline in the same transaction.
For example, you cannot call a DML pipeline multiple times in a single
transaction. Attempting to read after a DML pipeline executes fails with a
FAILED_PRECONDITION error:
Cannot have reads after the first write in a Firestore transaction.