The Neo4j BI Connector is your bridge from the complex, interconnected world of graph data to the familiar, tabular landscape of Business Intelligence tools.
Let’s see it in action. Imagine you have a Neo4j graph database tracking customer interactions and product relationships. You want to analyze which product bundles are most frequently purchased together by high-value customers.
First, you’d install the Neo4j BI Connector. This typically involves downloading a JAR file and placing it in your Neo4j plugins directory, then restarting the Neo4j server.
# Example: Place the connector JAR in the plugins directory
cp neo4j-bi-connector-x.y.z.jar /opt/neo4j/plugins/
systemctl restart neo4j
Once installed, the connector exposes your graph data as virtual tables and views that standard BI tools can query using SQL. You configure this mapping via a neo4j-bi-connector.properties file.
# neo4j-bi-connector.properties
neo4j.uri=bolt://localhost:7687
neo4j.username=neo4j
neo4j.password=your_password
# Define a virtual table for Customers
virtual.table.customers.query=MATCH (c:Customer) RETURN c.customerId AS customer_id, c.name AS customer_name, c.value AS customer_value
# Define a virtual table for Products
virtual.table.products.query=MATCH (p:Product) RETURN p.productId AS product_id, p.name AS product_name, p.category AS product_category
# Define a virtual table for Orders, linking customers and products
virtual.table.orders.query=MATCH (c:Customer)-[:PURCHASED]->(p:Product) RETURN c.customerId AS customer_id, p.productId AS product_id, p.name AS product_name
With this configuration, your BI tool (like Tableau, Power BI, or Looker) can connect to the Neo4j BI Connector as if it were a regular SQL database. You’d typically provide the connector’s host and port (e.g., localhost:2000 if running stand-alone, or the Neo4j server’s port if embedded).
In your BI tool, you’d then see customers, products, and orders as tables. You can join them using standard SQL:
SELECT
cust.customer_name,
prod.product_name,
COUNT(*) AS purchase_count
FROM
customers cust
JOIN
orders ord ON cust.customer_id = ord.customer_id
JOIN
products prod ON ord.product_id = prod.product_id
WHERE
cust.customer_value > 1000
GROUP BY
cust.customer_name, prod.product_name
ORDER BY
purchase_count DESC
LIMIT 10;
This query translates into Cypher queries executed by the connector behind the scenes, fetching the relevant graph traversal results and presenting them in a tabular format for your BI tool. The connector intelligently translates SQL JOIN operations into graph traversals, and WHERE clauses into Cypher WHERE clauses.
The core problem the connector solves is abstracting the graph’s structure. BI tools are built for relational data, expecting rows and columns. The connector acts as a semantic layer, allowing you to define how graph patterns (nodes and relationships) map to these familiar tabular structures. It lets you query your rich graph relationships using the SQL dialect your BI team already knows, unlocking insights that would be difficult or impossible to extract with traditional relational analysis.
The surprising efficiency comes from the connector’s ability to push down query execution to Neo4j. Instead of pulling all graph data into the BI tool and then processing it, the connector translates your SQL into optimized Cypher queries that run directly on the graph database. Neo4j’s native graph processing engine then performs the heavy lifting, returning only the aggregated, necessary results. This dramatically reduces data transfer and processing overhead.
When you define a virtual table, you’re not creating a materialized view. Each time your BI tool queries that virtual table, the virtual.table.<name>.query Cypher statement is executed against Neo4j in real-time. This means your reports always reflect the latest data in your graph, but it also implies that complex or very broad Cypher queries defined in the connector can impact Neo4j’s performance.
The next challenge you’ll face is optimizing the Cypher queries defined in your connector configuration for the best performance in your BI tool.