Neo4j

Turn a Cypher query into a dataset — nodes, relationships, and paths as tabular rows.

The Neo4j connector runs a Cypher query and returns its result as a dataset. It works with Neo4j 5.x and AuraDB over the Bolt protocol.

Connection details

Field	Required	Notes
Connection Name	yes	Display name in the catalogue
URI	yes	`neo4j+s://…` for Aura, `bolt://…` self-hosted
User	yes	Use a read-only role
Password	yes	Stored encrypted; never shown again
Database	no	Defaults to `neo4j`

Scheme	Use for
`neo4j+s://`	Aura and clusters with a valid certificate
`neo4j+ssc://`	Clusters with a self-signed certificate
`bolt://`	Single instance, agent runtime only

Grant reader, not admin

Neo4j ships a built-in reader role. Use it — a Cypher query from an admin account can modify the graph, and Chartizer should never be able to.

Create a read-only user

CREATE USER chartizer SET PASSWORD 'use-a-generated-secret' CHANGE NOT REQUIRED;
GRANT ROLE reader TO chartizer;

Defining a dataset

Unlike a relational source, a Neo4j dataset is not a table. A dataset is a Cypher query, and its returned columns become the fields.

Dealers and their order totals

MATCH (d:Dealer)-[:PLACED]->(o:Order)
WHERE o.created_at >= datetime($since)
RETURN d.id            AS dealer_id,
       d.name          AS dealer_name,
       d.region        AS region,
       count(o)        AS order_count,
       sum(o.total)    AS revenue
ORDER BY revenue DESC

Return scalars, not nodes

RETURN d hands back a whole node object, which flattens unpredictably as the graph evolves. Always project the properties you want with AS aliases — the query above returns five clean, stable, typed fields.

Parameters

Queries accept the same template variables as other connectors, passed as Cypher parameters:

Variable	Resolves to
`$since`	ISO-8601 timestamp of the last successful sync
`$now`	UTC time at sync start
`$limit`	Page size, when paginating

Incremental sync

MATCH (o:Order)
WHERE o.updated_at > datetime($since)
RETURN o.id AS order_id, o.total AS total, o.updated_at AS updated_at

Type mapping

Neo4j	Becomes	Note
`String`	text
`Integer`, `Float`	integer, decimal
`Boolean`	boolean
`Date`, `DateTime`	date, timestamp	Zoned values converted to UTC
`Duration`	text	ISO-8601 string
`Point`	geo	Usable in map charts
`List`	array	Not exploded into rows
`Node`, `Relationship`	flattened	Avoid — project properties instead

Paths and relationships

Graph shapes have to be flattened before they can be charted. Two patterns cover most cases.

CYPHER

MATCH (a:Dealer)-[r:SUPPLIES]->(b:Dealer)
RETURN a.id AS from_id, b.id AS to_id, r.volume AS volume

Ideal for network and map charts, where each row is an edge.

CYPHER

MATCH (d:Dealer)-[:SUPPLIES*1..3]->(x:Dealer)
RETURN d.id AS dealer_id, count(DISTINCT x) AS reachable_dealers

Collapses a variable-length traversal into one row per starting node.

Bound your variable-length patterns

[:SUPPLIES*] with no upper bound can traverse the entire graph and will hit the query timeout — on a large graph it can affect the database for everyone. Always write *1..3 or similar.

Performance

Setting	Default	Notes
Query timeout	60s	Raise per dataset if genuinely needed
Page size	5,000 rows	Applied with `SKIP`/`LIMIT` when paginating
Refresh	Scheduled	Live query only for small, fast queries

Profile before scheduling

Run the query with PROFILE in Neo4j Browser first. A query with hundreds of thousands of db hits will be slow every 15 minutes forever.

Troubleshooting

Unable to connect to localhost:7687

bolt://localhost is only reachable from a local agent. From the Cloud runtime, use the public neo4j+s:// endpoint.

Field names look like d.name instead of dealer_name

The query returns unaliased expressions. Add AS aliases to every returned column.

Schema drift after a graph change

A property was added, removed, or retyped on the returned nodes. Since the query defines the schema, projecting explicit properties makes this far rarer.

Query timed out

Unbounded traversal, a missing index on the matched property, or a cartesian product from two disconnected MATCH clauses. PROFILE the query to find which.