Struct NexusClient 

pub struct NexusClient { /* private fields */ }

Nexus client — transport-agnostic handle to a running server.

Implementations

impl NexusClient

pub async fn batch_create_nodes( &self, nodes: Vec<BatchNode>, ) -> Result<BatchCreateNodesResponse>

Batch create multiple nodes

Arguments

• nodes - Vector of batch node definitions

Example

let mut nodes = Vec::new();
for i in 0..10 {
    let mut properties = HashMap::new();
    properties.insert("name".to_string(), Value::String(format!("Node{}", i)));
    nodes.push(nexus_sdk::BatchNode {
        labels: vec!["Person".to_string()],
        properties,
    });
}
let response = client.batch_create_nodes(nodes).await?;
tracing::info!("Created {} nodes", response.node_ids.len());

pub async fn batch_create_relationships( &self, relationships: Vec<BatchRelationship>, ) -> Result<BatchCreateRelationshipsResponse>

Batch create multiple relationships

Arguments

• relationships - Vector of batch relationship definitions

Example

let mut relationships = Vec::new();
for i in 0..5 {
    relationships.push(nexus_sdk::BatchRelationship {
        source_id: i,
        target_id: i + 1,
        rel_type: "KNOWS".to_string(),
        properties: HashMap::new(),
    });
}
let response = client.batch_create_relationships(relationships).await?;
tracing::info!("Created {} relationships", response.rel_ids.len());

impl NexusClient

pub fn endpoint_description(&self) -> String

Describe the active transport ("nexus://host:15475 (RPC)"). Useful for tracing and --verbose-style diagnostics in applications wrapping the SDK.

pub fn is_rpc(&self) -> bool

True when the active transport uses the native binary RPC wire format.

pub fn new(base_url: &str) -> Result<Self>

Create a client with default configuration against base_url.

base_url may use nexus://, http://, https://, or a bare host:port (defaults to RPC). Loading a nexus:// URL picks the native binary RPC transport; any other scheme uses HTTP.

Example

use nexus_sdk::NexusClient;

// Binary RPC (fastest path)
let rpc = NexusClient::new("nexus://localhost:15475")?;

// Legacy HTTP
let http = NexusClient::new("http://localhost:15474")?;

pub fn with_api_key(base_url: &str, api_key: &str) -> Result<Self>

Create a client with API key authentication.

pub fn with_credentials( base_url: &str, username: &str, password: &str, ) -> Result<Self>

Create a client with username/password authentication.

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

Create a client from a custom ClientConfig.

Transport precedence (strongest → weakest):

1. URL scheme in config.base_url (nexus:// forces RPC, http[s]:// forces HTTP).
2. NEXUS_SDK_TRANSPORT env var.
3. config.transport field.
4. Default: TransportMode::NexusRpc.

pub async fn execute_cypher( &self, query: &str, parameters: Option<HashMap<String, Value>>, ) -> Result<QueryResult>

Execute a Cypher query.

pub async fn get_stats(&self) -> Result<DatabaseStats>

Get database statistics.

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

Health check — returns true if the server responds successfully on the active transport.

pub async fn list_databases(&self) -> Result<ListDatabasesResponse>

List all databases (REST).

pub async fn create_database( &self, name: &str, ) -> Result<CreateDatabaseResponse>

Create a new database (REST).

pub async fn get_database(&self, name: &str) -> Result<DatabaseInfo>

Get database information (REST).

pub async fn drop_database(&self, name: &str) -> Result<DropDatabaseResponse>

Drop a database (REST).

pub async fn get_current_database(&self) -> Result<String>

Get the current session database (REST).

pub async fn switch_database( &self, name: &str, ) -> Result<SwitchDatabaseResponse>

Switch to a different database (REST).

impl NexusClient

pub async fn create_node( &self, labels: Vec<String>, properties: HashMap<String, Value>, ) -> Result<CreateNodeResponse>

Create a new node

Arguments

• labels - Node labels
• properties - Node properties

Example

let mut properties = HashMap::new();
properties.insert("name".to_string(), Value::String("Alice".to_string()));
let response = client.create_node(vec!["Person".to_string()], properties).await?;
tracing::info!("Created node with ID: {}", response.node_id);

pub async fn create_node_with_external_id( &self, labels: Vec<String>, properties: HashMap<String, Value>, external_id: impl Into<String>, conflict_policy: Option<&str>, ) -> Result<CreateNodeResponse>

Create a node with a caller-supplied external id.

external_id accepts the prefixed string form (sha256:<hex>, blake3:<hex>, sha512:<hex>, uuid:<canonical>, str:<utf8>, bytes:<hex>). conflict_policy is one of "error" (default), "match", or "replace".

Phase9 §5.5.

pub async fn get_node_by_external_id( &self, external_id: impl AsRef<str>, ) -> Result<GetNodeResponse>

Resolve a node by external id (returns node: None when absent).

Phase9 §5.5.

pub async fn get_node(&self, node_id: u64) -> Result<GetNodeResponse>

Get a node by ID

Arguments

• node_id - ID of the node to retrieve

Example

let response = client.get_node(0).await?; // Replace 0 with an actual node ID
if let Some(node) = response.node {
    tracing::info!("Retrieved node: {:?}", node);
}

pub async fn update_node( &self, node_id: u64, properties: HashMap<String, Value>, ) -> Result<UpdateNodeResponse>

Update an existing node

Arguments

• node_id - ID of the node to update
• properties - New properties for the node

Example

let mut properties = HashMap::new();
properties.insert("name".to_string(), Value::String("Bob".to_string()));
let response = client.update_node(0, properties).await?; // Replace 0 with an actual node ID
tracing::info!("Update node result: {}", response.message);

pub async fn delete_node(&self, node_id: u64) -> Result<DeleteNodeResponse>

Delete a node by ID

Arguments

• node_id - ID of the node to delete

Example

let response = client.delete_node(0).await?; // Replace 0 with an actual node ID
tracing::info!("Delete result: {}", response.message);

pub async fn create_relationship( &self, source_id: u64, target_id: u64, rel_type: String, properties: HashMap<String, Value>, ) -> Result<CreateRelResponse>

Create a new relationship

Arguments

• source_id - ID of the source node
• target_id - ID of the target node
• rel_type - Type of the relationship
• properties - Optional relationship properties

Example

let mut properties = HashMap::new();
properties.insert("weight".to_string(), Value::Float(1.5));
let response = client.create_relationship(1, 2, "KNOWS".to_string(), properties).await?;
tracing::info!("Created relationship with ID: {}", response.rel_id);

pub async fn update_relationship( &self, rel_id: u64, properties: HashMap<String, Value>, ) -> Result<UpdateRelResponse>

Update an existing relationship using Cypher

Arguments

• rel_id - ID of the relationship to update
• properties - New properties for the relationship

Example

let mut properties = HashMap::new();
properties.insert("weight".to_string(), Value::Float(2.0));
let response = client.update_relationship(1, properties).await?;
tracing::info!("Update relationship result: {}", response.message);

pub async fn delete_relationship( &self, rel_id: u64, ) -> Result<DeleteRelResponse>

Delete a relationship using Cypher

Arguments

• rel_id - ID of the relationship to delete

Example

let response = client.delete_relationship(1).await?;
tracing::info!("Delete relationship result: {}", response.message);

impl NexusClient

pub async fn get_query_statistics(&self) -> Result<QueryStatisticsResponse>

Get query statistics

Example

let stats = client.get_query_statistics().await?;
tracing::info!("Total queries: {}", stats.statistics.total_queries);
tracing::info!("Average execution time: {}ms", stats.statistics.average_execution_time_ms);

pub async fn get_slow_queries(&self) -> Result<SlowQueriesResponse>

Get slow queries

Example

let slow_queries = client.get_slow_queries().await?;
tracing::info!("Found {} slow queries", slow_queries.count);
for query in slow_queries.queries {
    tracing::info!("Query: {} ({}ms)", query.query, query.execution_time_ms);
}

pub async fn get_plan_cache_statistics( &self, ) -> Result<PlanCacheStatisticsResponse>

Get plan cache statistics

Example

let cache_stats = client.get_plan_cache_statistics().await?;
tracing::info!("Cached plans: {}", cache_stats.cached_plans);
tracing::info!("Hit rate: {:.2}%", cache_stats.hit_rate * 100.0);

pub async fn clear_plan_cache(&self) -> Result<Value>

Clear plan cache

Example

let response = client.clear_plan_cache().await?;
tracing::info!("Plan cache cleared: {:?}", response);

impl NexusClient

pub async fn create_label(&self, name: String) -> Result<CreateLabelResponse>

Create a new label

Arguments

• name - Label name

Example

let response = client.create_label("Person".to_string()).await?;
tracing::info!("Create label result: {}", response.message);

pub async fn list_labels(&self) -> Result<ListLabelsResponse>

List all labels

Example

let response = client.list_labels().await?;
tracing::info!("Labels: {:?}", response.labels);

pub async fn create_rel_type( &self, name: String, ) -> Result<CreateRelTypeResponse>

Create a new relationship type

Arguments

• name - Relationship type name

Example

let response = client.create_rel_type("KNOWS".to_string()).await?;
tracing::info!("Create rel type result: {}", response.message);

pub async fn list_rel_types(&self) -> Result<ListRelTypesResponse>

List all relationship types

Example

let response = client.list_rel_types().await?;
tracing::info!("Relationship types: {:?}", response.types);

impl NexusClient

pub async fn begin_transaction(&self) -> Result<Transaction>

Begin a new transaction

Example

let mut tx: Transaction = client.begin_transaction().await?;
// Perform operations...
tx.commit().await?;

Trait Implementations

impl Clone for NexusClient

fn clone(&self) -> NexusClient

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for NexusClient

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

Formats the value using the given formatter.