FalkorDB Python Client

Warnings

• breaking FalkorDB Python client v1.4.0 and later require Python 3.10 or higher. Older Python versions are no longer supported.
  Fix: Upgrade your Python environment to 3.10 or later.
• gotcha The FalkorDB server itself requires Redis 7.4 or newer for optimal compatibility and latest features. While the Python client's `redis-py` dependency might be met with older Redis versions (e.g., Redis 7.1), using an outdated Redis server with FalkorDB can lead to unexpected behavior or missing functionality.
  Fix: Ensure your FalkorDB server is running on a Redis instance that is version 7.4 or higher, ideally Redis 8.x for the latest FalkorDB releases.
• gotcha Explicitly close FalkorDB connections when they are no longer needed using `db.close()` or `await db.aclose()` for async clients. This prevents resource leaks and ensures proper cleanup, especially in long-running applications or when managing connection pools.
  Fix: Call `db.close()` or `await db.aclose()` after completing your database operations.
• gotcha FalkorDB's `LIMIT` clause does not affect eager operations like `CREATE`, `SET`, `DELETE`, `MERGE`, and projections with aggregate functions. For example, `UNWIND [1,2,3] AS value CREATE (a {property: value}) RETURN a LIMIT 1` will create three nodes but only return one.
  Fix: Be aware of this limitation when writing Cypher queries involving eager operations and `LIMIT`. Structure your queries to apply `LIMIT` after the eager operation has completed its full scope, if possible, or filter results at the client side if the server behavior is not desired.
• gotcha In Cypher queries, if a relationship in a `MATCH` pattern is not explicitly referenced elsewhere in the query, FalkorDB may only verify the existence of at least one matching relationship rather than operating on every single matching one. This can lead to incorrect counts or unexpected results in certain `COUNT()` scenarios.
  Fix: To ensure operations consider all matching relationships, explicitly refer to the relationship's alias in the query (e.g., `MATCH (a)-[e]->(b) WHERE ID(e) >= 0 RETURN COUNT(b)` or `MATCH (a)-[e]->(b) RETURN COUNT(b), e.dummyval`).

Install

• pip install falkordb Install falkordb

Imports

• FalkorDB

  from falkordb import FalkorDB

• FalkorDB (async)

  from falkordb.asyncio import FalkorDB

  Use this for asynchronous operations.

Quickstart

This quickstart demonstrates how to connect to a running FalkorDB instance, select or create a graph, insert data using Cypher queries, and retrieve results. It's crucial to have a FalkorDB server running (e.g., via Docker) before executing this code.

import os
from falkordb import FalkorDB

# Ensure FalkorDB server is running, e.g., via Docker:
# docker run -p 6379:6379 -p 3000:3000 -it --rm -v ./data:/var/lib/falkordb/data falkordb/falkordb

# Connect to FalkorDB (default host/port)
db = FalkorDB(host=os.environ.get('FALKORDB_HOST', 'localhost'), port=int(os.environ.get('FALKORDB_PORT', 6379)))

# Select a graph (or create if it doesn't exist)
g = db.select_graph('social')

# Create some data
create_query = """
CREATE (alice:User {id: 1, name: 'Alice', email: 'alice@example.com'})
CREATE (bob:User {id: 2, name: 'Bob', email: 'bob@example.com'})
CREATE (alice)-[:FRIENDS_WITH {since: 2020}]->(bob)
"""
g.query(create_query)

# Query the data
query = """
MATCH (u1:User)-[f:FRIENDS_WITH]->(u2:User)
RETURN u1.name, u2.name, f.since
"""

result = g.query(query)

# Print results
for record in result.result_set:
    print(f"{record[0]} is friends with {record[1]} since {record[2]}")

# Close the connection (important for resource management)
db.close()