Struct SnowflakeApi 

pub struct SnowflakeApi { /* private fields */ }

Snowflake API, keeps connection pool and manages session for you

Implementations

impl SnowflakeApi

pub fn new( connection: Arc<Connection>, session: Session, account_identifier: String, ) -> Self

Create a new SnowflakeApi object with an existing connection and session.

pub fn with_password_auth( account_identifier: &str, warehouse: Option<&str>, database: Option<&str>, schema: Option<&str>, username: &str, role: Option<&str>, password: &str, ) -> Result<Self, SnowflakeApiError>

Initialize object with password auth. Authentication happens on the first request.

pub fn with_certificate_auth( account_identifier: &str, warehouse: Option<&str>, database: Option<&str>, schema: Option<&str>, username: &str, role: Option<&str>, private_key_pem: &str, ) -> Result<Self, SnowflakeApiError>

Initialize object with private certificate auth. Authentication happens on the first request.

pub fn from_env() -> Result<Self, SnowflakeApiError>

pub async fn close_session(&self) -> Result<(), SnowflakeApiError>

Closes the current session, this is necessary to clean up temporary objects (tables, functions, etc) which are Snowflake session dependent. If another request is made the new session will be initiated.

pub async fn exec(&self, sql: &str) -> Result<QueryResult, SnowflakeApiError>

Execute a single query against API. If statement is PUT, then file will be uploaded to the Snowflake-managed storage

pub async fn exec_raw( &self, sql: &str, ) -> Result<RawQueryResult, SnowflakeApiError>

Executes a single query against API. If statement is PUT, then file will be uploaded to the Snowflake-managed storage Returns raw bytes in the Arrow response

pub async fn exec_response( &self, sql: &str, ) -> Result<ExecResponse, SnowflakeApiError>

Useful for debugging to get the straight query response

pub async fn exec_json(&self, sql: &str) -> Result<Value, SnowflakeApiError>

Useful for debugging to get raw JSON response

pub fn query<'a>(&'a self, sql: &'a str) -> QueryBuilder<'a>

Builder entry point for queries that need bind parameters, cancellation, or a caller-supplied request_id. For unbound, non-cancellable queries SnowflakeApi::exec is shorter.

let r = api.query("SELECT name FROM users WHERE id = ? AND active = ?")
    .bind(123_i64)
    .bind(true)
    .with_cancel(&cancel_token)
    .execute()
    .await?;

pub async fn exec_with_cancel( &self, sql: &str, cancel: &CancellationToken, ) -> Result<QueryResult, SnowflakeApiError>

Execute a query with cooperative cancellation. Cancelling the token before completion sends a Snowflake abort-request for the query and returns SnowflakeApiError::QueryCancelled. Useful for REST APIs that need to abort Snowflake work when the upstream HTTP request is cancelled (wire it via token.clone().drop_guard() in your handler).

pub async fn exec_raw_with_cancel( &self, sql: &str, cancel: &CancellationToken, ) -> Result<RawQueryResult, SnowflakeApiError>

Like exec_raw, but cooperatively cancellable. See SnowflakeApi::exec_with_cancel.

pub async fn exec_with_request_id( &self, sql: &str, request_id: Uuid, cancel: &CancellationToken, ) -> Result<QueryResult, SnowflakeApiError>

Same as SnowflakeApi::exec_with_cancel, but the caller supplies the request_id. Useful when the cancellation signal lives in a completely different code path (e.g., a separate HTTP cancel endpoint that looks up an in-flight query by id) and you want to pass the id around instead of a CancellationToken. The token here is still honored if you have one; pass a fresh CancellationToken if not.

pub async fn cancel_query( &self, request_id: Uuid, ) -> Result<(), SnowflakeApiError>

Cancel a query identified by the request_id returned from the cancellable exec methods or generated by the caller. Idempotent: if the query has already finished, returns Ok(()) rather than an error (matching the Go driver’s behavior on queryNotExecutingCode).

pub async fn cancel_query_by_id( &self, query_id: &str, ) -> Result<(), SnowflakeApiError>

Cross-process / cross-session cancel by query_id. Sends Snowflake’s SYSTEM$CANCEL_QUERY('<id>') system function as a regular SQL statement; works from any session that has access to the running query (the owning role, or any role with the MONITOR privilege on the query’s session).

Use this when the canceller doesn’t share a process with the runner — e.g., a “POST /query” handler started the query and returned QueryHandle::query_id, and a separate “POST /query/:id/cancel” handler in a different worker needs to abort it. If both ends share a process, Self::cancel_query (by request_id) is one round-trip cheaper.

Idempotent: if the query has already finished, Snowflake returns “Query is no longer running” as a normal result and we surface Ok(()).

pub async fn submit_async( &self, sql: &str, ) -> Result<QueryHandle, SnowflakeApiError>

Submit a query without waiting for results. Returns immediately with a QueryHandle carrying both request_id (for Self::cancel_query) and query_id (for Self::query_status / Self::fetch_results). Equivalent to gosnowflake’s WithAsyncMode(true).

Useful for the three-handler dashboard pattern: one process submits, another polls, a third fetches the rows after the original HTTP request has long since closed.

pub async fn query_status( &self, query_id: &str, ) -> Result<QueryStatus, SnowflakeApiError>

One status round-trip against /monitoring/queries/<id>. Does not consume warehouse credits or buffer results; safe to call from a poll loop. query_id typically comes from QueryHandle::query_id or metadata.query_id on a previous result.

pub async fn fetch_results( &self, query_id: &str, ) -> Result<QueryResult, SnowflakeApiError>

Fetch decoded results for a previously submitted query by id. Blocks until terminal using gosnowflake’s fetch-by-id backoff ([1, 1, 2, 3, 4, 8, 10]s, saturating at 10s).

pub async fn fetch_results_raw( &self, query_id: &str, ) -> Result<RawQueryResult, SnowflakeApiError>

Raw counterpart to Self::fetch_results: returns Arrow IPC bytes without deserialization (or JSON when the session is configured for it). Same blocking + backoff semantics.

pub async fn fetch_results_stream( &self, query_id: &str, ) -> Result<(QueryMetadata, RecordBatchStream), SnowflakeApiError>

Stream decoded RecordBatches by query id. Blocks until Snowflake hands back a terminal envelope, then drives chunk downloads with bounded prefetch. Errors with SnowflakeApiError::JsonStreamUnsupported for JSON responses.

pub async fn fetch_results_stream_raw( &self, query_id: &str, ) -> Result<(QueryMetadata, ArrowChunkStream), SnowflakeApiError>

Raw counterpart to Self::fetch_results_stream: yields Arrow IPC blobs in original Snowflake order, suitable for SSE-style forwarding.