Neo4j

Neo4j's connector uses the official neo4j Python driver over the Bolt protocol. Queries are plain Cypher.

Quick example

databases:
  - name: <database>          # used as --database <database> in queries
    type: neo4j
    host: localhost
    port: 7687
    database: <db-name>       # the Neo4j database name (4.0+); use `neo4j` for the default
    username: <username>
    password: <password>

permissions:
  - database: <database>      # must match `name:` above
    access: R
    # access codes:
    # R    read only           — MATCH, OPTIONAL MATCH, RETURN, WITH, UNWIND
    # W    write only          — CREATE, MERGE, SET, DELETE, REMOVE, DETACH (no reads)
    # RW   read + write
    # RA   read + append       — reads + CREATE / MERGE
    # RWA  read + write, no DELETE / REMOVE
    # A    admin (incl. CREATE / DROP INDEX, CONSTRAINT)

See Permissions for the full model, per-table overrides, and the operation matrix.

faz query "MATCH (n:<Label>) RETURN n LIMIT 5" --database <database> --table <Label> --language cypher

uv run faz query "MATCH (n:<Label>) RETURN n LIMIT 5" --database <database> --table <Label> --language cypher

python -m faz query "MATCH (n:<Label>) RETURN n LIMIT 5" --database <database> --table <Label> --language cypher

Configuration

The connection URI is built as bolt://{host}:{port} (or bolt+s:// when ssl: true).

Capabilities

• Read: MATCH ... RETURN, OPTIONAL MATCH, WITH, UNWIND, aggregations.
• Schema discovery enumerates labels and walks property-key associations to build a tables[] view: each label is a "table" with its property keys as fields.
• The R access level allows MATCH, WITH, UNWIND, CALL on read-only procedures, RETURN.
• Writes (CREATE, MERGE, SET, DELETE, REMOVE, DETACH DELETE) are gated by RBAC at the operation-class level.
• DDL (CREATE INDEX, DROP CONSTRAINT, etc.) is allowed only with A.

Limitations

• APOC procedures are mostly blocked by the Injection Analyser: apoc.load.*, apoc.cypher.run, apoc.cypher.runMany, apoc.periodic.*, apoc.export.*. These can read filesystems, run arbitrary Cypher, and exfiltrate data.
• LOAD CSV FROM is blocked — file access from inside Cypher is rejected.
• Stacked Cypher (multiple statements separated by ; followed by write keywords) is rejected.
• Schema discovery doesn't enumerate relationships as separate tables. Each label is a table; relationships traversed in queries are checked as part of the source label's permission.

Troubleshooting

ServiceUnavailable / connection timeout — Neo4j isn't listening on bolt://host:port. Test with cypher-shell -a bolt://host:port.

AuthError — credentials are wrong, or the user doesn't have access to the requested database. In Neo4j Aura and enterprise, multi-database access is granular.

SSL handshake failure — your Neo4j requires TLS. Set ssl: true (uses bolt+s://).

Empty schema — Neo4j has no nodes yet, or the user lacks READ privilege on the database.

Query blocked at INJECTION_ANALYSER for apoc.load.json — APOC data-loading procedures aren't allowed. Use a different ingestion path; faz's safety pipeline treats them as out-of-band exfiltration.

For the broader troubleshooting flow, see Connection failed.

Related

• Databases overview — cross-connector basics.
• Permissions — how access codes map to Cypher operations.
• faz.yaml — the full config schema.