Struct AsyncArrowInserter 

pub struct AsyncArrowInserter<'conn> { /* private fields */ }

Async inserter for Arrow IPC stream data into a Hyper table.

This is the async version of ArrowInserter, designed for use in tokio-based async applications.

Ownership & Drop

You must call either execute() or cancel() to properly terminate the COPY session. If the inserter is dropped without calling one of these, a best-effort CopyFail is queued and the connection will self-heal on the next async operation. Data sent so far will be lost.

Example

use hyperdb_api::{AsyncArrowInserter, AsyncConnection, CreateMode, TableDefinition, SqlType, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let conn = AsyncConnection::connect("localhost:7483", "test.hyper", CreateMode::CreateIfNotExists).await?;

    let table_def = TableDefinition::new("data")
        .add_required_column("id", SqlType::int())
        .add_nullable_column("value", SqlType::double());

    // Arrow IPC data from external source
    let arrow_data: Vec<u8> = vec![]; // Your Arrow IPC stream here

    let mut inserter = AsyncArrowInserter::new(&conn, &table_def)?;
    inserter.insert_data(&arrow_data).await?;
    let rows = inserter.execute().await?;
    println!("Inserted {} rows", rows);
    Ok(())
}

Implementations

impl<'conn> AsyncArrowInserter<'conn>

pub fn new( connection: &'conn AsyncConnection, table_def: &TableDefinition, ) -> Result<Self>

Creates a new async Arrow inserter for the given table.

The underlying COPY session is started lazily on the first data write, so construction is lightweight. However, the connection’s transport is validated eagerly — using a gRPC connection will return an error immediately.

Arguments

• connection - The async database connection (must be TCP, not gRPC).
• table_def - The table definition for the target table.

Errors

• Returns Error::Other with message "Table definition must have at least one column" if table_def has no columns.
• Returns Error::Other if connection is using gRPC transport (COPY is TCP-only).

pub fn with_flush_threshold(self, threshold: usize) -> Self

Sets a custom flush threshold in bytes.

Data is buffered until the threshold is reached, then flushed to the server. Default is 16 MB (matching HyperBinary Inserter).

pub async fn insert_data(&mut self, arrow_ipc_data: &[u8]) -> Result<()>

Inserts a complete Arrow IPC stream (schema + record batches).

Use this method for single-chunk inserts or for the first chunk of multi-chunk inserts. The Arrow IPC stream must include the schema message followed by one or more record batch messages.

Errors

• Returns Error::Other if a schema was already sent (call insert_record_batches for subsequent chunks instead).
• Returns Error::Other / Error::Client if the lazy COPY session cannot be opened.
• Returns Error::Client / Error::Io if the server rejects the data or the socket write fails.

pub async fn insert_record_batches( &mut self, arrow_batch_data: &[u8], ) -> Result<()>

Inserts Arrow record batch data without schema.

Use this method for subsequent chunks after the first insert_data() call. The data should contain only Arrow record batch messages, not the schema.

Errors

• Returns Error::Other if no schema has been sent yet (call insert_data first).
• Returns Error::Client / Error::Io if the server rejects the data or the socket write fails.

pub async fn insert_raw(&mut self, data: &[u8]) -> Result<()>

Inserts raw Arrow data without schema tracking.

This is a low-level method that sends data directly without checking whether schema has been sent. Use this only if you are managing schema handling yourself.

Errors

• Returns Error::Other / Error::Client if the lazy COPY session cannot be opened.
• Returns Error::Client / Error::Io if the server rejects the data or the socket write fails.

pub async fn execute(self) -> Result<u64>

Finishes the insert operation and returns the number of rows inserted.

This sends any remaining buffered data to the server and completes the COPY session. Always call this (or cancel()) to properly terminate the session.

Errors

Returns Error::Client or Error::Io if the CommandComplete round-trip fails (server rejected some buffered batch, or the socket closed mid-flush). If no data was ever written, returns Ok(0).

pub async fn cancel(self)

Cancels the insert operation.

All data sent so far will be discarded.

pub fn has_data(&self) -> bool

Returns whether any data has been sent.

pub fn total_bytes(&self) -> usize

Returns the total bytes sent so far.

pub fn chunk_count(&self) -> usize

Returns the number of chunks sent so far.

Trait Implementations

impl<'conn> Debug for AsyncArrowInserter<'conn>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for AsyncArrowInserter<'_>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.