Struct AmateRSClient 

pub struct AmateRSClient { /* private fields */ }

AmateRS client for interacting with the database

The client manages connections, handles retries, and provides high-level operations for working with encrypted data.

Implementations

impl AmateRSClient

pub async fn connect(addr: impl Into<String>) -> Result<Self>

Connect to an AmateRS server

Example

use amaters_sdk_rust::AmateRSClient;

let client = AmateRSClient::connect("http://localhost:50051").await?;

pub async fn connect_with_config(config: ClientConfig) -> Result<Self>

Connect with a custom configuration

Example

use amaters_sdk_rust::{AmateRSClient, ClientConfig};
use std::time::Duration;

let config = ClientConfig::new("http://localhost:50051")
    .with_connect_timeout(Duration::from_secs(5))
    .with_max_connections(20);

let client = AmateRSClient::connect_with_config(config).await?;

pub fn with_encryptor(self, encryptor: FheEncryptor) -> Self

Set the FHE encryptor for client-side encryption

pub fn encryptor(&self) -> Option<&Arc<FheEncryptor>>

Get the encryptor (if set)

pub fn with_cache(self, config: QueryCacheConfig) -> Self

Enable client-side query result caching with the given configuration.

Example

use amaters_sdk_rust::{AmateRSClient, QueryCacheConfig};
use std::time::Duration;

let client = AmateRSClient::connect("http://localhost:50051")
    .await?
    .with_cache(QueryCacheConfig::default().with_ttl(Duration::from_secs(120)));

pub fn cache(&self) -> Option<&Arc<QueryCache>>

Get a reference to the cache (if enabled).

pub async fn set( &self, collection: &str, key: &Key, value: &CipherBlob, ) -> Result<()>

Set a key-value pair

Example

use amaters_sdk_rust::AmateRSClient;
use amaters_core::{Key, CipherBlob};

let key = Key::from_str("user:123");
let value = CipherBlob::new(vec![1, 2, 3, 4]);

client.set("users", &key, &value).await?;

pub async fn get( &self, collection: &str, key: &Key, ) -> Result<Option<CipherBlob>>

Get a value by key

Returns None if the key doesn’t exist.

Example

use amaters_sdk_rust::AmateRSClient;
use amaters_core::Key;

let key = Key::from_str("user:123");

if let Some(value) = client.get("users", &key).await? {
    println!("Found value: {} bytes", value.len());
}

pub async fn delete(&self, collection: &str, key: &Key) -> Result<()>

Delete a key

Example

use amaters_sdk_rust::AmateRSClient;
use amaters_core::Key;

let key = Key::from_str("user:123");
client.delete("users", &key).await?;

pub async fn contains(&self, collection: &str, key: &Key) -> Result<bool>

Check if a key exists

Example

use amaters_sdk_rust::AmateRSClient;
use amaters_core::Key;

let key = Key::from_str("user:123");

if client.contains("users", &key).await? {
    println!("Key exists");
}

pub async fn execute_query(&self, query: &Query) -> Result<QueryResult>

Execute a query

This is a lower-level method that executes arbitrary queries.

Example

use amaters_sdk_rust::AmateRSClient;
use amaters_core::{Query, Key};

let query = Query::Get {
    collection: "users".to_string(),
    key: Key::from_str("user:123"),
};

client.execute_query(&query).await?;

pub async fn execute_batch( &self, queries: Vec<Query>, ) -> Result<Vec<QueryResult>>

Execute a batch of queries

All queries are executed atomically (all succeed or all fail).

pub fn pool_stats(&self) -> PoolStats

Get connection pool statistics

pub fn close(&self)

Close all connections

pub async fn health_check(&self) -> Result<()>

Health check

Returns Ok(()) if the server is healthy.

pub async fn server_info(&self) -> Result<ServerInfo>

Get server information

Returns information about the server including version, capabilities, and uptime.

pub async fn range( &self, collection: &str, start: &Key, end: &Key, ) -> Result<Vec<(Key, CipherBlob)>>

Range query - retrieve keys in a range

Example

use amaters_sdk_rust::AmateRSClient;
use amaters_core::Key;

let start = Key::from_str("user:000");
let end = Key::from_str("user:999");

let results = client.range("users", &start, &end).await?;
println!("Found {} keys in range", results.len());

pub async fn range_paginated( &self, collection: &str, start: &Key, end: &Key, page_size: usize, ) -> Result<PaginatedResult<(Key, CipherBlob)>>

Range query with simple pagination.

Returns the first page_size items in the range [start, end). Use the returned cursor to fetch subsequent pages via Self::range_with_cursor.

pub async fn range_with_cursor( &self, collection: &str, start: &Key, end: &Key, pagination: &PaginationConfig, ) -> Result<PaginatedResult<(Key, CipherBlob)>>

Range query with full cursor-based pagination.

If pagination.cursor is Some, the scan resumes from the key encoded in the cursor (exclusive). Otherwise it starts from start.

pub async fn range_sorted( &self, collection: &str, start: &Key, end: &Key, sort: &SortConfig, ) -> Result<Vec<(Key, CipherBlob)>>

Range query with results sorted according to sort.

The full range is fetched from the server and then sorted client-side.

pub async fn scan( &self, collection: &str, prefix: &Key, pagination: &PaginationConfig, ) -> Result<PaginatedResult<(Key, CipherBlob)>>

Scan keys with a given prefix, returning paginated results.

This constructs a range [prefix, prefix_end) where prefix_end is the lexicographic successor of prefix, then delegates to Self::range_with_cursor.

pub async fn count(&self, collection: &str) -> Result<usize>

Count the number of keys in a collection.

This performs a full range scan and counts the results. For very large collections a server-side count would be more efficient, but this provides a correct answer using the existing API surface.

pub async fn stream_query( &self, query: Query, config: StreamConfig, ) -> Result<QueryStream>

Stream query results row by row using a real gRPC server-streaming RPC.

Returns a QueryStream that implements futures::Stream. The stream is backed by a bounded mpsc channel (capacity = config.buffer_size) so the producer is automatically throttled when the consumer is slow. Dropping the returned stream cancels the background task.

The server currently supports Range and Get queries for streaming. Other query variants will be rejected by the server with a gRPC error that is forwarded to the stream as Err(SdkError::Grpc(...)).

Returns Err(SdkError::Connection(...)) if there is no live server connection available.

Trait Implementations

impl Clone for AmateRSClient

fn clone(&self) -> AmateRSClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.