KuzuDB Python Client

Common errors

• common/type_utils.h on line 277: KU_UNREACHABLE

  cause Passing an empty Python list as a parameter to the `list_contains` function in Cypher queries. This was a bug in earlier versions.
  fix Upgrade Kuzu to version 0.11.1 or later, where this bug is fixed. If upgrading is not an option, avoid passing empty lists to `list_contains` by handling empty list cases in your application logic.

• Segmentation fault (core dumped) OR Program terminated with signal SIGSEGV, Segmentation fault.

  cause A `QueryResult` object being garbage collected after its parent `Connection` or `Database` object has already been closed/deleted, leading to a use-after-free error.
  fix Ensure all `QueryResult` objects (and other child objects) are explicitly deleted (`del result`) before the `Connection` (`del conn`) and `Database` (`del db`) objects are closed or deleted. This ensures resources are freed in the correct order. This was a known issue in v0.10.0 that should be addressed in newer versions.

• Trying to read a database file with an unmatched version

  cause Attempting to open a Kuzu database with a client (e.g., CLI or Python API) that has a different version or was not the original client used to create or last modify the database.
  fix Use the same version of the Kuzu client (Python or CLI) to open and interact with the database as was used to create it or last modify it. If using both CLI and Python, ensure their versions are identical for compatibility. If a database was created with an older version, consider backing up and migrating data to a new database created with the current version.

Warnings

• breaking Extension management has changed significantly in v0.11.3. For versions prior to v0.11.3, you needed to set up a local extension server and manually `INSTALL` extensions (e.g., `algo`, `fts`, `json`, `vector`). In v0.11.3, these four common extensions are pre-installed and pre-loaded. For other extensions or prior Kuzu versions, a local extension server is still required.
  Fix: For v0.11.3, commonly used extensions are bundled. For other extensions or older versions, set up a local extension server and use `INSTALL <EXTENSION_NAME> FROM 'http://localhost:8080/';` in your Cypher queries.
• gotcha The KuzuDB project on GitHub (kuzudb/kuzu) has been marked as 'archived', and a note indicates Kuzu is 'working on something new'. While prior releases are stated to be usable without modification, this indicates a potential shift in the project's long-term direction or the primary repository for future development.
  Fix: Monitor the official KuzuDB website and GitHub organization for announcements regarding new repositories, project direction, or potential migration paths for future development. Back up your databases regularly.
• gotcha Using Kuzu CLI to open a database created with the Python API (or vice-versa) can sometimes lead to 'Trying to read a database file with an unmatched version' errors due to versioning or internal format differences.
  Fix: Ensure that the Kuzu CLI and Python client versions are compatible, ideally identical. If encountering issues, try opening the database exclusively with the client (Python or CLI) that created it, or migrate data if a version mismatch is confirmed.
• gotcha In Kuzu v0.10.0, a bug could lead to segmentation faults if `QueryResult` objects were garbage collected after their parent `Connection` or `Database` objects were closed, due to use-after-free in the underlying C++ code.
  Fix: Explicitly `del` all `QueryResult` objects (and any other child objects) before closing or deleting their parent `Connection` or `Database` objects. Calling `gc.collect()` immediately after deletion can also help force cleanup. This issue should be resolved in later versions (e.g., 0.11.x and above).

Install

• pip install kuzu Install Kuzu Python client

Imports

• Database

  import kuzu
  db = kuzu.Database('path/to/db')

  Initializes a Kuzu database instance at the specified path. If the database does not exist, it will be created.
• Connection

  import kuzu
  db = kuzu.Database('path/to/db')
  conn = kuzu.Connection(db)

  Establishes a connection to the database instance for executing queries.

Quickstart

This quickstart demonstrates how to initialize a Kuzu database, define a schema with node and relationship tables, insert data, and execute Cypher queries using the Python API. It also shows how to retrieve results as a list of rows or a Pandas DataFrame. Remember to explicitly delete `Connection` and `Database` objects to ensure proper cleanup and data persistence, especially in scripts that exit immediately.

import kuzu

# Initialize a database and connection
db_path = 'my_graph_db'
db = kuzu.Database(db_path)
conn = kuzu.Connection(db)

# Define schema (Node Tables and Relationship Tables)
conn.execute("""
    CREATE NODE TABLE User(name STRING, age INT64, PRIMARY KEY (name));
    CREATE NODE TABLE City(name STRING, population INT64, PRIMARY KEY (name));
    CREATE REL TABLE LivesIn(FROM User TO City, start_date DATE);
""")

# Insert data
conn.execute("INSERT INTO User VALUES ('Alice', 30), ('Bob', 25);")
conn.execute("INSERT INTO City VALUES ('New York', 8000000), ('London', 9000000);")
conn.execute("INSERT INTO LivesIn VALUES ('Alice', 'New York', DATE('2020-01-01'));")
conn.execute("INSERT INTO LivesIn VALUES ('Bob', 'London', DATE('2021-03-15'));")

# Query data
result = conn.execute("MATCH (u:User)-[l:LivesIn]->(c:City) RETURN u.name, c.name, l.start_date;")

# Fetch and print results
for row in result.get_as_list():
    print(f"User: {row[0]}, City: {row[1]}, Lived Since: {row[2]}")

# Close the database connection (important to flush changes)
del conn
del db

# You can also fetch results as a Pandas DataFrame if pandas is installed
try:
    import pandas as pd
    db_df = kuzu.Database(db_path) # Re-open database
    conn_df = kuzu.Connection(db_df)
    df_result = conn_df.execute("MATCH (u:User) RETURN u.name, u.age;").get_as_df()
    print("\nResults as DataFrame:")
    print(df_result)
    del conn_df
    del db_df
except ImportError:
    print("\nInstall pandas (pip install pandas) to see DataFrame output.")