---
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: "csharp"
---

# Bulk Insert: How to Work With Bulk Insert Operation

> Client language: C#. Also available for [Java](https://docs.ravendb.net/7.2/client-api/bulk-insert/how-to-work-with-bulk-insert-operation.java.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."

> **Note**
>
> - `BulkInsert` is useful when inserting a large quantity of data from the client to the server.
>
> - It is an optimized time-saving approach with a few
>   [limitations](#limitations)
>   like the possibility that interruptions will occur during the operation.
>
> - In this page:
>   - [Quick example](#quick-example)
>   - [`BulkInsertOperation`](#bulkinsertoperation)
>     - [Methods](#methods)
>     - [Limitations](#limitations)
>     - [Example](#example)
>   - [`BulkInsertOptions`](#bulkinsertoptions)
>     - [CompressionLevel](#compressionlevel)
>     - [SkipOverwriteIfUnchanged](#skipoverwriteifunchanged)
>   - [Track progress with OnProgress](#track-progress-with-onprogress)
>   - [Syntax](#syntax)
>     - [Method signatures](#method-signatures)
>     - [Event signature](#event-signature)
>     - [Classes](#classes)

## Quick example {#quick-example}

Open a bulk insert from the document store and store entities through it.  
Each `Store` call is buffered and streamed to the server in batches; the operation finalizes
when the bulk insert is disposed.

```csharp
using (BulkInsertOperation bulkInsert = store.BulkInsert())
{
    foreach (var employee in employees)
    {
        bulkInsert.Store(employee);
    }
}
```

For the full set of `BulkInsert` overloads and their parameters, see the
[Syntax](#syntax)
section at the end of this page.

## BulkInsertOperation {#bulkinsertoperation}

The following methods can be used when creating a bulk insert.

### Methods

| Signature | Description |
| - | - |
| `void Abort()` | Abort the operation. |
| `string Store(object entity, IMetadataDictionary metadata = null)` | Store the entity. The identifier is generated automatically on the client side and returned. Optional metadata can be provided for the stored entity. |
| `void Store(object entity, string id, IMetadataDictionary metadata = null)` | Store the entity with an explicit `id`. Optional metadata can be provided for the stored entity. |
| `Task<string> StoreAsync(object entity, IMetadataDictionary metadata = null)` | Store the entity asynchronously. The identifier is generated automatically on the client side and returned. Optional metadata can be provided for the stored entity. |
| `Task StoreAsync(object entity, string id, IMetadataDictionary metadata = null)` | Store the entity asynchronously, with an explicit `id`. Optional metadata can be provided for the stored entity. |
| `void Dispose()` | Dispose of the operation. |
| `ValueTask DisposeAsync()` | Dispose of the operation asynchronously. |

---

### Limitations

- BulkInsert is designed to efficiently push large volumes of data.  
  Data is therefore streamed and **processed by the server in batches**.  
  Each batch is fully transactional, but there are no transaction guarantees between the
  batches, and the operation as a whole is non-transactional.  
  If the bulk insert operation is interrupted mid-way, some of your data might be persisted
  on the server while some of it might not.
  - Make sure that your logic accounts for the possibility of an interruption that would
    cause some of your data not to persist on the server yet.
  - If the operation was interrupted and you choose to re-insert the whole dataset in a
    new operation, you can set
    [SkipOverwriteIfUnchanged](#skipoverwriteifunchanged)
    to `true` so the operation overwrites existing documents only if they changed since
    the last insertion.
  - **If you need full transactionality**, using a
    [session](https://docs.ravendb.net/7.2/client-api/session/what-is-a-session-and-how-does-it-work.md)
    may be a better option.  
    Note that if a session is used, all of the data is processed in a single transaction,
    so the server must have sufficient resources to handle the entire data set included
    in the transaction.
- Bulk insert is **not thread-safe**.  
  A single bulk insert should not be accessed concurrently.
  - Using multiple bulk inserts concurrently on the same client is supported.
  - Usage in an async context is also supported.

---

### Example

#### Create bulk insert

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

##### sync

```csharp
using (BulkInsertOperation bulkInsert = store.BulkInsert())
{
    for (int i = 0; i < 1000 * 1000; i++)
    {
        bulkInsert.Store(new Employee
        {
            FirstName = "FirstName #" + i,
            LastName = "LastName #" + i
        });
    }
}
```

##### async

```csharp
BulkInsertOperation bulkInsert = null;
try
{
    bulkInsert = store.BulkInsert();
    for (int i = 0; i < 1000 * 1000; i++)
    {
        await bulkInsert.StoreAsync(new Employee
        {
            FirstName = "FirstName #" + i,
            LastName = "LastName #" + i
        });
    }
}
finally
{
    if (bulkInsert != null)
    {
        await bulkInsert.DisposeAsync().ConfigureAwait(false);
    }
}
```

## BulkInsertOptions {#bulkinsertoptions}

The following options can be configured for BulkInsert.

### CompressionLevel

| Value | Type | Description |
| - | - | - |
| **Optimal** | `CompressionLevel` | Compression level to be used when compressing static files. |
| **Fastest**<br />(Default) | `CompressionLevel` | Compression level to be used when compressing HTTP responses with `GZip` or `Deflate`. |
| **NoCompression** | `CompressionLevel` | Does not compress. |

> **Info:** Default compression level {#default-compression-level}
>
> For RavenDB versions up to `6.2`, bulk-insert compression is Disabled (`NoCompression`) by default.  
> For RavenDB versions from `7.0` on, bulk-insert compression is Enabled (set to `Fastest`) by default.

---

### SkipOverwriteIfUnchanged

Use this option to avoid overwriting documents when the inserted document and the existing
one are similar.

Enabling this flag can exempt the server from many operations triggered by document-change,
like re-indexation and subscription or ETL-task updates.  
There is a slight potential cost in the additional comparison that has to be made between
the existing documents and the ones that are being inserted.

```csharp
using (var bulk = store.BulkInsert(new BulkInsertOptions
{
    SkipOverwriteIfUnchanged = true
}))
{
    // ...
}
```

## Track progress with OnProgress {#track-progress-with-onprogress}

A long-running bulk insert can take some time to complete. To track its progress -
for example, to show a progress bar or to log how many documents have been inserted
so far - subscribe to the `OnProgress` event.

The bulk insert delivers a progress snapshot to your handler each time the server
reports new progress, with counters such as `DocumentsProcessed`, `BatchCount`, and
the ID of the document processed most recently (`LastProcessedId`).  
See [Classes](#classes)
for the full property list.

- Updates arrive asynchronously over the
  [Changes](https://docs.ravendb.net/7.2/client-api/changes/what-is-changes-api.md)
  stream that the server opens for the operation.  
  Your handler is invoked by the server's progress reports, not by your `Store`
  calls - a single progress event typically covers many `Store` calls at once.
- The subscription opens after the first `Store` call. Attach the handler before
  storing anything to avoid missing early updates.
- Each snapshot is **cumulative** from the start of the bulk insert. `DocumentsProcessed`,
  `BatchCount`, `Total`, and the other counters grow over time and do not reset between
  events.  
  To find the number of documents added between two consecutive events, subtract the
  older snapshot's `DocumentsProcessed` from the newer one's. For example, if event A
  reports `DocumentsProcessed = 1000` and event B reports `DocumentsProcessed = 1500`,
  then 500 documents were added in the interval.

#### Example: Print progress to the console

```csharp
using (BulkInsertOperation bulkInsert = store.BulkInsert())
{
    // Attach the handler before the first Store call so early updates are not missed.
    bulkInsert.OnProgress += (sender, args) =>
    {
        // Each event carries a cumulative snapshot since the bulk insert started.
        Console.WriteLine(
            $"Processed {args.Progress.DocumentsProcessed} documents " +
            $"(last: {args.Progress.LastProcessedId})");
    };

    // Each employee inserted here advances the counters reported to the handler above.
    foreach (var employee in employees)
    {
        bulkInsert.Store(employee);
    }
}
```

## Syntax {#syntax}

### Method signatures

#### BulkInsert

Opens a bulk insert against the given database, or the document store's default database
when `database` is `null`.

```csharp
public BulkInsertOperation BulkInsert(
    string database = null,
    CancellationToken token = default);
```

Usage:

```csharp
using (var bulkInsert = store.BulkInsert())
{
    // ...
}
```

| Parameter | Type | Description |
| - | - | - |
| **database** | `string` | The name of the database to perform the bulk operation on.<br />If `null`, the `DocumentStore.Database` is used. |
| **token** | `CancellationToken` | Cancellation token used to halt the worker operation. |

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

#### BulkInsert (with options)

Opens a bulk insert against the given database with a
[`BulkInsertOptions`](#bulkinsertoptions)
instance to configure compression and overwrite behavior.

```csharp
public BulkInsertOperation BulkInsert(
    string database,
    BulkInsertOptions options,
    CancellationToken token = default);
```

Usage:

```csharp
using (var bulkInsert = store.BulkInsert("Northwind", new BulkInsertOptions
{
    SkipOverwriteIfUnchanged = true
}))
{
    // ...
}
```

| Parameter | Type | Description |
| - | - | - |
| **database** | `string` | The name of the database to perform the bulk operation on.<br />If `null`, the `DocumentStore.Database` is used. |
| **options** | `BulkInsertOptions` | [Options](#bulkinsertoptions) to configure BulkInsert. |
| **token** | `CancellationToken` | Cancellation token used to halt the worker operation. |

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

#### BulkInsert (options only)

Opens a bulk insert against the document store's default database with a
[`BulkInsertOptions`](#bulkinsertoptions)
instance to configure compression and overwrite behavior.

```csharp
public BulkInsertOperation BulkInsert(
    BulkInsertOptions options,
    CancellationToken token = default);
```

Usage:

```csharp
using (var bulkInsert = store.BulkInsert(new BulkInsertOptions
{
    SkipOverwriteIfUnchanged = true
}))
{
    // ...
}
```

| Parameter | Type | Description |
| - | - | - |
| **options** | `BulkInsertOptions` | [Options](#bulkinsertoptions) to configure BulkInsert. |
| **token** | `CancellationToken` | Cancellation token used to halt the worker operation. |

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

---

### Event signature

Raised while a bulk insert is running, each time the server reports new progress.
Each invocation carries a cumulative progress snapshot since the start of the
operation.

```csharp
public event EventHandler<BulkInsertOnProgressEventArgs> OnProgress;
```

Usage:

```csharp
bulkInsert.OnProgress += (sender, args) =>
{
    // Read args.Progress for the current snapshot.
};
```

---

### Classes

#### BulkInsertOnProgressEventArgs

The event arguments delivered to an `OnProgress` handler.

```csharp
public class BulkInsertOnProgressEventArgs : EventArgs
{
    public BulkInsertProgress Progress { get; }
}
```

| Property | Type | Description |
| - | - | - |
| **Progress** | `BulkInsertProgress` | The cumulative progress snapshot for this update. |

#### BulkInsertProgress

A cumulative snapshot of the bulk insert's progress, reported by the server.

```csharp
public class BulkInsertProgress
{
    public long Total { get; set; }
    public long BatchCount { get; set; }
    public string LastProcessedId { get; set; }
    public long DocumentsProcessed { get; set; }
    public long AttachmentsProcessed { get; set; }
    public long CountersProcessed { get; set; }
    public long TimeSeriesProcessed { get; set; }
}
```

| Property | Type | Description |
| - | - | - |
| **Total** | `long` | Total items processed since the bulk insert started, across documents, attachments, counters, and time series. |
| **BatchCount** | `long` | Number of server-side batches processed so far. |
| **LastProcessedId** | `string` | The identifier of the document that was processed most recently. |
| **DocumentsProcessed** | `long` | Number of documents inserted so far. |
| **AttachmentsProcessed** | `long` | Number of attachments stored so far. |
| **CountersProcessed** | `long` | Number of counters created or modified so far. |
| **TimeSeriesProcessed** | `long` | Number of time series entries appended so far. |

## See also

- [What is a Document Store](https://docs.ravendb.net/7.2/client-api/what-is-a-document-store.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.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.md)
- [What is the Changes API](https://docs.ravendb.net/7.2/client-api/changes/what-is-changes-api.md)
