Metadata-Version: 2.5
Name: FalkorDB
Version: 1.8.1
Summary: Python client for interacting with FalkorDB database
Project-URL: Homepage, http://falkordb-py.readthedocs.io
Project-URL: Repository, http://github.com/falkorDB/falkordb-py
Author-email: FalkorDB inc <info@falkordb.com>
License-File: LICENSE
Keywords: Cypher,FalkorDB,GraphDB
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: python-dateutil<3,>=2.9.0
Requires-Dist: redis<9,>=8.0.0
Provides-Extra: hiredis
Requires-Dist: redis[hiredis]<9,>=8.0.0; extra == 'hiredis'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'test'
Requires-Dist: pytest-cov>=7.0.0; extra == 'test'
Requires-Dist: pytest>=9.0.2; extra == 'test'
Description-Content-Type: text/markdown

[![license](https://img.shields.io/github/license/falkordb/falkordb-py.svg)](https://github.com/falkordb/falkordb-py)
[![Release](https://img.shields.io/github/release/falkordb/falkordb-py.svg)](https://github.com/falkordb/falkordb-py/releases/latest)
[![PyPI version](https://badge.fury.io/py/falkordb.svg)](https://badge.fury.io/py/falkordb)
[![Codecov](https://codecov.io/gh/falkordb/falkordb-py/branch/main/graph/badge.svg)](https://codecov.io/gh/falkordb/falkordb-py)
[![Forum](https://img.shields.io/badge/Forum-falkordb-blue)](https://github.com/orgs/FalkorDB/discussions)
[![Discord](https://img.shields.io/discord/1146782921294884966?style=flat-square)](https://discord.gg/6M4QwDXn2w)

# falkordb-py

[![Try Free](https://img.shields.io/badge/Try%20Free-FalkorDB%20Cloud-FF8101?labelColor=FDE900&style=for-the-badge&link=https://app.falkordb.cloud)](https://app.falkordb.cloud)

FalkorDB Python client

see [docs](http://falkordb-py.readthedocs.io/)

## Installation
```sh
pip install FalkorDB
```

For faster parsing of large results (for example vector properties), install the
optional `hiredis` parser. `redis` uses it automatically:
```sh
pip install "FalkorDB[hiredis]"
```

## Usage

### Run FalkorDB instance
Docker:
```sh
docker run --rm -p 6379:6379 falkordb/falkordb
```
Or use [FalkorDB Cloud](https://app.falkordb.cloud)

### Synchronous Example 

```python
from falkordb import FalkorDB

# Connect to FalkorDB
db = FalkorDB(host="localhost", port=6379)

# Select the social graph
g = db.select_graph("social")

# Create 100 nodes and return a handful
nodes = g.query(
    "UNWIND range(0, 100) AS i CREATE (n {v:1}) RETURN n LIMIT 10"
).result_set
for n in nodes:
    print(n)

# Read-only query the graph for the first 10 nodes
nodes = g.ro_query("MATCH (n) RETURN n LIMIT 10").result_set

# Copy the Graph
copy_graph = g.copy("social_copy")

# Delete the Graph
g.delete()
```

### Asynchronous Example

```python
import asyncio
from falkordb.asyncio import FalkorDB
from redis.asyncio import BlockingConnectionPool


async def main():

    # Connect to FalkorDB
    pool = BlockingConnectionPool(
        max_connections=16, timeout=None, decode_responses=True
    )
    db = FalkorDB(connection_pool=pool)

    # Select the social graph
    g = db.select_graph("social")

    # Execute query asynchronously
    result = await g.query(
        "UNWIND range(0, 100) AS i CREATE (n {v:1}) RETURN n LIMIT 10"
    )

    # Process results
    for n in result.result_set:
        print(n)

    # Run multiple queries concurrently
    tasks = [
        g.query("MATCH (n) WHERE n.v = 1 RETURN count(n) AS count"),
        g.query('CREATE (p:Person {name: "Alice"}) RETURN p'),
        g.query('CREATE (p:Person {name: "Bob"}) RETURN p'),
    ]

    results = await asyncio.gather(*tasks)

    # Process concurrent results
    print(f"Node count: {results[0].result_set[0][0]}")
    print(f"Created Alice: {results[1].result_set[0][0]}")
    print(f"Created Bob: {results[2].result_set[0][0]}")

    # Close the connection when done
    await pool.aclose()


# Run the async example
if __name__ == "__main__":
    asyncio.run(main())
```

### Sentinel Failover

Point the client at a Sentinel and it connects to the monitored master. The Sentinel must monitor exactly one master; the client raises an error otherwise. After a failover, it reconnects to the new master:

```python
from falkordb import FalkorDB

db = FalkorDB(host="localhost", port=26379)
```

A dropped connection or a timeout does not tell whether a write already ran on the server, so a write that fails this way is not sent again: the error is raised to the caller. Reads, and writes that provably never ran (the connection could not be opened, or a demoted master rejected the write as read-only), are retried according to the client's `retry` settings. `FalkorDB` does not retry by default, so pass a `retry` policy to ride out a failover.

To resend writes as well, pass `retry_writes=True`. A resent write may then run twice, so only enable it when your write queries are safe to repeat, for example `MERGE` instead of `CREATE`:

```python
from redis.backoff import ExponentialBackoff
from redis.exceptions import ConnectionError, ReadOnlyError, TimeoutError
from redis.retry import Retry

db = FalkorDB(
    host="localhost",
    port=26379,
    retry=Retry(ExponentialBackoff(cap=1, base=0.1), 15),
    retry_on_error=[ConnectionError, TimeoutError, ReadOnlyError],
    retry_writes=True,
)
```