---
title: "Bulk Insert: How to Work With Bulk Insert Operation"
description: "Use RavenDB's BulkInsertOperation to efficiently insert large volumes of documents, counters, time series, and attachments in a single batch."
url: "https://docs.ravendb.net/7.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation"
version: "7.2"
language: "java"
---

# Bulk Insert: How to Work With Bulk Insert Operation

> Client language: Java. Also available for [C#](https://docs.ravendb.net/7.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.md), [Node.js](https://docs.ravendb.net/7.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

One of the features that is particularly useful when inserting large amount of data is `bulk inserting`.  
This is an optimized time-saving approach with few drawbacks that will be described later.

### Syntax

```java
BulkInsertOperation bulkInsert();

BulkInsertOperation bulkInsert(String database);
```

| Parameters | | |
| - | - | - |
| **database** | `String` | The name of the database to perform the bulk operation on.<br />If `null`, the DocumentStore `Database` will be used. |

| Return Value | |
| - | - |
| `BulkInsertOperation` | Instance of BulkInsertOperation used for interaction. |

## BulkInsertOperation

#### Methods

| Signature | Description |
| - | - |
| **void abort()** | Abort the operation |
| **void store(Object entity, IMetadataDictionary metadata = null)** | store the entity, identifier will be generated automatically on client-side. Optional, metadata can be provided for the stored entity. |
| **void store(Object entity, String id, IMetadataDictionary metadata = null)** | store the entity, with `id` parameter to explicitly declare the entity identifier. Optional, metadata can be provided for the stored entity. |
| **void close()** | Close an object |

### Limitations

There are a couple limitations to the API:

- The bulk insert operation is broken into batches, each batch is treated in its own transaction
  so the whole operation isn't treated under a single transaction.
- Bulk insert is not thread safe, a single bulk insert should not be accessed concurrently.  
  The use of multiple bulk inserts, on the same client, concurrently is supported also the
  use in an async context is supported.

### Example

#### Create bulk insert

Here we create a bulk insert operation and insert a million documents of type Employee

```java
try (BulkInsertOperation bulkInsert = store.bulkInsert()) {
  for (int i = 0; i < 1_000_000; i++) {
      Employee employee = new Employee();
      employee.setFirstName("FirstName #" + i);
      employee.setLastName("LastName #" + i);
      bulkInsert.store(employee);
  }
}
```

## See also

- [What is a Document Store](https://docs.ravendb.net/7.2/client-api/what-is-a-document-store.java.md)
- [What is a Session and How Does it Work](https://docs.ravendb.net/7.2/client-api/session/what-is-a-session-and-how-does-it-work.java.md)
- [Bulk Insert: How to Add Attachments](https://docs.ravendb.net/7.2/document-extensions/attachments/store-attachments/bulk-insert.md)
- [Bulk Insert: How to Append Time Series](https://docs.ravendb.net/7.2/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.md)
- [Working with Document Identifiers](https://docs.ravendb.net/7.2/client-api/document-identifiers/working-with-document-identifiers.md)
- [Create or Modify Counters](https://docs.ravendb.net/7.2/document-extensions/counters/create-or-modify.java.md)
- [What is the Changes API](https://docs.ravendb.net/7.2/client-api/changes/what-is-changes-api.java.md)
