> ## 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.

# BatchingSqlClient

> BatchingSqlClient — Kinetica Rust API

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

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

A SQL client that automatically batches INSERT statements for high-performance bulk loading.When you execute INSERT statements in a loop, this client accumulates them and automatically flushes through `BulkInserter<GenericRecord>` when the batch size is reached. This provides massive performance improvements over executing individual INSERT statements.

## Example

```rust theme={null}
use gpudb_api::{Kinetica, KineticaOptions, BatchingSqlClient};
use std::sync::Arc;

let kinetica = Arc::new(Kinetica::new(
    vec!["http://localhost:9191".to_string()],
    KineticaOptions::new()
).await?);

// Create batching client with 10000 record batch size
let mut client = BatchingSqlClient::new(kinetica, 10000, 8);

// Execute 1 million INSERT statements - they are automatically batched!
for i in 0..1_000_000 {
    client.execute(&format!(
        "INSERT INTO my_table (id, name, value) VALUES ({}, 'user_{}', {})",
        i, i, i as f64 * 1.5
    )).await?;
}

// Flush any remaining records
let stats = client.close().await?;
println!("Inserted {} records at {:.0} rec/sec",
    stats.records_inserted, stats.records_per_second);
```

## Implementations

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1777-L1920)
impl [BatchingSqlClient](https://docs.kinetica.com/content/api/rust/sql/struct.BatchingSqlClient.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1785-L1789)
pub 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)>, 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), ) -> Self

Create a new batching SQL client.

##### Arguments

<ul>
  <li>`kinetica` - The Kinetica client</li>
  <li>`batch_size` - Number of records to accumulate before flushing (recommended: 10000-50000)</li>
  <li>`num_workers` - Number of parallel workers for BulkInserter (recommended: 4-16)</li>
</ul>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1792-L1801)
pub 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)>, 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: [BulkInserterOptions](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserterOptions.md), ) -> Self

Create a batching client with custom options (e.g., upsert mode).

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1825-L1837)
pub fn [with\_hints](#method.with_hints)( 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)>, 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), hints: [SqlHints](https://docs.kinetica.com/content/api/rust/sql/struct.SqlHints.md), ) -> Self

Create a batching client with SQL hints.

##### Example

```rust theme={null}
use gpudb_api::{Kinetica, KineticaOptions, BatchingSqlClient, SqlHints};
use std::sync::Arc;

let kinetica = Arc::new(Kinetica::new(
    vec!["http://localhost:9191".to_string()],
    KineticaOptions::new()
).await?);

let hints = SqlHints::new()
    .update_on_existing_pk(true)
    .distributed_operations(true);

let mut client = BatchingSqlClient::with_hints(kinetica, 10000, 8, hints);
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1840-L1850)
pub fn [with\_options\_and\_hints](#method.with_options_and_hints)( 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)>, 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: [BulkInserterOptions](https://docs.kinetica.com/content/api/rust/bulk_inserter/struct.BulkInserterOptions.md), hints: [SqlHints](https://docs.kinetica.com/content/api/rust/sql/struct.SqlHints.md), ) -> Self

Create a batching client with both BulkInserter options and SQL hints.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1857-L1859)
pub fn [set\_hints](#method.set_hints)(\&mut self, hints: [SqlHints](https://docs.kinetica.com/content/api/rust/sql/struct.SqlHints.md))

Set SQL hints for non-INSERT statements.Note: For INSERT statements, hints like `update_on_existing_pk` are automatically applied through the BulkInserter options. Use `with_hints()` constructor to set both at creation time.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1862-L1864)
pub fn [hints](#method.hints)(\&self) -> &[SqlHints](https://docs.kinetica.com/content/api/rust/sql/struct.SqlHints.md)

Get the current SQL hints.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1876-L1891)
pub async fn [execute](#method.execute)(\&mut self, sql: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html)) -> [SqlOpResult](https://docs.kinetica.com/content/api/rust/sql/type.SqlOpResult.md)\<[Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[SqlResult](https://docs.kinetica.com/content/api/rust/sql/struct.SqlResult.md)>>

Execute a SQL statement.

<ul>
  <li>INSERT statements are accumulated and batched automatically</li>
  <li>Other statements (SELECT, CREATE, etc.) are executed immediately with hints applied</li>
</ul>

When the batch size is reached, records are automatically flushed through `BulkInserter<GenericRecord>` with shard-aware routing.For non-INSERT statements, any configured SQL hints (via `set_hints()` or `with_hints()`) will be applied to the execute\_sql request.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1894-L1896)
pub async fn [flush](#method.flush)(\&mut self) -> [SqlOpResult](https://docs.kinetica.com/content/api/rust/sql/type.SqlOpResult.md)\<[()](https://doc.rust-lang.org/1.98.1/std/primitive.unit.html)>

Flush all pending records for all tables.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1901-L1904)
pub async fn [close](#method.close)(self) -> [SqlOpResult](https://docs.kinetica.com/content/api/rust/sql/type.SqlOpResult.md)\<[BatchingStats](https://docs.kinetica.com/content/api/rust/sql/struct.BatchingStats.md)>

Flush all pending records and return final statistics.This should be called when you’re done inserting to ensure all records are flushed.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1907-L1909)
pub fn [stats](#method.stats)(\&self) -> [BatchingStats](https://docs.kinetica.com/content/api/rust/sql/struct.BatchingStats.md)

Get current statistics without closing.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1912-L1914)
pub fn [pending\_count](#method.pending_count)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Get the number of pending (unflushed) records across all tables.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1917-L1919)
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)>

Get a reference to the underlying Kinetica client.


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