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

# SqlClient

> SqlClient — 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#L1132-L1138)&#x20;

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

High-level SQL client that wraps Kinetica with result parsing.`SqlClient` executes SQL through Kinetica’s `/execute/sql` endpoint and returns [`SqlResult`](https://docs.kinetica.com/content/api/rust/sql/struct.SqlResult)s, with helpers for paging through large result sets.

## Example

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let options = KineticaOptions::new();
    let kinetica = Arc::new(
        Kinetica::new(vec!["http://localhost:9191".to_string()], options).await?
    );

    let client = SqlClient::new(kinetica);

    // Execute a SELECT query
    let result = client.execute("SELECT * FROM my_table LIMIT 10").await?;
    println!("Found {} records", result.total_records());

    // Fetch a specific page
    let page = client.execute_paged("SELECT * FROM my_table ORDER BY id", 100, 50).await?;

    Ok(())
}
```

## Implementations

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

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

Create a new SqlClient wrapping a Kinetica instance

##### Example

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

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

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1166-L1172)
pub fn [with\_defaults](#method.with_defaults)( 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)>, encoding: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), limit: [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html), ) -> Self

Create a SqlClient with custom defaults

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

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1192-L1194)
pub async fn [execute](#method.execute)(\&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)\<[SqlResult](https://docs.kinetica.com/content/api/rust/sql/struct.SqlResult.md)>

Execute a raw SQL string

##### Example

```rust theme={null}
use gpudb_api::SqlClient;

let mut result = client.execute("SELECT COUNT(*) FROM users WHERE active = true").await?;
let count: i64 = result.scalar()?;
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1209-L1211)
pub async fn [execute\_paged](#method.execute_paged)( \&self, sql: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), offset: [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html), limit: [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html), ) -> [SqlOpResult](https://docs.kinetica.com/content/api/rust/sql/type.SqlOpResult.md)\<[SqlResult](https://docs.kinetica.com/content/api/rust/sql/struct.SqlResult.md)>

Execute a raw SQL string with custom limit and offset

##### Example

```rust theme={null}
use gpudb_api::SqlClient;

// Get records 10-19
let result = client.execute_paged("SELECT * FROM users", 10, 10).await?;
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1234-L1252)
pub async fn [execute\_with\_options](#method.execute_with_options)( \&self, sql: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), offset: [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html), limit: [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html), options: [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)>>, ) -> [SqlOpResult](https://docs.kinetica.com/content/api/rust/sql/type.SqlOpResult.md)\<[SqlResult](https://docs.kinetica.com/content/api/rust/sql/struct.SqlResult.md)>

Execute SQL with full control over options

##### Example

```rust theme={null}
use gpudb_api::SqlClient;
use std::collections::HashMap;

let mut options = HashMap::new();
options.insert("parallel_execution".to_string(), "true".to_string());

let result = client.execute_with_options(
    "SELECT * FROM large_table",
    0,
    1000,
    Some(options)
).await?;
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1293-L1302)
pub async fn [fetch\_next\_page](#method.fetch_next_page)( \&self, paging\_table: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), offset: [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html), limit: [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html), ) -> [SqlOpResult](https://docs.kinetica.com/content/api/rust/sql/type.SqlOpResult.md)\<[SqlResult](https://docs.kinetica.com/content/api/rust/sql/struct.SqlResult.md)>

Fetch the next page of results using a paging tableWhen a query returns `has_more_records = true`, Kinetica creates a temporary paging table containing the full result set. Use this method to fetch subsequent pages from that paging table.

##### Arguments

<ul>
  <li>`paging_table` - The paging table name from `SqlResult::paging_table()`</li>
  <li>`offset` - The offset within the paging table to start fetching from</li>
  <li>`limit` - The maximum number of records to fetch</li>
</ul>

##### Example

```rust theme={null}
use gpudb_api::SqlClient;

// Initial query with a limit
let mut result = client.execute_paged("SELECT * FROM large_table", 0, 1000).await?;
let mut all_rows = result.rows()?.to_vec();

// Fetch remaining pages if there are more records
let paging_table = result.paging_table().map(|s| s.to_string());
if let Some(pt) = paging_table {
    let mut offset = 1000i64;
    while result.has_more() {
        result = client.fetch_next_page(&pt, offset, 1000).await?;
        all_rows.extend(result.rows()?.to_vec());
        offset += 1000;
    }
}
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1336-L1403)
pub async fn [execute\_all](#method.execute_all)( \&self, sql: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), page\_size: [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html), ) -> [SqlOpResult](https://docs.kinetica.com/content/api/rust/sql/type.SqlOpResult.md)\<[SqlResult](https://docs.kinetica.com/content/api/rust/sql/struct.SqlResult.md)>

Execute a query and iterate through all pages automaticallyThis method handles pagination transparently, fetching all pages from the paging table and returning an iterator over all results.**Warning**: This loads all results into memory. For very large result sets, consider using `execute_paged` and `fetch_next_page` to process results in batches.

##### Arguments

<ul>
  <li>`sql` - The SQL query to execute</li>
  <li>`page_size` - The number of records to fetch per page</li>
</ul>

##### Example

```rust theme={null}
use gpudb_api::SqlClient;

// Fetch all records, 10000 at a time
let mut result = client.execute_all("SELECT * FROM large_table", 10000).await?;

println!("Total records fetched: {}", result.row_count()?);

for row in result.rows()? {
    let id: i64 = row.get("column_1")?;
    // Process each row...
}
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1439-L1497)

#### pub async fn [execute\_paginated](#method.execute_paginated)\<F>( \&self, sql: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), page\_size: [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html), callback: F, ) ->[SqlOpResult](https://docs.kinetica.com/content/api/rust/sql/type.SqlOpResult.md)\<[PaginationStats](https://docs.kinetica.com/content/api/rust/sql/struct.PaginationStats.md)>&#xA;where F: [FnMut](https://doc.rust-lang.org/1.98.1/core/ops/function/trait.FnMut.html)([SqlResult](https://docs.kinetica.com/content/api/rust/sql/struct.SqlResult.md), [u64](https://doc.rust-lang.org/1.98.1/std/primitive.u64.html)) -> [SqlOpResult](https://docs.kinetica.com/content/api/rust/sql/type.SqlOpResult.md)\<[bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)>,

Execute a query and process results page by page with a callbackThis is the most memory-efficient way to process large result sets, as it only loads one page at a time.

##### Arguments

<ul>
  <li>`sql` - The SQL query to execute</li>
  <li>`page_size` - The number of records to fetch per page</li>
  <li>`callback` - A function called for each page of results</li>
</ul>

##### Example

```rust theme={null}
use gpudb_api::SqlClient;

let mut total_processed = 0u64;

client.execute_paginated(
    "SELECT * FROM large_table",
    10000,
    |mut page, page_num| {
        println!("Processing page {}", page_num);
        for row in page.rows()? {
            let id: i64 = row.get("column_1")?;
            // Process row...
        }
        Ok(true) // Return false to stop pagination early
    }
).await?;
```

## Trait Implementations

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1131)
impl [Clone](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html) for [SqlClient](https://docs.kinetica.com/content/api/rust/sql/struct.SqlClient.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/sql.rs#L1131)
fn [clone](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#tymethod.clone)(\&self) -> [SqlClient](https://docs.kinetica.com/content/api/rust/sql/struct.SqlClient.md)

Returns a duplicate of the value. [Read more](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#tymethod.clone)

1.0.0 (const: [unstable](https://github.com/rust-lang/rust/issues/142757)) · [Source](https://doc.rust-lang.org/1.98.1/src/core/clone.rs.html#245-247)
fn [clone\_from](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#method.clone_from)(\&mut self, source: \&Self)

Performs copy-assignment from `source`. [Read more](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#method.clone_from)


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