Polybase local client

Bounded synchronous HTTP client for a local Polybase console. This crate contains the standalone client and depends on serde and serde_json. It does not contain the private database engine or a hosted service. Requires Rust 1.89 or newer and a separately installed Polybase console; version 0.8.2 is the release qualification target.

cargo add polybase-client@0.8.3

Start polybase-console /path/to/database 7340, then:

use polybase_client::{Client, Query};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new("127.0.0.1:7340".parse()?)?;
    let read = client.read_revision(b"tasks/1")?;
    let receipt = client.write_revision(
        &read.revision, Some(br#"{"status":"open"}"#),
    )?;
    let page = client.page(&Query::all(b"tasks/"), None, 64)?;
    println!("{} {}", receipt.position, page.rows.len());
    Ok(())
}

read_revision returns an opaque revision for a conditional write_revision. Error::Api { status: 409, .. } reports a stale revision. A transport timeout can leave a write's outcome uncertain: the server can still commit. The client never automatically retries writes. Reconcile application state before another write.

Query pages have a captured position and an optional continuation cursor. Keep the query and pass page.next.as_deref() to subsequent page calls until it is None. Keys and values in returned rows are lowercase hexadecimal bytes; use unhex to decode them. Positions are decimal strings.

subscribe captures initial rows and a token. Persist those together. poll takes the application's last applied token explicitly: apply complete commit transitions and atomically persist rows and the returned token before advancing. On restart call resume with the saved token, then pass its returned ResumedSession and the saved token to poll. Resume returns session identity without taking another snapshot. Both initial and resumed sessions work with poll and unsubscribe. Delivery can repeat, tokens can expire, and the client does not silently take a new snapshot. Client::call provides serde-typed access to other documented routes.

verify_backup, create_index, indexes, search_index, drop_index and compaction_advice provide the same named maintenance/index routes as the TypeScript client. create_index serializes its prefix bytes as a JSON byte array because the server's index-create route requires that format. Other key and key_prefix wire fields use lowercase hex.

search(&SearchQuery::Json { .. }) and search(&SearchQuery::Text { .. }) call /api/search: bounded current-head scalar equality or Unicode whole-word search, without a subscription. This differs from search_index, which calls /api/index-search for one named equality index, and from paginated typed queries. Search prefixes are lowercase hex strings, produced with hex.

Non-JSON HTTP error responses retain their status in Error::Api; body is a JSON string containing the response text (invalid UTF-8 is replaced). Successful responses still require valid JSON.

The client supports IPv4 loopback only, uses blocking standard-library TCP, bounds requests to 128 KiB and responses to 8 MiB, and sets five-second connect, read and write socket timeouts. A read timeout is a per-socket-operation timeout, not a deadline for the entire response. Keep the console on loopback.

See the Polybase documentation for server installation, limits and protocol guarantees. Client terms are in LICENSE. The public client source and release tags allow comparison with the registry archive; the engine is private.

polybase-client 0.8.3

Polybase local client