neo4rs

When using Graph::execute or Txn::execute, the returned RowStream is lazy. The query is not actually processed by the server until you begin consuming the stream (e.g., via RowStream::next).

Streams within the same transaction are well-isolated, allowing you to consume multiple streams sequentially within the transaction lifecycle.

A DetachedRowStream is returned when executing a query directly on the graph (e.g., via crate::Graph::execute). Unlike RowStream, it manages its own connection from the pool. The connection is automatically released back to the pool when the stream is dropped.

Methods on DetachedRowStream (like next, single, into_stream) do not require passing a TransactionHandle because the connection is held internally.

// Example of consuming a DetachedRowStream
let mut stream = graph.execute("MATCH (n) RETURN n").await?;
while let Some(row) = stream.next().await? {
    // process row
}
let summary = stream.finish().await?;

To ensure atomicity, use Graph::start_txn to obtain a Txn handle.

• Use Txn::commit to finalize changes.
• Use Txn::rollback to abort changes.
• Connection Reuse: Unlike Graph::run or Graph::execute (which take a connection from the pool and release it immediately), a Txn holds onto a single connection from the pool until the transaction is committed, rolled back, or the Txn handle is dropped.

use neo4rs::*;

#[tokio::main]
async fn main() {
   let uri = "127.0.0.1:7687";
   let user = "neo4j";
   let pass = "neo";
   let graph = Graph::new(uri, user, pass).unwrap();

   let txn = graph.start_txn().await.unwrap();
   // ... execute queries using txn.run() or txn.execute() ...
   txn.commit().await.unwrap();
}

The driver provides two ways to represent a relationship, primarily differing in how they handle memory:

Use RelationshipRef when you are iterating over results and want maximum performance by borrowing strings and bytes directly from the network buffer. Use Relationship if you need to store the relationship in a long-lived structure that outlives the initial database response buffer.

A RowStream is returned when executing a query within a transaction (e.g., via crate::Txn::execute). It requires an active TransactionHandle to fetch rows from the server.

Important: You must stream through the results using next or similar methods to ensure the query is fully executed and the server-side state is managed correctly. If you stop consuming early, you should call finish to discard remaining messages and retrieve a summary.

// Example of consuming a RowStream within a transaction
// Note: This is a conceptual usage pattern based on the API
let mut stream = txn.execute("MATCH (n) RETURN n").await?;
while let Some(row) = stream.next(&mut txn).await? {
    // process row
}
let summary = stream.finish(&mut txn).await?;

When deserializing Neo4j Bolt results using serde, you can use specific newtype wrappers to target particular parts of the graph data structure. These types allow you to extract specific fields like IDs, labels, or properties directly into your Rust structs.

Commonly used types include:

• Id(u64): Extracts a node or relationship ID.
• StartNodeId(u64) and EndNodeId(u64): Extracts the start or end node ID of a relationship.
• Labels<Coll>: Extracts node labels (defaults to Vec<String>).
• Type<T>: Extracts a relationship type (defaults to String).
• Keys<Coll>: Extracts property keys (defaults to HashSet<String>).
• Properties<Coll>: Extracts element properties (defaults to HashMap<String, BoltType>).
• Nodes<T> and Relationships<T>: Extracts collections of nodes or relationships from a path.

For fine-grained control over the connection pool and protocol settings, use ConfigBuilder. This allows you to specify connection details and performance tuning parameters.

use neo4rs::*;
use std::time::Duration;

#[tokio::main]
async fn main() {
   let config = ConfigBuilder::default()
       .uri("127.0.0.1:7687")
       .user("neo4j")
       .password("neo")
       .db("neo4j")
       .fetch_size(500)
       .max_connections(10)
       .connection_timeout(Duration::from_secs(10))
       .build()
       .unwrap();
   let graph = Graph::connect(config).unwrap();
}

Use ConfigBuilder to construct a Config object required for connecting to a Neo4j instance. You must provide a uri, user, and password. The builder provides several methods to tune connection pooling, timeouts, and TLS settings.

use neo4rs::ConfigBuilder;
use std::time::Duration;

let config = ConfigBuilder::new()
    .uri("127.0.0.1:7687")
    .user("neo4j")
    .password("password")
    .db("neo4j")
    .max_connections(10)
    .fetch_size(500)
    .connection_timeout(Duration::from_secs(10))
    .build()
    .expect("Failed to build config");

The simplest way to connect to a Neo4j instance is using Graph::new(uri, user, pass). This creates a connection pool and allows you to execute queries immediately.

use neo4rs::*;

#[tokio::main]
async fn main() {
   let uri = "127.0.0.1:7687";
   let user = "neo4j";
   let pass = "neo";

   let graph = Graph::new(uri, user, pass).unwrap();
   // ...
}