Struct Client

Source

pub struct Client { /* private fields */ }

Expand description

Async HTTP client for running queries against a Helix instance.

A thin async wrapper over reqwest that knows how to reach a Helix gateway’s query routes. Construct it with Client::new, optionally attach a bearer API key via Client::with_api_key, then build and send requests through Client::query.

The client is cheap to Clone — the underlying reqwest::Client shares its connection pool — so a single instance can be reused across tasks.

Reachable as helix_db::Client.

§Examples

use helix_db::Client;

// Defaults to http://localhost:6969 when the URL is `None`.
let local = Client::new(None)?;

// Or point at a remote cluster and attach an API key.
let remote = Client::new(Some("https://cluster.helix-db.com"))?
    .with_api_key(Some("hx_your_api_key"));

Implementations§

Source §

impl Client

Source

pub async fn graph( &self, selection: &GraphSelection, ) -> Result<Graph, GraphLoadError>

Execute one ordinary read batch and construct an immutable native graph.

All methods on the returned graph operate locally and perform no additional Helix reads.

Source §

impl Client

Source

pub fn new(url: Option<&str>) -> Result<Self, HelixError>

Create a client pointed at a Helix instance.

url is the instance base URL; when None, it defaults to http://localhost:6969. The /v2/query base route is resolved up front and reused by every request.

§Errors

Returns HelixError::InvalidURL if url (or the resolved query route) cannot be parsed.

Source

pub fn server(url: Option<&str>) -> Result<Self, HelixError>

Create a server-mode client pointed at a Helix instance.

Source

pub fn with_api_key(self, api_key: Option<&str>) -> Self

Attach (or clear) the bearer API key sent with every request.

Passing Some(key) sets an Authorization: Bearer <key> header on each request; passing None clears any previously set key.

Source

pub fn query<R: for<'de> Deserialize<'de>>( &self, request: QueryRequest, ) -> QueryExecutionRequest<'_, 'static, R>

Execute an SDK-built query request.

In server mode this posts to /v2/query. In embedded mode this executes directly against the in-process [HelixDB].

Source

pub fn query_raw( &self, request: QueryRequest, ) -> QueryExecutionRequest<'_, 'static, Vec<u8>>

Execute a query while retaining the response as raw bytes.

Graph loading uses this path so Rust validates and constructs the graph without an intermediate language-level object graph.

Source

pub fn request_builder<R: for<'de> Deserialize<'de>>( &self, ) -> QueryBuilder<'_, '_, R>

Start building an advanced server request.

R is the type the JSON response body is deserialized into by QueryExecutionRequest::send. Returns a QueryBuilder on which you can toggle request headers, then attach a request with QueryBuilder::query.

§Examples

#![recursion_limit = "256"]
use helix_db::Client;
use helix_db::dsl::prelude::*;
use serde::Deserialize;

#[derive(Deserialize)]
struct Users { count: u64 }

let response: Users = client.query(request).send().await?;