API reference
guard()
guard(driver, mode="read", *, allow=None, disallow=None)
Guard a Neo4j driver so it only runs allowed queries and only returns allowed results.
Every query the driver sends is checked first, through execute_query, sessions and transactions. A blocked query raises GuardError and is never sent. A blocked result raises GuardError while it is read, which rolls back execute_query and explicit transactions. An auto-commit query from session.run has already run.
Parameters
| Name | Type | Description |
|---|---|---|
driver | neo4j.Driver or neo4j.AsyncDriver | The driver to guard. |
mode | "read", "write", "readonly" or "readwrite" | The defaults to start from. "readonly" and "readwrite" are aliases for "read" and "write". Default "read". |
allow | list[str] or None | Entries to allow on top of the mode's defaults. |
disallow | list[str] or None | Entries to block. They take precedence over allow. |
Returns
The same driver, now guarded.
Raises
ValueError:modeor an entry is invalid, or the driver is already guarded.TypeError:allowordisallowis a single string instead of a list.
GuardError
class GuardError(Exception)
Raised when a query or its result is blocked, or the query is invalid Cypher. The message describes what was blocked, so it can be returned to the LLM.
Mode defaults
| Read | Write | |
|---|---|---|
Read clauses (MATCH, RETURN, WITH, ...) | ✓ | ✓ |
Write clauses (CREATE, MERGE, SET, ...) | ✓ | |
Delete clauses (DELETE, DETACH DELETE) | ||
Other clauses (LOAD CSV, USE) | ||
Built-in functions (toUpper, count, ...) | ✓ | ✓ |
Schema and search procedures (db.labels, db.index.vector.queryNodes, ...) | ✓ | ✓ |
Other procedures and functions (apoc.*, dbms.*, ...) | ||
Admin commands (SHOW USERS, CREATE INDEX, ...) |
Admin commands are blocked in every mode and cannot be allowed. A leading EXPLAIN or PROFILE is removed before the query is checked.
Entries
| Entry | Example | allow | disallow |
|---|---|---|---|
| Clause | "DELETE" | ✓ | ✓ |
| Procedure or function | "apoc.load.json", "apoc.meta.*" | ✓ | ✓ |
| Label or relationship type | "Employee" | ✓ | |
| Property | "Person.ssn" | ✓ |
Clause, procedure and function names ignore case. Labels and properties are case-sensitive, as in Neo4j.
Blocked labels and properties are checked in the query and in returned nodes, relationships and paths. While a property is blocked, properties(), n {.*}, n[key] and map comprehensions over maps are blocked. While a label is blocked, dynamic labels are blocked.