> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinetica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# BulkInserter

> BulkInserter — Kinetica Rust API

[gpudb\_api](https://docs.kinetica.com/content/api/rust/index.md)::<wbr />[bulk\_inserter](https://docs.kinetica.com/content/api/rust/bulk_inserter/index.md)
[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L1101-L1277)&#x20;

<pre>`pub struct BulkInserter<T> { /* private fields */ }`</pre>

Shard-aware high-performance bulk inserter.Routes records to the correct worker based on shard key computation, enabling true multi-head ingest. Uses `serde_avro_fast` for fast Avro encoding and rayon for parallel processing.It also provides:

<ul>
  <li>Support for insert options (update\_on\_existing\_pk, etc.)</li>
  <li>Permission checking before insertion</li>
  <li>Table replication detection (replicated tables use head node only)</li>
  <li>Multi-head ingest configuration</li>
  <li>Retry logic with configurable max retries</li>
</ul>

## HA Failover Safety

This implementation uses `ArcSwap` for lock-free atomic updates of routing state during HA failover. This ensures:

<ul>
  <li>No race conditions when routing table changes during insert operations</li>
  <li>No out-of-bounds indexing from stale routing data</li>
  <li>Records are always routed using consistent, up-to-date routing information</li>
</ul>

## Implementations

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L1280-L1340)
impl\<T: [Serialize](https://docs.rs/serde_core/1.0.228/serde_core/ser/trait.Serialize.html) + [KineticaRecord](https://docs.kinetica.com/content/api/rust/trait.KineticaRecord.md) + [ShardKeyExtractor](https://docs.kinetica.com/content/api/rust/bulk_inserter_common/trait.ShardKeyExtractor.md) + [Send](https://doc.rust-lang.org/1.98.1/core/marker/trait.Send.html) + [Sync](https://doc.rust-lang.org/1.98.1/core/marker/trait.Sync.html) + 'static + [Default](https://doc.rust-lang.org/1.98.1/core/default/trait.Default.html)> [BulkInserter](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter.md)\<T>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L1294-L1301)
pub async fn [new](#method.new)( kinetica: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>, table\_name: [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), batch\_size: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html), num\_workers: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html), ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<Self>, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Creates a new shard-aware BulkInserter instance with default options.This is a convenience method that calls `with_options` with `None` for options. For more control over insert behavior, use `with_options` directly.

##### Arguments

<ul>
  <li>`kinetica` - Shared Kinetica client</li>
  <li>`table_name` - Target table for inserts (including schema, e.g., “my\_schema.my\_table”)</li>
  <li>`batch_size` - Records per batch (recommended: 50000)</li>
  <li>`num_workers` - Number of flush workers, i.e. of batches sent concurrently; used exactly as given. `0` sizes the pool at one worker per available CPU.</li>
</ul>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L1329-L1339)
pub async fn [with\_options](#method.with_options)( kinetica: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>, table\_name: [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), batch\_size: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html), num\_workers: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html), options: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[BulkInserterOptions](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserterOptions.md)>, ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<Self>, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Creates a new shard-aware BulkInserter instance with the specified options.This constructor:

<ol>
  <li>Validates user permissions for the table</li>
  <li>Validates batch size</li>
  <li>Checks if the table is replicated</li>
  <li>Configures multi-head ingest (if available and table is not replicated)</li>
  <li>Sets up worker queues and routing</li>
</ol>

##### Arguments

<ul>
  <li>`kinetica` - Shared Kinetica client</li>
  <li>`table_name` - Target table for inserts (including schema, e.g., “my\_schema.my\_table”)</li>
  <li>`batch_size` - Records per batch (recommended: 50000); must be > 0</li>
  <li>`num_workers` - Number of flush workers, i.e. of batches sent concurrently; used exactly as given. `0` sizes the pool at one worker per available CPU.</li>
  <li>`options` - Optional BulkInserterOptions for configuring insert behavior</li>
</ul>

##### Errors

Returns an error if:

<ul>
  <li>User doesn’t have required permissions (insert, and update if using upsert)</li>
  <li>Table doesn’t exist</li>
  <li>Batch size is less than 1</li>
  <li>Unable to configure multi-head ingest</li>
</ul>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L1343-L1392)
impl\<T: [Serialize](https://docs.rs/serde_core/1.0.228/serde_core/ser/trait.Serialize.html) + [KineticaRecord](https://docs.kinetica.com/content/api/rust/trait.KineticaRecord.md) + [ShardKeyExtractor](https://docs.kinetica.com/content/api/rust/bulk_inserter_common/trait.ShardKeyExtractor.md) + [Send](https://doc.rust-lang.org/1.98.1/core/marker/trait.Send.html) + [Sync](https://doc.rust-lang.org/1.98.1/core/marker/trait.Sync.html) + 'static> [BulkInserter](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter.md)\<T>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L1382-L1391)
pub async fn [with\_schema](#method.with_schema)( kinetica: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>, table\_name: [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), batch\_size: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html), num\_workers: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html), options: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[BulkInserterOptions](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserterOptions.md)>, schema\_str: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<Self>, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Creates a new shard-aware BulkInserter instance with an explicit schema.This constructor is useful for types that cannot implement `Default`, such as `GenericRecord` which requires a `Type` reference at construction time.

##### Arguments

<ul>
  <li>`kinetica` - Shared Kinetica client</li>
  <li>`table_name` - Target table for inserts (including schema, e.g., “my\_schema.my\_table”)</li>
  <li>`batch_size` - Records per batch (recommended: 50000); must be > 0</li>
  <li>`num_workers` - Number of flush workers, i.e. of batches sent concurrently; used exactly as given. `0` sizes the pool at one worker per available CPU.</li>
  <li>`options` - Optional BulkInserterOptions for configuring insert behavior</li>
  <li>`schema_str` - The Avro schema JSON string for the record type</li>
</ul>

##### Example

```rust theme={null}
use gpudb_api::{BulkInserter, GenericRecord, Type};

let record_type = Arc::new(Type::from_table(&kinetica, "my_table").await?);
let schema_str = record_type.schema_string();

let inserter = BulkInserter::<GenericRecord>::with_schema(
    kinetica,
    "my_table".into(),
    50000,
    8,
    None,
    schema_str,
).await?;
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L1401-L1427)
impl [BulkInserter](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter.md)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>

An inserter of JSON records.

Each record is one JSON object, as text. Records are sent as JSON arrays to the ranks’ `/insert/records/json`, each to the rank of a random shard: the client does not read their keys. A batch the server fails is reported as any other, through [`drain_errors`](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter#method.drain_errors), and one that meets a connection failure is retried and failed over like any other.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L1405-L1412)
pub async fn [new\_json](#method.new_json)( kinetica: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>, table\_name: [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), batch\_size: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html), num\_workers: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html), ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<Self>, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Creates a JSON inserter with the default [`JsonOptions`](https://docs.kinetica.com/content/api/rust/json_records/struct.JsonOptions) and options.`num_workers` is as for [`BulkInserter::with_schema`](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter#method.with_schema).

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L1416-L1426)
pub async fn [with\_json\_options](#method.with_json_options)( kinetica: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>, table\_name: [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), batch\_size: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html), num\_workers: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html), options: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[BulkInserterOptions](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserterOptions.md)>, json\_options: [JsonOptions](https://docs.kinetica.com/content/api/rust/json_records/struct.JsonOptions.md), ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<Self>, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Creates a JSON inserter. With [`JsonOptions::is_validate_json`](https://docs.kinetica.com/content/api/rust/json_records/struct.JsonOptions#method.is_validate_json), each record inserted must be a JSON object.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L1430-L3608)
impl\<T: [Serialize](https://docs.rs/serde_core/1.0.228/serde_core/ser/trait.Serialize.html) + [ShardKeyExtractor](https://docs.kinetica.com/content/api/rust/bulk_inserter_common/trait.ShardKeyExtractor.md) + [Send](https://doc.rust-lang.org/1.98.1/core/marker/trait.Send.html) + [Sync](https://doc.rust-lang.org/1.98.1/core/marker/trait.Sync.html) + 'static> [BulkInserter](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter.md)\<T>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L1970-L1975)
pub fn [insert](#method.insert)(\&self, record: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<T>) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[()](https://doc.rust-lang.org/1.98.1/std/primitive.unit.html), [QueueError](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.QueueError.md)\<T>>

Inserts a single record with shard-aware routing.The record’s shard key is computed using `ShardKeyExtractor::shard_key_values()`, and the record is routed to the worker that owns the corresponding shard.

##### Errors

Returns an error if the record cannot be routed — see [`Self::route_to_worker`](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter#method.route_to_worker). The record is not queued in that case, and comes back in the [`QueueError`](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.QueueError).Also returns an error after [`close`](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter#method.close) when this record fills a batch: the batch cannot be sent, and its records come back.

##### HA Failover Safety

This method uses `ArcSwap::load()` to get the current routing state, which provides:

<ul>
  <li>Lock-free atomic read of the routing configuration</li>
  <li>Consistent routing even during HA failover (no torn reads)</li>
  <li>No race conditions with concurrent routing updates</li>
</ul>

A JSON inserter whose [`JsonOptions`](https://docs.kinetica.com/content/api/rust/json_records/struct.JsonOptions) ask for it first checks that the record is a JSON object.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2057-L2094)
pub async fn [insert\_with\_backpressure](#method.insert_with_backpressure)( \&self, record: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<T>, ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[()](https://doc.rust-lang.org/1.98.1/std/primitive.unit.html), [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Inserts a single record with backpressure control.This async method will wait if the maximum in-flight batches limit is reached, providing memory-bounded operation for high-throughput scenarios.

##### HA Failover Safety

This method uses `ArcSwap::load()` to get the current routing state atomically.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2145-L2160)
pub fn [insert\_batch](#method.insert_batch)(\&self, records: [Vec](https://doc.rust-lang.org/1.98.1/alloc/vec/struct.Vec.html)\<T>) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[()](https://doc.rust-lang.org/1.98.1/std/primitive.unit.html), [QueueError](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.QueueError.md)\<T>>

Inserts a batch of records with shard-aware routing.This method is more efficient than calling `insert()` in a loop because:

<ol>
  <li>Worker indices are computed in parallel using rayon</li>
  <li>Records are grouped by destination before any lock is taken</li>
  <li>Each destination’s queue is locked once per call, not once per record</li>
</ol>

The records go into the calling thread’s stripe of each queue, as `insert` puts them, and a batch is sent each time that stripe reaches the batch size. No batch is larger than the batch size.

##### Arguments

<ul>
  <li>`records` - A vector of records to insert. Each record will be wrapped in Arc internally.</li>
</ul>

##### Errors

The records before the first that cannot be routed are queued, and that record and every one after it come back in the [`QueueError`](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.QueueError) with its error. A list whose JSON does not validate is not queued at all, and comes back whole.

##### Example

```rust theme={null}
let records: Vec<MyRecord> = (0..100_000)
    .map(|i| MyRecord { id: i, name: format!("name_{}", i) })
    .collect();
inserter.insert_batch(records)?;
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2169-L2184)
pub fn [insert\_batch\_arc](#method.insert_batch_arc)( \&self, records: [Vec](https://doc.rust-lang.org/1.98.1/alloc/vec/struct.Vec.html)\<[Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<T>>, ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[()](https://doc.rust-lang.org/1.98.1/std/primitive.unit.html), [QueueError](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.QueueError.md)\<T>>

Inserts a batch of records that are already wrapped in Arc.This is useful when records are shared or when the caller already has Arc-wrapped records.

##### Arguments

<ul>
  <li>`records` - A vector of Arc-wrapped records to insert.</li>
</ul>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2737-L2739)
pub fn [count\_inserted](#method.count_inserted)(\&self) -> [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html)

Returns the total number of records successfully inserted.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2742-L2744)
pub fn [count\_updated](#method.count_updated)(\&self) -> [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html)

Returns the total number of records successfully updated (for upserts).

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2747-L2749)
pub fn [table\_name](#method.table_name)(\&self) -> &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html)

Returns the table name.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2752-L2754)
pub fn [batch\_size](#method.batch_size)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the batch size.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2757-L2759)
pub fn [is\_table\_replicated](#method.is_table_replicated)(\&self) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Returns whether the target table is replicated.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2762-L2764)
pub fn [is\_multi\_head\_enabled](#method.is_multi_head_enabled)(\&self) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Returns whether multi-head ingest is enabled.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2767-L2769)
pub fn [is\_using\_head\_node](#method.is_using_head_node)(\&self) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Returns whether the head node is being used (replicated table or multi-head disabled).

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2772-L2774)
pub fn [max\_retries](#method.max_retries)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the current maximum retries for failed insertions.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2777-L2779)
pub fn [set\_max\_retries](#method.set_max_retries)(\&self, max\_retries: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html))

Sets the maximum retries for failed insertions.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2782-L2784)
pub fn [options](#method.options)(\&self) -> [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<&[HashMap](https://doc.rust-lang.org/1.98.1/std/collections/hash/map/struct.HashMap.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>>

Returns a reference to the insert options.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2787-L2789)
pub fn [json\_options](#method.json_options)(\&self) -> [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[JsonOptions](https://docs.kinetica.com/content/api/rust/json_records/struct.JsonOptions.md)>

The JSON options of a JSON inserter, or those set since.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2793-L2795)
pub fn [set\_json\_options](#method.set_json_options)(\&self, json\_options: [JsonOptions](https://docs.kinetica.com/content/api/rust/json_records/struct.JsonOptions.md))

Replaces the JSON options, which a JSON inserter reads for each record it is given. They do not make an inserter of Avro records a JSON one.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2798-L2800)
pub fn [flush\_options](#method.flush_options)(\&self) -> [FlushOptions](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.FlushOptions.md)

Returns the flush options.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2803-L2805)
pub fn [timed\_flush\_options](#method.timed_flush_options)(\&self) -> [FlushOptions](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.FlushOptions.md)

The timed flush options.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2811-L2819)
pub fn [set\_timed\_flush\_options](#method.set_timed_flush_options)( self: &[Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<Self>, flush\_options: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[FlushOptions](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.FlushOptions.md)>, )

Replaces the timed flush options, `None` restoring the defaults (no timed flush), and restarts the timed flush with them. A scheduled timed flush is stopped first, and a new one starts if the new interval is positive, its first run one interval from now.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2875-L2877)
pub fn [is\_return\_individual\_errors](#method.is_return_individual_errors)(\&self) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Returns whether return\_individual\_errors mode is active.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2883-L2892)
pub fn [buffered\_record\_count](#method.buffered_record_count)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the number of records currently buffered in worker queues.These are records that have been queued via `insert()` but not yet sent to the flush workers. Call `flush()` to send these records.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2898-L2900)
pub fn [in\_flight\_record\_estimate](#method.in_flight_record_estimate)(\&self) -> [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html)

Returns the estimated number of records in-flight (sent but not yet confirmed).This is an estimate based on pending\_batches \* batch\_size. The actual number may be slightly different due to partial batches.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2907-L2909)
pub fn [kinetica](#method.kinetica)(\&self) -> &[Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>

The connection this inserter sends through.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2913-L2916)
pub fn [drain\_errors](#method.drain_errors)(\&self) -> [Vec](https://doc.rust-lang.org/1.98.1/alloc/vec/struct.Vec.html)\<[InsertError](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.InsertError.md)\<T>>

Drains and returns all queued errors. This clears the error queue, so subsequent calls return new errors only.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2919-L2921)
pub fn [error\_count](#method.error_count)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the number of queued errors without draining.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2925-L2927)
pub fn [failed\_record\_count](#method.failed_record_count)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the total number of records that failed to insert. This sums the record\_count from all errors in the queue.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2930-L2933)
pub fn [drain\_warnings](#method.drain_warnings)(\&self) -> [Vec](https://doc.rust-lang.org/1.98.1/alloc/vec/struct.Vec.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>

Drains and returns all queued warnings.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2936-L2938)
pub fn [warning\_count](#method.warning_count)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the number of queued warnings without draining.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2941-L2943)
pub fn [is\_timed\_flush\_running](#method.is_timed_flush_running)(\&self) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Returns whether timed flush is currently running.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2946-L2948)
pub fn [stop\_timed\_flush](#method.stop_timed_flush)(\&self)

Stops the timed flush task.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2951-L2953)
pub fn [max\_in\_flight\_batches](#method.max_in_flight_batches)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the maximum number of in-flight batches configured.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2956-L2958)
pub fn [available\_in\_flight\_permits](#method.available_in_flight_permits)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the number of available in-flight permits.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L2977-L2997)
pub fn [backpressure\_metrics](#method.backpressure_metrics)(\&self) -> [BackpressureMetrics](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BackpressureMetrics.md)

Returns backpressure metrics for monitoring.This provides visibility into the backpressure state of the inserter, useful for monitoring and tuning `max_in_flight_batches`.

##### Example

```rust theme={null}
let metrics = inserter.backpressure_metrics();
println!("In-flight: {}/{} ({:.1}% utilized)",
    metrics.in_flight_batches,
    metrics.max_in_flight_batches,
    metrics.utilization_pct
);
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3017-L3021)
pub async fn [flush](#method.flush)(\&self) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[()](https://doc.rust-lang.org/1.98.1/std/primitive.unit.html), [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Flushes all buffered records to the server and waits until they have been acknowledged.When this returns `Ok(())`, every record queued before the call has either been inserted or recorded in the error queue — so a subsequent read is guaranteed to see them.Check [`error_count`](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter#method.error_count) or [`drain_errors`](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter#method.drain_errors) afterwards to see whether any records failed; a returned `Ok` means “all batches finished”, not “all batches succeeded”.Use [`flush_no_wait`](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter#method.flush_no_wait) if you deliberately want to hand the batches off without waiting.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3030-L3035)
pub async fn [flush\_no\_wait](#method.flush_no_wait)(\&self) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[()](https://doc.rust-lang.org/1.98.1/std/primitive.unit.html), [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Hands all buffered records to the flush workers without waiting for them to complete.Prefer [`flush`](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter#method.flush) — after this returns, the records have not necessarily reached the server, so reading the table back may not see them. This exists for background flushing (the timed-flush task uses it) where blocking would stall the caller.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3112-L3114)
pub fn [pending\_batches](#method.pending_batches)(\&self) -> [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html)

Returns the number of pending batches (sent but not yet completed).

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3138-L3164)
pub async fn [close](#method.close)(\&self) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[()](https://doc.rust-lang.org/1.98.1/std/primitive.unit.html), [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Closes the BulkInserter, flushing all records and waiting for completion.This method:

<ol>
  <li>Flushes all buffered records to the flush workers</li>
  <li>Waits for all pending batches to complete</li>
  <li>Stops the flush workers and the timed flush</li>
</ol>

The inserter cannot send anything afterwards: an insert still buffers, but one that fills a batch, or a `flush()` with records buffered, fails.**IMPORTANT**: This method will wait indefinitely until all pending batches complete. It only returns when:

<ol>
  <li>All records have been successfully inserted, OR</li>
  <li>All records have either succeeded or failed (with errors queued)</li>
</ol>

Failed records are tracked in the error queue and can be retrieved via `drain_errors()`. The method guarantees that `inserted + updated + failed = queued`.

##### Returns

Returns `Ok(())` when all batches have completed (success or failure). Check `error_count()` or `drain_errors()` to see if any records failed.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3178-L3220)
pub async fn [close\_with\_timeout](#method.close_with_timeout)( \&self, timeout: [Duration](https://doc.rust-lang.org/1.98.1/core/time/struct.Duration.html), ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[()](https://doc.rust-lang.org/1.98.1/std/primitive.unit.html), [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Closes the BulkInserter with an optional timeout.If timeout is reached, returns an error but records may still be in-flight. **Prefer using `close()` without timeout to ensure all records are flushed.**

##### Arguments

<ul>
  <li>`timeout` - Maximum time to wait for pending batches to complete</li>
</ul>

##### Returns

Returns `Ok(())` if all batches completed, or `Err` if timeout was reached.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3227-L3229)
pub fn [shard\_column\_count](#method.shard_column_count)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the number of shard key columns used for routing.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3232-L3236)
pub fn [shard\_column\_names](#method.shard_column_names)(\&self) -> [Vec](https://doc.rust-lang.org/1.98.1/alloc/vec/struct.Vec.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>

Returns the names of shard key columns.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3239-L3241)
pub fn [routing\_table\_size](#method.routing_table_size)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the routing table size (number of shards).

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3244-L3246)
pub fn [worker\_count](#method.worker_count)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the number of worker queues.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3254-L3256)
pub fn [num\_cluster\_switches](#method.num_cluster_switches)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the number of times the connection has switched clusters due to failover.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3259-L3261)
pub fn [ha\_ring\_size](#method.ha_ring_size)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the current HA ring size (number of clusters).

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3264-L3266)
pub fn [current\_head\_node\_url](#method.current_head_node_url)(\&self) -> [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[Url](https://docs.rs/url/2.5.7/url/struct.Url.html)>

Returns the current head node URL.

## Trait Implementations

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3614-L3634)
impl\<T> [Drop](https://doc.rust-lang.org/1.98.1/core/ops/drop/trait.Drop.html) for [BulkInserter](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserter.md)\<T>

Dropping an inserter stops its background tasks (they hold only `Weak` references, and the shutdown sender goes with it), so nothing leaks. It cannot flush, since that is asynchronous: records still buffered, or queued but not yet sent, are lost. Say so, rather than lose them silently.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/bulk_inserter.rs#L3615-L3633)
fn [drop](https://doc.rust-lang.org/1.98.1/core/ops/drop/trait.Drop.html#method.drop)(\&mut self)

Executes the destructor for this type. [Read more](https://doc.rust-lang.org/1.98.1/core/ops/drop/trait.Drop.html#method.drop)

[Source](https://doc.rust-lang.org/1.98.1/src/core/ops/drop.rs.html#267)
fn [pin\_drop](https://doc.rust-lang.org/1.98.1/core/ops/drop/trait.Drop.html#method.pin_drop)(self: [Pin](https://doc.rust-lang.org/1.98.1/core/pin/struct.Pin.html)\<\&mut Self>)

🔬This is a nightly-only experimental API. (`pin_ergonomics`)
Execute the destructor for this type, but different to [`Drop::drop`](https://doc.rust-lang.org/1.98.1/core/ops/drop/trait.Drop.html#method.drop), it requires `self` to be pinned. [Read more](https://doc.rust-lang.org/1.98.1/core/ops/drop/trait.Drop.html#method.pin_drop)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.