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

# BatchingSqlxClient

> BatchingSqlxClient — Kinetica Rust API

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

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

A SQLx client that automatically batches INSERT statements and routes them through `BulkInserter<GenericRecord>` for high-performance shard-aware ingestion.This client intercepts INSERT statements executed in a loop, accumulates them, and flushes them through the high-performance `BulkInserter` when the batch size is reached. Non-INSERT statements are executed immediately via SQLx.

## Features

<ul>
  <li>**Auto-batching**: INSERT statements are automatically accumulated</li>
  <li>**Shard-aware routing**: Uses `BulkInserter<GenericRecord>` for multi-head ingest</li>
  <li>**Mixed statements**: SELECT, CREATE, etc. work normally alongside INSERTs</li>
  <li>**Performance**: Achieves high throughput for bulk INSERT operations</li>
</ul>

## Example

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

// The SQLx pool for other statements, and the HTTP API client INSERT
// batches are flushed through
let pool = connect("localhost", "admin", "password").await?;
let mut options = KineticaOptions::new();
options.set_username("admin").set_password("password");
let kinetica = Arc::new(Kinetica::new(vec!["http://localhost:9191".to_string()], options).await?);

let mut client = BatchingSqlxClient::new(pool, kinetica, 10000, 8);

// Execute INSERT statements in a loop - they get auto-batched
for i in 0..100000 {
    client.execute(&format!(
        "INSERT INTO my_table (id, value) VALUES ({}, {})", i, i * 10
    )).await?;
}

// Flush remaining records and get stats
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/sqlx_support.rs#L1251-L1405)
impl [BatchingSqlxClient](https://docs.kinetica.com/content/api/rust/sqlx_support/struct.BatchingSqlxClient.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sqlx_support.rs#L1260-L1272)
pub fn [new](#method.new)( pool: [KineticaPool](https://docs.kinetica.com/content/api/rust/sqlx_support/type.KineticaPool.md), 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 SQLx client.

##### Arguments

<ul>
  <li>`pool` - SQLx PostgreSQL connection pool, for statements other than INSERT</li>
  <li>`kinetica` - The Kinetica HTTP API client INSERT batches are flushed through</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/sqlx_support.rs#L1275-L1288)
pub fn [with\_options](#method.with_options)( pool: [KineticaPool](https://docs.kinetica.com/content/api/rust/sqlx_support/type.KineticaPool.md), 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/sqlx_support.rs#L1313-L1328)
pub fn [with\_hints](#method.with_hints)( pool: [KineticaPool](https://docs.kinetica.com/content/api/rust/sqlx_support/type.KineticaPool.md), 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::sqlx_support::{BatchingSqlxClient, connect};
use gpudb_api::{Kinetica, KineticaOptions, SqlHints};
use std::sync::Arc;

let pool = connect("localhost", "admin", "password").await?;
let mut options = KineticaOptions::new();
options.set_username("admin").set_password("password");
let kinetica = Arc::new(Kinetica::new(vec!["http://localhost:9191".to_string()], options).await?);

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

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

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sqlx_support.rs#L1331-L1343)
pub fn [with\_options\_and\_hints](#method.with_options_and_hints)( pool: [KineticaPool](https://docs.kinetica.com/content/api/rust/sqlx_support/type.KineticaPool.md), 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/sqlx_support.rs#L1349-L1351)
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 the client.Note: For INSERT statements, hints like `update_on_existing_pk` are automatically applied through the BulkInserter options.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sqlx_support.rs#L1354-L1356)
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/sqlx_support.rs#L1365-L1376)
pub async fn [execute](#method.execute)( \&mut self, sql: &[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)\<[Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[Vec](https://doc.rust-lang.org/1.98.1/alloc/vec/struct.Vec.html)\<PgRow>>, [BatchingSqlxError](https://docs.kinetica.com/content/api/rust/sqlx_support/enum.BatchingSqlxError.md)>

Execute a SQL statement.

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

When the batch size is reached, records are automatically flushed through `BulkInserter<GenericRecord>` with shard-aware routing.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sqlx_support.rs#L1379-L1381)
pub async fn [flush](#method.flush)(\&mut 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), [BatchingSqlxError](https://docs.kinetica.com/content/api/rust/sqlx_support/enum.BatchingSqlxError.md)>

Flush all pending records for all tables.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sqlx_support.rs#L1386-L1389)
pub async fn [close](#method.close)(self) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[BatchingSqlxStats](https://docs.kinetica.com/content/api/rust/sqlx_support/struct.BatchingSqlxStats.md), [BatchingSqlxError](https://docs.kinetica.com/content/api/rust/sqlx_support/enum.BatchingSqlxError.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/sqlx_support.rs#L1392-L1394)
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/sqlx_support.rs#L1397-L1399)
pub fn [stats](#method.stats)(\&self) -> [BatchingSqlxStats](https://docs.kinetica.com/content/api/rust/sqlx_support/struct.BatchingSqlxStats.md)

Get current statistics without closing.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sqlx_support.rs#L1402-L1404)
pub fn [pool](#method.pool)(\&self) -> &[KineticaPool](https://docs.kinetica.com/content/api/rust/sqlx_support/type.KineticaPool.md)

Get a reference to the SQLx pool for direct queries.


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