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

# Overview

> Overview — Kinetica Rust API

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/lib.rs#L1-L328) 

## GPUdb API Rust Client

A high-performance, async Rust client for Kinetica (GPUdb) - a distributed GPU-accelerated database.

### Features

<ul>
  <li>**Async/await** - Built on Tokio for non-blocking I/O</li>
  <li>**High Performance** - Achieves 600K+ records/sec with optimized bulk insert</li>
  <li>**Type Safe** - Auto-generated API from Avro schemas</li>
  <li>**Fast Avro Encoding** - Uses `serde_avro_fast` for 6-7x faster serialization</li>
  <li>**Parallel Processing** - Multi-worker architecture with rayon for encoding</li>
  <li>**Worker Distribution** - Direct routing to worker nodes for maximum throughput</li>
  <li>**Logging** - Built-in logging via the `log` crate (default level: WARN)</li>
</ul>

### Logging

This library uses the [`log`](https://docs.rs/log) crate for logging. To enable logging output, add a logging implementation like `env_logger` to your application:

```toml theme={null}
[dependencies]
env_logger = "0.11"
```

Then initialize it in your main function:

```rust theme={null}
// Enable logging with default WARN level
env_logger::init();
// Or with a specific level: RUST_LOG=gpudb_api=debug cargo run
```

#### Log Levels

Messages are logged at these levels:

<ul>
  <li>**ERROR**: A request that could not be sent (“Giving up with an exit error after \<n>ms …”), and failures the call goes on past, such as a KiFS file that could not be transferred. Errors are also returned via `Result`.</li>
  <li>**WARN**: Failing over to another cluster, and settings that are ignored</li>
  <li>**INFO**: Failing back to the primary cluster, and KiFS files transferred</li>
  <li>**DEBUG**: Connecting, configuration details, worker setup, routing info</li>
  <li>**TRACE**: Per-batch details, HTTP request/response info (very verbose)</li>
</ul>

The level is the application’s logger’s to set, for the `gpudb_api` target (as with `RUST_LOG=gpudb_api=debug` above), or for all with [`log::set_max_level`](https://docs.rs/log/0.4.29/log/fn.set_max_level.html).

### Quick Start

```rust theme={null}
use gpudb_api::{
    Kinetica, KineticaOptions, BulkInserter, BulkInserterOptions,
    KineticaRecord, ShardKeyExtractor, ShardKeyValue, ShardKeyValues,
    avro_schema, AvroSchemaBuilder, TypePropertiesBuilder,
};
use smallvec::smallvec;
use std::sync::Arc;
use std::collections::HashMap;
use serde::Serialize;

// Define your record type
#[derive(Serialize, Clone, Default)]
struct MyRecord {
    id: i32,
    name: String,
}

impl ShardKeyExtractor for MyRecord {
    fn shard_key_values(&self) -> ShardKeyValues<'_> {
        smallvec![("id", ShardKeyValue::Int(self.id))]
    }
}

impl KineticaRecord for MyRecord {
    fn avro_schema(&self) -> &'static str {
        avro_schema!(
            AvroSchemaBuilder::new("MyRecord")
                .int_field("id")
                .string_field("name")
        )
    }

    fn type_properties() -> HashMap<String, Vec<String>> {
        TypePropertiesBuilder::new().build()
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client with authentication
    let mut options = KineticaOptions::new();
    options.set_username("admin")
           .set_password("password")
           .set_use_snappy(false);

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

    // Simple usage: Create bulk inserter with default options
    let inserter = BulkInserter::<MyRecord>::new(
        kinetica.clone(),
        "my_table".into(),
        50000,  // batch size
        8       // num workers
    ).await?;

    // Or with options:
    let mut bulk_options = BulkInserterOptions::new();
    bulk_options.set_update_on_existing_pk(true);  // Enable upsert mode

    let inserter_with_options = BulkInserter::<MyRecord>::with_options(
        kinetica,
        "my_table".into(),
        50000,
        8,
        Some(bulk_options),
    ).await?;

    // Insert records...

    Ok(())
}
```

## Re-exports

`pub use crate::gpudb::Kinetica;``pub use crate::gpudb::KineticaOptions;``pub use crate::gpudb::KineticaVersion;``pub use crate::gpudb::HaFailoverOrder;``pub use crate::gpudb::HaSynchronicityMode;``pub use crate::gpudb::ClusterAddressInfo;``pub use crate::gpudb::DEFAULT_HOST_MANAGER_PORT;``pub use crate::gpudb::USER_AGENT_PROGRAM_NAME;``pub use crate::errors::KineticaError;``pub use crate::bulk_inserter::BulkInserter;``pub use crate::bulk_inserter::BulkInserterOptions;``pub use crate::bulk_inserter::FlushOptions;``pub use crate::bulk_inserter::ShardKeyExtractor;``pub use crate::bulk_inserter::ShardKeyValue;``pub use crate::bulk_inserter::ShardKeyValues;``pub use crate::bulk_inserter::insert_records_options;``pub use crate::bulk_inserter::BatchInsertionResult;``pub use crate::bulk_inserter::BatchInsertionListener;``pub use crate::bulk_inserter::FnBatchListener;``pub use crate::bulk_inserter::InsertError;``pub use crate::bulk_inserter::QueueError;``pub use crate::bulk_inserter::BackpressureMetrics;``pub use crate::worker_list::WorkerList;``pub use crate::avro_schema_builder::AvroSchemaBuilder;``pub use crate::avro_schema_builder::AvroType;``pub use crate::avro_schema_builder::TypePropertiesBuilder;``pub use crate::avro_schema_builder::KineticaColumnProperties;``pub use crate::record_retriever::RecordRetriever;``pub use crate::record_retriever::RecordRetrieverOptions;``pub use crate::record_retriever::RetrievedRecord;``pub use crate::record_retriever::END_OF_SET;``pub use crate::avro::encode_records;``pub use crate::avro::encode_records_parallel;``pub use crate::avro::encode_records_sequential;``pub use crate::avro::encode_arc_records_parallel;``pub use crate::avro::encode_arc_records_partitioned;``pub use crate::avro::encode_records_partitioned;``pub use crate::avro::encode_single;``pub use crate::avro::decode_records;``pub use crate::avro::decode_records_parallel;``pub use crate::avro::decode_records_sequential;``pub use crate::avro::decode_with_fast_schema;``pub use crate::avro::decode_single;``pub use crate::avro::parse_schema;``pub use crate::avro::parse_fast_schema;``pub use crate::avro::PARALLEL_THRESHOLD;``pub use crate::sql_iterator::SqlIterator;``pub use crate::sql_iterator::SqlParameters;``pub use crate::json_records::GetRecordsJsonResponse;``pub use crate::json_records::InsertRecordsJsonRequest;``pub use crate::json_records::JsonOptions;``pub use crate::sql::SqlClient;``pub use crate::sql::SqlResult;``pub use crate::sql::Row;``pub use crate::sql::SqlError;``pub use crate::sql::SqlOpResult;``pub use crate::sql::PaginationStats;``pub use crate::sql::BatchingSqlClient;``pub use crate::sql::BatchingStats;``pub use crate::sql::SqlHints;``pub use crate::sql_insert_parser::ParsedInsert;``pub use crate::sql_insert_parser::parse_insert_statement;``pub use crate::sql_insert_parser::parse_sql_value_to_record_value;``pub use crate::generic_record::Type;``pub use crate::generic_record::TypeBuilder;``pub use crate::generic_record::Column;``pub use crate::generic_record::ColumnType;``pub use crate::generic_record::ColumnBaseType;``pub use crate::generic_record::GenericRecord;``pub use crate::generic_record::RecordValue;``pub use crate::generic_record::ArrayValue;``pub use crate::generic_record::BulkInsertStats;``pub use crate::sqlx_support::KineticaPool;``pub use crate::sqlx_support::KineticaConnection;``pub use crate::sqlx_support::KineticaTransaction;``pub use crate::sqlx_support::KineticaPoolOptions;``pub use crate::sqlx_support::KineticaPoolExt;``pub use crate::sqlx_support::SslMode;``pub use crate::sqlx_support::SqlxPaginationStats;``pub use crate::sqlx_support::SqlxBulkInserter;``pub use crate::sqlx_support::BatchingSqlxClient;``pub use crate::sqlx_support::BatchingSqlxStats;``pub use crate::sqlx_support::BatchingSqlxError;``pub use crate::sqlx_support::connect;``pub use crate::sqlx_support::connect_with_url;``pub use crate::sqlx_support::connect_with_options;``pub use crate::sqlx_support::connect_from_env;``pub use crate::sqlx_support::build_connection_url;``pub use crate::sqlx_support::connection_url_from_env;``pub use crate::sqlx_support::DEFAULT_PORT;``pub use crate::sqlx_support::DEFAULT_DATABASE;``pub use crate::sqlx_support::KineticaText;``pub use crate::sqlx_support::ToKineticaText;``pub use crate::sqlx_support::FromKineticaText;``pub use crate::sqlx_support::KineticaTimestamp;``pub use crate::sqlx_support::KineticaBytes;``pub use crate::sqlx_support::KineticaVector;``pub use crate::sqlx_support::KineticaArray;``pub use crate::sqlx_support::KineticaArrayElement;``pub use crate::sqlx_support::KineticaJson;``pub use crate::generated::*;`

## Modules

[avro](https://docs.kinetica.com/content/api/rust/avro/index.md)High-performance Avro encoding and decoding utilities.[avro\_<wbr />schema\_<wbr />builder](https://docs.kinetica.com/content/api/rust/avro_schema_builder/index.md)Avro Schema Builder for Kinetica Records[bulk\_<wbr />inserter](https://docs.kinetica.com/content/api/rust/bulk_inserter/index.md)Shard-aware high-performance bulk insert using serde\_avro\_fast for encoding.[bulk\_<wbr />inserter\_<wbr />common](https://docs.kinetica.com/content/api/rust/bulk_inserter_common/index.md)Common types and utilities shared between bulk inserter implementations.[column\_<wbr />property](https://docs.kinetica.com/content/api/rust/column_property/index.md)The column properties a Kinetica type can give its columns, as text. A [`Column`](https://docs.kinetica.com/content/api/rust/generic_record/struct.Column) takes them in its properties, and [`KineticaColumnProperties`](https://docs.kinetica.com/content/api/rust/avro_schema_builder/struct.KineticaColumnProperties) builds them.[errors](https://docs.kinetica.com/content/api/rust/errors/index.md)Error types for the Kinetica client.[filesystem](https://docs.kinetica.com/content/api/rust/filesystem/index.md)KiFS (Kinetica File System) API module.[generated](https://docs.kinetica.com/content/api/rust/generated/index.md)Endpoint layer generated by `gpudb_gen_api_rust.py` in gpudb-generators from the gpudb-schemas endpoint schemas. Regenerate with `../gpudb-generators/process_schema_changes.py gen-files --rust`; do not edit by hand. Generated endpoint layer. Every endpoint is an inherent method on [`Kinetica`](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica); the transport it calls lives in the hand-written runtime, not here.[generic\_<wbr />record](https://docs.kinetica.com/content/api/rust/generic_record/index.md)Generic Record Support for Dynamic Type Handling[gpudb](https://docs.kinetica.com/content/api/rust/gpudb/index.md)Core Kinetica client implementation.[hyper\_<wbr />client](https://docs.kinetica.com/content/api/rust/hyper_client/index.md)High-performance HTTP client using hyper directly.[json\_<wbr />records](https://docs.kinetica.com/content/api/rust/json_records/index.md)Inserting and reading records as JSON.[json\_<wbr />utils](https://docs.kinetica.com/content/api/rust/json_utils/index.md)Whether a text is a JSON object or array, and how a list of JSON records is sent as one array.[record\_<wbr />key](https://docs.kinetica.com/content/api/rust/record_key/index.md)[record\_<wbr />key\_<wbr />builder](https://docs.kinetica.com/content/api/rust/record_key_builder/index.md)[record\_<wbr />retriever](https://docs.kinetica.com/content/api/rust/record_retriever/index.md)Record retriever for efficient record retrieval from Kinetica with multi-head support.[sql](https://docs.kinetica.com/content/api/rust/sql/index.md)SQL client and result parser for Kinetica’s HTTP API[sql\_<wbr />insert\_<wbr />parser](https://docs.kinetica.com/content/api/rust/sql_insert_parser/index.md)Parsing of `INSERT INTO ... VALUES ...` statements.[sql\_<wbr />iterator](https://docs.kinetica.com/content/api/rust/sql_iterator/index.md)Iterating over the records an SQL query returns, a batch at a time.[sqlx\_<wbr />support](https://docs.kinetica.com/content/api/rust/sqlx_support/index.md)SQLx Support for Kinetica via PostgreSQL Wire Protocol[worker\_<wbr />list](https://docs.kinetica.com/content/api/rust/worker_list/index.md)Worker list for multi-head ingest and retrieval.

## Macros

[avro\_<wbr />schema](https://docs.kinetica.com/content/api/rust/macro.avro_schema.md)Helper macro to define a static Avro schema using the builder pattern.

## Structs

[ByteBuf](https://docs.kinetica.com/content/api/rust/struct.ByteBuf.md)Re-exported because generated request/response types expose Avro `bytes` fields as [`ByteBuf`](https://docs.kinetica.com/content/api/rust/struct.ByteBuf); callers would otherwise need their own `serde_bytes` dependency pinned to a matching version. Wrapper around `Vec<u8>` to serialize and deserialize efficiently.[Trust<wbr />Store](https://docs.kinetica.com/content/api/rust/struct.TrustStore.md)The certificates of a trust store.

## Traits

[Kinetica<wbr />Record](https://docs.kinetica.com/content/api/rust/trait.KineticaRecord.md)Trait that must be implemented by all types that can be inserted into Kinetica.


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