Crate falkordb

Expand description

§falkordb-rs

§FalkorDB Rust client

§Usage

§Installation

Just add it to your Cargo.toml, like so:

falkordb = { version = "0.1.10" }

§Run FalkorDB instance

Docker:

docker run --rm -p 6379:6379 falkordb/falkordb

§Code Example

use falkordb::{FalkorClientBuilder, FalkorConnectionInfo};

// Connect to FalkorDB
let connection_info: FalkorConnectionInfo = "falkor://127.0.0.1:6379".try_into()
            .expect("Invalid connection info");

let client = FalkorClientBuilder::new()
           .with_connection_info(connection_info)
           .build()
           .expect("Failed to build client");

// Select the social graph
let mut graph = client.select_graph("social");

// Create 100 nodes and return a handful
let mut nodes = graph.query("UNWIND range(0, 100) AS i CREATE (n { v:1 }) RETURN n LIMIT 10")
            .with_timeout(5000)
            .execute()
            .expect("Failed executing query");

// Can also be collected, like any other iterator
while let Some(node) = nodes.data.next() {
   println ! ("{:?}", node);
}

§Features

§`tokio` support

This client supports nonblocking API using the tokio runtime. It can be enabled like so:

falkordb = { version = "0.1.10", features = ["tokio"] }

Currently, this API requires running within a multi_threaded tokio scheduler, and does not support the current_thread one, but this will probably be supported in the future.

The API uses an almost identical API, but the various functions need to be awaited:

use falkordb::{FalkorClientBuilder, FalkorConnectionInfo};

// Connect to FalkorDB
let connection_info: FalkorConnectionInfo = "falkor://127.0.0.1:6379".try_into()
            .expect("Invalid connection info");

let client = FalkorClientBuilder::new_async()
            .with_connection_info(connection_info)
            .build()
            .await
            .expect("Failed to build client");

// Select the social graph
let mut graph = client.select_graph("social");

// Create 100 nodes and return a handful
let mut nodes = graph.query("UNWIND range(0, 100) AS i CREATE (n { v:1 }) RETURN n LIMIT 10")
            .with_timeout(5000)
            .execute()
            .await
            .expect("Failed executing query");

// Graph operations are asynchronous, but parsing is still concurrent:
while let Some(node) = nodes.data.next() {
     println ! ("{:?}", node);
}

Note that thread safety is still up to the user to ensure, I.e. an AsyncGraph cannot simply be sent to a task spawned by tokio and expected to be used later, it must be wrapped in an Arc<Mutex<_>> or something similar.

§SSL/TLS Support

This client is currently built upon the redis crate, and therefore supports TLS using its implementation, which uses either rustls or native_tls. This is not enabled by default, and the user ust opt-in by enabling the respective features: "rustls"/"native-tls" ( when using tokio: "tokio-rustls"/"tokio-native-tls").

For Rustls:

falkordb = { version = "0.1.10", features = ["rustls"] }

falkordb = { version = "0.1.10", features = ["tokio-rustls"] }

For Native TLS:

falkordb = { version = "0.1.10", features = ["native-tls"] }

falkordb = { version = "0.1.10", features = ["tokio-native-tls"] }

§Tracing

This crate fully supports instrumentation using the tracing crate, to use it, simply, enable the tracing feature:

falkordb = { version = "0.1.10", features = ["tracing"] }

Note that different functions use different filtration levels, to avoid spamming your tests, be sure to enable the correct level as you desire it.

Structs§

AsyncGraph: The main graph API, this allows the user to perform graph operations while exposing as little details as possible.
Constraint: A constraint applied on all ‘properties’ of the graph entity ‘label’ in this graph
Edge: An edge in the graph, representing a relationship between two Nodes.
ExecutionPlan: An execution plan, allowing access both to the human-readable text representation, access to a per-operation map, or traversable operation tree
FalkorAsyncClient: This is the publicly exposed API of the asynchronous Falkor Client It makes no assumptions in regard to which database the Falkor module is running on, and will select it based on enabled features and url connection
FalkorClientBuilder: A Builder-pattern implementation struct for creating a new Falkor client.
FalkorIndex: Contains all the info regarding an index on the database
FalkorSyncClient: This is the publicly exposed API of the sync Falkor Client It makes no assumptions in regard to which database the Falkor module is running on, and will select it based on enabled features and url connection
GraphSchema: A struct containing the various schema maps, allowing conversions between ids and their string representations.
LazyResultSet: A wrapper around the returned raw data, allowing parsing on demand of each result This implements Iterator, so can simply be collect()’ed into any desired container
Node: A node in the graph, containing a unique id, various labels describing it, and its own property.
Path: Represents a path between two nodes, contains all the nodes, and the relationships between them along the path
Point: A point in the world.
ProcedureQueryBuilder: A Builder-pattern struct that allows creating and executing procedure call on a graph
QueryBuilder: A Builder-pattern struct that allows creating and executing queries on a graph
QueryResult: A response struct which also contains the returned header and stats data
SlowlogEntry: A slowlog entry, representing one of the N slowest queries in the current log
SyncGraph: The main graph API, this allows the user to perform graph operations while exposing as little details as possible.

Enums§

ConfigValue: An enum representing the two viable types for a config value
ConstraintStatus: The status of this constraint
ConstraintType: The type of restriction to apply for the property
EntityType: Whether this element is a node or edge in the graph
FalkorConnectionInfo: An agnostic container which allows maintaining of various connection details. The different enum variants are enabled based on compilation features
FalkorDBError: A verbose error enum used throughout the client, messages are static string slices. this allows easy error integration using thiserror
FalkorValue: An enum of all the supported Falkor types
IndexStatus: The status of this index
IndexType: The type of this indexed field
SchemaType: An enum specifying which schema type we are addressing When querying using the compact parser, ids are returned for the various schema entities instead of strings Using this enum we know which of the schema maps to access in order to convert these ids to strings

Type Aliases§

FalkorResult: A Result which only returns FalkorDBError as its E type

Crate falkordbCopy item path