falkordb package

Subpackages

Submodules

falkordb.cluster module

falkordb.cluster.Cluster_Conn(conn, ssl, cluster_error_retry_attempts=3, startup_nodes=None, require_full_coverage=False, reinitialize_steps=5, read_from_replicas=False, dynamic_startup_nodes=True, url=None, address_remap=None)[source]
falkordb.cluster.Is_Cluster(conn)[source]

falkordb.edge module

class falkordb.edge.Edge(src_node: Node | int, relation: str, dest_node: Node | int, edge_id: int | None = None, alias: str | None = '', properties=None)[source]

Bases: object

An edge connecting two nodes.

to_string() → str[source]

Get a string representation of the edge’s properties.

Returns:

str: A string representation of the edge’s properties.

falkordb.exceptions module

exception falkordb.exceptions.SchemaVersionMismatchException(version: int)[source]

Bases: Exception

Exception raised when the schema version of the database does not match the version of the schema that the application expects.

falkordb.execution_plan module

class falkordb.execution_plan.ExecutionPlan(plan)[source]

Bases: object

ExecutionPlan Class for representing a collection of operations.

Attributes:

plan (list): List of strings representing the collection of operations. structured_plan (Operation): Root of the structured operation tree.

collect_operations(op_name)[source]

Collects all operations with specified name from plan

Args:

op_name (string): Name of operation to collect

Returns:

List[Operation]: All operations with the specified name

class falkordb.execution_plan.Operation(name: str, args: str | None = None, profile_stats: ProfileStats | None = None)[source]

Bases: object

Operation Class for representing a single operation within an execution plan.

Attributes:

name (str): The name of the operation. args (str): Operation arguments. children (list): List of child operations. profile_stats (ProfileStats): Profile statistics for the operation.

append_child(child)[source]

Appends a child operation to the current operation.

Args:

child (Operation): The child operation to append.

Returns:

Operation: The updated operation instance.

child_count() → int[source]

Returns the number of child operations.

Returns:

int: Number of child operations.

property execution_time: float

returns operation’s execution time in ms

property records_produced: int

returns number of records produced by operation.

class falkordb.execution_plan.ProfileStats(records_produced: int, execution_time: float)[source]

Bases: object

ProfileStats Class for representing runtime execution statistics of an operation.

Attributes:

records_produced (int): The number of records produced. execution_time (float): The execution time in milliseconds.

falkordb.falkordb module

class falkordb.falkordb.FalkorDB(host='localhost', port=6379, password=None, socket_timeout=None, socket_connect_timeout=None, socket_keepalive=None, socket_keepalive_options=None, connection_pool=None, unix_socket_path=None, encoding='utf-8', encoding_errors='strict', retry_on_error=None, ssl=False, ssl_keyfile=None, ssl_certfile=None, ssl_cert_reqs='required', ssl_ca_certs=None, ssl_ca_path=None, ssl_ca_data=None, ssl_check_hostname=False, ssl_password=None, ssl_validate_ocsp=False, ssl_validate_ocsp_stapled=False, ssl_ocsp_context=None, ssl_ocsp_expected_cert=None, max_connections=None, single_connection_client=False, health_check_interval=0, client_name=None, lib_name='FalkorDB', lib_version=None, username=None, retry=None, connect_func=None, credential_provider=None, protocol=2, cluster_error_retry_attempts=3, startup_nodes=None, require_full_coverage=False, reinitialize_steps=5, read_from_replicas=False, dynamic_startup_nodes=True, url=None, address_remap=None)[source]

Bases: object

FalkorDB Class for interacting with a FalkorDB server.

Supports both TCP and Unix socket connections.

Usage example::

from falkordb import FalkorDB # connect to the database and select the ‘social’ graph db = FalkorDB() graph = db.select_graph(“social”)

# connect using a Unix socket db = FalkorDB.from_url(“unix:///path/to/redis.sock”) graph = db.select_graph(“social”)

# get a single ‘Person’ node from the graph and print its name result = graph.query(“MATCH (n:Person) RETURN n LIMIT 1”).result_set person = result[0][0] print(person.properties[‘name’])

close() → None[source]

Close the underlying connection(s).

config_get(name: str) → int | str[source]

Retrieve a DB level configuration. For a list of available configurations see: https://docs.falkordb.com/configuration.html#falkordb-configuration-parameters

Args:

name (str): The name of the configuration.

Returns:

int or str: The configuration value.

config_set(name: str, value=None) → None[source]

Update a DB level configuration. For a list of available configurations see: https://docs.falkordb.com/configuration.html#falkordb-configuration-parameters

Args:

name (str): The name of the configuration. value: The value to set.

Returns:

None

classmethod from_url(url: str, **kwargs) → FalkorDB[source]

Creates a new FalkorDB instance from a URL.

Args:

cls: The class itself. url (str): The URL. kwargs: Additional keyword arguments to pass to the

DB.from_url function.

Returns:

DB: A new DB instance.

Usage example:: db = FalkorDB.from_url(“falkor://[[username]:[password]]@localhost:6379”) db = FalkorDB.from_url(“falkors://[[username]:[password]]@localhost:6379”) db = FalkorDB.from_url(“unix://[username@]/path/to/socket.sock?db=0[&password=password]”)

list_graphs() → List[str][source]

Lists all graph names. See: https://docs.falkordb.com/commands/graph.list.html

Returns:

List: List of graph names.

select_graph(graph_id: str) → Graph[source]

Selects a graph by creating a new Graph instance.

Args:

graph_id (str): The identifier of the graph.

Returns:

Graph: A new Graph instance associated with the selected graph.

udf_delete(lib: str)[source]

Delete a User Defined Function (UDF) library.

Args:

lib (str): The name of the library to delete.

udf_flush()[source]

Flush (remove) all User Defined Function (UDF) libraries.

udf_list(lib: str | None = None, with_code: bool = False)[source]

List User Defined Function (UDF) libraries.

Args:
lib (str, optional): If provided, filter the list to

this specific library.

with_code (bool, optional): If True, include the library

source code in the result. Defaults to False.

Returns:

list: A list of UDF libraries and their metadata.

udf_load(name: str, script: str, replace: bool = False)[source]

Load a User Defined Function (UDF) library.

Args:

name (str): The name of the library to load. script (str): The UDF script contents. replace (bool, optional): If True, replace an existing

library with the same name. Defaults to False.

falkordb.graph module

class falkordb.graph.Graph(client, name: str)[source]

Bases: object

Graph, collection of nodes and edges.

call_procedure(procedure: str, read_only: bool = True, args: List | None = None, emit: List[str] | None = None) → QueryResult[source]

Call a procedure.

Args:

procedure (str): The procedure to call. read_only (bool): Whether the procedure is read-only. args: Procedure arguments. emit: Procedure yield.

Returns:

QueryResult: The result of the procedure call.

copy(clone: str)[source]

Creates a copy of graph

Args:

clone (str): Name of cloned graph

Returns:

Graph: the cloned graph

create_edge_fulltext_index(relation: str, *properties) → QueryResult[source]

Create a full-text index for an edge. See: https://docs.falkordb.com/commands/graph.query.html#full-text-indexing

Args:

relation (str): The relation of the edge. properties: Variable number of property names to be indexed.

Returns:

Any: The result of the index creation query.

create_edge_mandatory_constraint(relation: str, *properties)[source]

Create edge mandatory constraint See: https://docs.falkordb.com/commands/graph.constraint-create.html

The constraint is created asynchronously, use list constraints to pull on constraint creation status

Args:

relation (str): Edge relationship-type to apply constraint to properties: Variable number of property names to constrain

create_edge_range_index(relation: str, *properties) → QueryResult[source]

Create a range index for an edge. See: https://docs.falkordb.com/commands/graph.query.html#creating-an-index-for-a-relationship-type

Args:

relation (str): The relation of the edge. properties: Variable number of property names to be indexed.

Returns:

Any: The result of the index creation query.

create_edge_unique_constraint(relation: str, *properties)[source]

Create edge unique constraint See: https://docs.falkordb.com/commands/graph.constraint-create.html

The constraint is created asynchronously, use list constraints to pull on constraint creation status

Note: unique constraints require the existence of a range index over the constraint properties, this function will create any missing range indices

Args:

relation (str): Edge relationship-type to apply constraint to properties: Variable number of property names to constrain

create_edge_vector_index(relation: str, *properties, dim: int = 0, similarity_function: str = 'euclidean') → QueryResult[source]

Create a vector index for an edge. See: https://docs.falkordb.com/commands/graph.query.html#vector-indexing

Args:

relation (str): The relation of the edge. properties: Variable number of property names to be indexed. dim (int, optional): The dimension of the vector. similarity_function (str, optional): The similarity function for the vector.

Returns:

Any: The result of the index creation query.

create_node_fulltext_index(label: str, *properties) → QueryResult[source]

Create a full-text index for a node. See: https://docs.falkordb.com/commands/graph.query.html#creating-a-full-text-index-for-a-node-label

Args:

label (str): The label of the node. properties: Variable number of property names to be indexed.

Returns:

Any: The result of the index creation query.

create_node_mandatory_constraint(label: str, *properties)[source]

Create node mandatory constraint See: https://docs.falkordb.com/commands/graph.constraint-create.html

The constraint is created asynchronously, use list constraints to pull on constraint creation status

Args:

label (str): Node label to apply constraint to properties: Variable number of property names to constrain

create_node_range_index(label: str, *properties) → QueryResult[source]

Create a range index for a node. See: https://docs.falkordb.com/commands/graph.query.html#creating-an-index-for-a-node-label

Args:

label (str): The label of the node. properties: Variable number of property names to be indexed.

Returns:

Any: The result of the index creation query.

create_node_unique_constraint(label: str, *properties)[source]

Create node unique constraint See: https://docs.falkordb.com/commands/graph.constraint-create.html

The constraint is created asynchronously, use list constraints to pull on constraint creation status

Note: unique constraints require the existence of a range index over the constraint properties, this function will create any missing range indices

Args:

label (str): Node label to apply constraint to properties: Variable number of property names to constrain

create_node_vector_index(label: str, *properties, dim: int = 0, similarity_function: str = 'euclidean') → QueryResult[source]

Create a vector index for a node. See: https://docs.falkordb.com/commands/graph.query.html#vector-indexing

Args:

label (str): The label of the node. properties: Variable number of property names to be indexed. dim (int, optional): The dimension of the vector. similarity_function (str, optional): The similarity function for the vector.

Returns:

Any: The result of the index creation query.

delete() → None[source]

Deletes the graph. See: https://docs.falkordb.com/commands/graph.delete.html

Returns:

None

drop_edge_fulltext_index(label: str, attribute: str) → QueryResult[source]

Drop a full-text index for an edge. See: https://docs.falkordb.com/commands/graph.query.html#deleting-an-index-for-a-relationship-type

Args:

label (str): The label of the edge. attribute (str): The attribute to drop the index on.

Returns:

Any: The result of the index dropping query.

drop_edge_mandatory_constraint(relation: str, *properties)[source]

Drop edge mandatory constraint See: https://docs.falkordb.com/commands/graph.constraint-create.html

Args:

label (str): Edge relationship-type to remove the constraint from properties: properties to remove constraint from

drop_edge_range_index(label: str, attribute: str) → QueryResult[source]

Drop a range index for an edge. See: https://docs.falkordb.com/commands/graph.query.html#deleting-an-index-for-a-relationship-type

Args:

label (str): The label of the edge. attribute (str): The attribute to drop the index on.

Returns:

Any: The result of the index dropping query.

drop_edge_unique_constraint(relation: str, *properties)[source]

Drop edge unique constraint See: https://docs.falkordb.com/commands/graph.constraint-create.html

Note: the constraint supporting range index is not removed

Args:

label (str): Edge relationship-type to remove the constraint from properties: properties to remove constraint from

drop_edge_vector_index(label: str, attribute: str) → QueryResult[source]

Drop a vector index for an edge. See: https://docs.falkordb.com/commands/graph.query.html#deleting-an-index-for-a-relationship-type

Args:

label (str): The label of the edge. attribute (str): The attribute to drop the index on.

Returns:

Any: The result of the index dropping query.

drop_node_fulltext_index(label: str, attribute: str) → QueryResult[source]

Drop a full-text index for a node. See: https://docs.falkordb.com/commands/graph.query.html#deleting-an-index-for-a-node-label

Args:

label (str): The label of the node. attribute (str): The attribute to drop the index on.

Returns:

Any: The result of the index dropping query.

drop_node_mandatory_constraint(label: str, *properties)[source]

Drop node mandatory constraint See: https://docs.falkordb.com/commands/graph.constraint-create.html

Args:

label (str): Node label to remove the constraint from properties: properties to remove constraint from

drop_node_range_index(label: str, attribute: str) → QueryResult[source]

Drop a range index for a node. See: https://docs.falkordb.com/commands/graph.query.html#deleting-an-index-for-a-node-label

Args:

label (str): The label of the node. attribute (str): The attribute to drop the index on.

Returns:

Any: The result of the index dropping query.

drop_node_unique_constraint(label: str, *properties)[source]

Drop node unique constraint See: https://docs.falkordb.com/commands/graph.constraint-create.html

Note: the constraint supporting range index is not removed

Args:

label (str): Node label to remove the constraint from properties: properties to remove constraint from

drop_node_vector_index(label: str, attribute: str) → QueryResult[source]

Drop a vector index for a node. See: https://docs.falkordb.com/commands/graph.query.html#deleting-an-index-for-a-node-label

Args:

label (str): The label of the node. attribute (str): The attribute to drop the index on.

Returns:

Any: The result of the index dropping query.

explain(query: str, params=None) → ExecutionPlan[source]

Get the execution plan for a given query. GRAPH.EXPLAIN returns an ExecutionPlan object. See: https://docs.falkordb.com/commands/graph.explain.html

Args:

query (str): The query for which to get the execution plan. params (dict): Query parameters.

Returns:

ExecutionPlan: The execution plan.

list_constraints() → List[Dict[str, object]][source]

Lists graph’s constraints

See: https://docs.falkordb.com/commands/graph.constraint-create.html#listing-constraints

Returns:

[Dict[str, object]]: list of constraints

list_indices() → QueryResult[source]

Retrieve a list of graph indices. See: https://docs.falkordb.com/commands/graph.query.html#procedures

Returns:

list: List of graph indices.

property name: str

Get the graph name.

Returns:

str: The graph name.

profile(query: str, params=None) → ExecutionPlan[source]

Execute a query and produce an execution plan augmented with metrics for each operation’s execution. Return an execution plan, with details on results produced by and time spent in each operation. See: https://docs.falkordb.com/commands/graph.profile.html

Args:

query (str): The query to profile. params (dict): Query parameters.

Returns:

ExecutionPlan: The profile information.

query(q: str, params: Dict[str, object] | None = None, timeout: int | None = None) → QueryResult[source]

Executes a query against the graph. See: https://docs.falkordb.com/commands/graph.query.html

Args:

q (str): The query. params (dict): Query parameters. timeout (int): Maximum query runtime in milliseconds.

Returns:

QueryResult: query result set.

ro_query(q: str, params: Dict[str, object] | None = None, timeout: int | None = None) → QueryResult[source]

Executes a read-only query against the graph. See: https://docs.falkordb.com/commands/graph.ro_query.html

Args:

q (str): The query. params (dict): Query parameters. timeout (int): Maximum query runtime in milliseconds.

Returns:

QueryResult: query result set.

slowlog()[source]

Get a list containing up to 10 of the slowest queries issued against the graph.

Each item in the list has the following structure: 1. a unix timestamp at which the log entry was processed 2. the issued command 3. the issued query 4. the amount of time needed for its execution, in milliseconds.

See: https://docs.falkordb.com/commands/graph.slowlog.html

Returns:

List: List of slow log entries.

slowlog_reset()[source]

Reset the slowlog. See: https://docs.falkordb.com/commands/graph.slowlog.html

Returns:

None

falkordb.graph_schema module

class falkordb.graph_schema.GraphSchema(graph)[source]

Bases: object

The graph schema. Maintains the labels, properties and relationships of the graph.

clear()[source]

Clear the graph schema.

Returns:

None

get_label(idx: int) → str[source]

Returns a label by its index.

Args:

idx (int): The index of the label.

Returns:

str: The label.

get_property(idx: int) → str[source]

Returns a property by its index.

Args:

idx (int): The index of the property.

Returns:

str: The property.

get_relation(idx: int) → str[source]

Returns a relationship type by its index.

Args:

idx (int): The index of the relation.

Returns:

str: The relationship type.

refresh(version: int) → None[source]

Refresh the graph schema.

Args:

version (int): The version of the graph schema.

Returns:

None

refresh_labels() → None[source]

Refresh labels.

Returns:

None

refresh_properties() → None[source]

Refresh property keys.

Returns:

None

refresh_relations() → None[source]

Refresh relationship types.

Returns:

None

falkordb.helpers module

falkordb.helpers.quote_string(v)[source]

FalkorDB strings must be quoted, quote_string wraps given v with quotes incase v is a string.

falkordb.helpers.stringify_param_value(value)[source]

turn a parameter value into a string suitable for the params header of a Cypher command you may pass any value that would be accepted by json.dumps()

ways in which output differs from that of str(): * strings are quoted * None –> “null” * in dictionaries, keys are wrapped in backticks so that non-bare-

identifier keys (e.g. @type, hyphenated UUIDs) are accepted by the Cypher parser. Empty keys and keys containing a literal backtick raise ValueError because FalkorDB’s CYPHER header parser does not support escaped backticks inside identifiers.

Parameters:

value – the parameter value to be turned into a string

Returns:

string

falkordb.node module

class falkordb.node.Node(node_id: int | None = None, alias: str | None = '', labels: str | List[str] | None = None, properties=None)[source]

Bases: object

A graph node.

to_string() → str[source]

Get a string representation of the node’s properties.

Returns:

str: A string representation of the node’s properties.

falkordb.path module

class falkordb.path.Path(nodes: List[Node], edges: List[Edge])[source]

Bases: object

Path Class for representing a path in a graph.

This class defines a path consisting of nodes and edges. It provides methods for managing and manipulating the path.

Example:

node1 = Node() node2 = Node() edge1 = Edge(node1, “R”, node2)

path = Path.new_empty_path() path.add_node(node1).add_edge(edge1).add_node(node2) print(path) # Output: <(node1)-(edge1)->(node2)>

edge_count() → int[source]

Returns the number of edges in the path.

Returns:

int: Number of edges in the path.

edges() → List[Edge][source]

Returns the list of edges in the path.

Returns:

list: List of edges in the path.

first_node() → Node | None[source]

Returns the first node in the path.

Returns:

Node: The first node in the path.

get_edge(index) → Edge | None[source]

Returns the edge at the specified index in the path.

Args:

index (int): Index of the edge.

Returns:

Edge: The edge at the specified index.

get_node(index) → Node | None[source]

Returns the node at the specified index in the path.

Args:

index (int): Index of the node.

Returns:

Node: The node at the specified index.

last_node() → Node | None[source]

Returns the last node in the path.

Returns:

Node: The last node in the path.

node_count() → int[source]

Returns the number of nodes in the path.

Returns:

int: Number of nodes in the path.

nodes() → List[Node][source]

Returns the list of nodes in the path.

Returns:

list: List of nodes in the path.

falkordb.query_result module

class falkordb.query_result.QueryResult(graph, response)[source]

Bases: object

Represents the result of a query operation on a graph.

property cached_execution: bool

Check if the query execution plan was cached.

Returns:

bool: True if the query execution plan was cached, False otherwise.

property header: list

Get the header of the result.

Returns:

list: An array of column name/column type pairs.

property indices_created: int

Get the number of indices created in the query.

Returns:

int: The number of indices created.

property indices_deleted: int

Get the number of indices deleted in the query.

Returns:

int: The number of indices deleted.

property labels_added: int

Get the number of labels added in the query.

Returns: int: The number of labels added.

property labels_removed: int

Get the number of labels removed in the query.

Returns:

int: The number of labels removed.

property nodes_created: int

Get the number of nodes created in the query.

Returns:

int: The number of nodes created.

property nodes_deleted: int

Get the number of nodes deleted in the query.

Returns:

int: The number of nodes deleted.

property properties_removed: int

Get the number of properties removed in the query.

Returns:

int: The number of properties removed.

property properties_set: int

Get the number of properties set in the query.

Returns:

int: The number of properties set.

property relationships_created: int

Get the number of relationships created in the query.

Returns:

int: The number of relationships created.

property relationships_deleted: int

Get the number of relationships deleted in the query.

Returns:

int: The number of relationships deleted.

property result_set: list

Get a list of the results from a query.

Returns:

list: A list of each row returned from a query.

property run_time_ms: float

Get the server execution time of the query.

Returns:

float: The server execution time of the query in milliseconds.

class falkordb.query_result.ResultSetScalarTypes(*values)[source]

Bases: Enum

Enumeration representing different scalar types in the query result set.

Attributes:

VALUE_UNKNOWN (int): Unknown scalar type (0) VALUE_NULL (int): Null scalar type (1) VALUE_STRING (int): String scalar type (2) VALUE_INTEGER (int): Integer scalar type (3) VALUE_BOOLEAN (int): Boolean scalar type (4) VALUE_DOUBLE (int): Double scalar type (5) VALUE_ARRAY (int): Array scalar type (6) VALUE_EDGE (int): Edge scalar type (7) VALUE_NODE (int): Node scalar type (8) VALUE_PATH (int): Path scalar type (9) VALUE_MAP (int): Map scalar type (10) VALUE_POINT (int): Point scalar type (11) VALUE_VECTORF32 (int): Vector scalar type (12) VALUE_DATETIME (int): DateTime scalar type (13) VALUE_DATE (int): Date scalar type (14) VALUE_TIME (int): Time scalar type (15) VALUE_DURATION (int): Duration scalar type (16)

VALUE_ARRAY = 6
VALUE_BOOLEAN = 4
VALUE_DATE = 14
VALUE_DATETIME = 13
VALUE_DOUBLE = 5
VALUE_DURATION = 16
VALUE_EDGE = 7
VALUE_INTEGER = 3
VALUE_MAP = 10
VALUE_NODE = 8
VALUE_NULL = 1
VALUE_PATH = 9
VALUE_POINT = 11
VALUE_STRING = 2
VALUE_TIME = 15
VALUE_UNKNOWN = 0
VALUE_VECTORF32 = 12
falkordb.query_result.parse_scalar(value, graph)[source]

Parse a scalar value from a value in the result set.

Args:

value: The value to parse. graph: The graph instance.

Returns:

Any: The parsed scalar value.

falkordb.sentinel module

falkordb.sentinel.Is_Sentinel(conn)[source]
falkordb.sentinel.Sentinel_Conn(conn, ssl)[source]

Module contents