{"id":7347,"library":"kuzu","title":"KuzuDB Python Client","description":"Kuzu is a highly scalable, extremely fast, and easy-to-use embedded property graph database, offering serverless integration into applications. It is optimized for complex analytical workloads on very large graphs, featuring a flexible Property Graph Data Model, Cypher query language support, native full-text search, and vector indices. Kuzu is actively developed and frequently releases minor updates and improvements.","status":"active","version":"0.11.3","language":"en","source_language":"en","source_url":"https://github.com/kuzudb/kuzu","tags":["graph database","embedded database","Cypher","vector search","full-text search","OLAP"],"install":[{"cmd":"pip install kuzu","lang":"bash","label":"Install Kuzu Python client"}],"dependencies":[{"reason":"Commonly used for converting query results to DataFrames via `get_as_df()` method.","package":"pandas","optional":true}],"imports":[{"note":"Initializes a Kuzu database instance at the specified path. If the database does not exist, it will be created.","symbol":"Database","correct":"import kuzu\ndb = kuzu.Database('path/to/db')"},{"note":"Establishes a connection to the database instance for executing queries.","symbol":"Connection","correct":"import kuzu\ndb = kuzu.Database('path/to/db')\nconn = kuzu.Connection(db)"}],"quickstart":{"code":"import kuzu\n\n# Initialize a database and connection\ndb_path = 'my_graph_db'\ndb = kuzu.Database(db_path)\nconn = kuzu.Connection(db)\n\n# Define schema (Node Tables and Relationship Tables)\nconn.execute(\"\"\"\n    CREATE NODE TABLE User(name STRING, age INT64, PRIMARY KEY (name));\n    CREATE NODE TABLE City(name STRING, population INT64, PRIMARY KEY (name));\n    CREATE REL TABLE LivesIn(FROM User TO City, start_date DATE);\n\"\"\")\n\n# Insert data\nconn.execute(\"INSERT INTO User VALUES ('Alice', 30), ('Bob', 25);\")\nconn.execute(\"INSERT INTO City VALUES ('New York', 8000000), ('London', 9000000);\")\nconn.execute(\"INSERT INTO LivesIn VALUES ('Alice', 'New York', DATE('2020-01-01'));\")\nconn.execute(\"INSERT INTO LivesIn VALUES ('Bob', 'London', DATE('2021-03-15'));\")\n\n# Query data\nresult = conn.execute(\"MATCH (u:User)-[l:LivesIn]->(c:City) RETURN u.name, c.name, l.start_date;\")\n\n# Fetch and print results\nfor row in result.get_as_list():\n    print(f\"User: {row[0]}, City: {row[1]}, Lived Since: {row[2]}\")\n\n# Close the database connection (important to flush changes)\ndel conn\ndel db\n\n# You can also fetch results as a Pandas DataFrame if pandas is installed\ntry:\n    import pandas as pd\n    db_df = kuzu.Database(db_path) # Re-open database\n    conn_df = kuzu.Connection(db_df)\n    df_result = conn_df.execute(\"MATCH (u:User) RETURN u.name, u.age;\").get_as_df()\n    print(\"\\nResults as DataFrame:\")\n    print(df_result)\n    del conn_df\n    del db_df\nexcept ImportError:\n    print(\"\\nInstall pandas (pip install pandas) to see DataFrame output.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"< 0.11.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, especially when mixing client types."},{"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).","message":"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.","severity":"gotcha","affected_versions":"0.10.0 and potentially earlier"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Passing an empty Python list as a parameter to the `list_contains` function in Cypher queries. This was a bug in earlier versions.","error":"common/type_utils.h on line 277: KU_UNREACHABLE"},{"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.","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.","error":"Segmentation fault (core dumped) OR Program terminated with signal SIGSEGV, Segmentation fault."},{"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.","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.","error":"Trying to read a database file with an unmatched version"}]}