How to Query Neo4j from Virtuoso (using Cypher)
Virtuoso’s Virtual Database Layer functionalites make it possible to run Neo4j’s native Cypher queries directly from within Virtuoso SQL.
By integrating Neo4j through the Lite Edition ODBC-JDBC Bridge, you can seamlessly query your graph data, blend results with existing SQL tables, or convert results into RDF Views—all without leaving Virtuoso.
This guide provides step-by-step instructions to configure this powerful capability.
Prerequisites
Before you start, ensure the following components are properly set up:
- A working connection to a Neo4j instance via the latest Neo4j JDBC Driver
- A working Lite Edition ODBC-JDBC Bridge installation
- Free Trials
- Windows
- macOS (Apple Silicon,Intel)
- Linux/Unix
- Free Trials
- A running Virtuoso Commercial Edition instance
- Free Trials
Step-by-Step Guide
1. Create an ODBC DSN for Neo4j JDBC Driver
Add the following entry to your odbc.ini file:
[neo4j_aura_lt]
Driver = {JDBC Driver Location}
Description =
DeferLongFetch =
MaxRows =
JetFix = No
NoRowSetSizeLimit = No
Options = jdbc:neo4j+s://{Your Neo4j Instance Location}
UserName = neo4j
Password = {Your Neo4j User Password}
InitialSQL =
Database = org.neo4j.jdbc.Neo4jDriver
ReadOnly =
NoAutoCommit = No
NoLoginBox =
FetchBufferSize = 60
SqlDbmsName =
Replace connection parameters (Options, UserName, and Password) with your Neo4j details.
2. Connect Virtuoso to the Neo4j Data Source
Access iSQL using one of the following options:
Web Interface
- HTTP:
http://{cname}:{port}/conductor/isql_main.vspx - HTTPS:
https://{cname}/conductor/isql_main.vspx
Command Line
- Use the
isqltool in your Virtuoso installation’s bin directory.
Once connected, use the following Virtuoso SQL commands to establish and verify the connection:
vd_remote_data_source('neo4j_aura_lt', null, '{Your Neo4j Username}', 'Your Neo4j Password');
vdd_disconnect_data_source('neo4j_aura_lt');
Replace placeholders with your Neo4j username and password.
3. Run a Test Cypher Query
Execute a simple Cypher query directly from Virtuoso SQL to confirm connectivity:
rstmtexec('neo4j_aura_lt', 'RETURN \'Hello World\' as test');
This should return the text “Hello World” if connectivity is successful.
4. Run a Cypher Query Returning Results
You can directly execute Cypher queries and fetch results, as shown below:
rstmtexec('neo4j_aura_lt', 'MATCH (p:Person) RETURN p.name LIMIT 10', 0);
This retrieves the names of up to 10 Person nodes from Neo4j, and provides a result set for easy confirmation.
5. Install Procedure for Running Queries
Using iSQL or your preferred interface, Install the nosql_query stored procedure that sends a Cypher query to Neo4j and returns a usable result set.
This stored procedure can be quickly installed by running:
CREATE PROCEDURE nosql_query(IN dsn VARCHAR, IN query VARCHAR){
DECLARE q VARCHAR;
DECLARE mdta_out any;
DECLARE res_vec_out, param_vec any;
DECLARE sql_state, err_msg varchar;
DECLARE inx integer;
DECLARE num_cols_out integer;
sql_state := '00000';
param_vec := VECTOR('A', 'B');
REXECUTE (dsn, query, sql_state, err_msg, param_vec, num_cols_out, mdta_out, res_vec_out, NULL);
IF (sql_state <> '00000')
{
SIGNAL ('nosql_query', CONCAT ('Remote execution returned ',sql_state, ' ', err_msg));
}
EXEC_RESULT_NAMES (mdta_out[0]);
inx := 0;
WHILE (inx < length (res_vec_out))
{
EXEC_RESULT ( res_vec_out[inx]);
inx := inx + 1;
}
END_RESULT ();
};
6. Query Neo4j via a Derived Table in Virtuoso SQL
After installing the procedure, you can run Cypher queries directly as SQL table sources:
The Syntax is as follows:
SELECT {Columns}
FROM nosql_query(dsn, query)({column 1} {datatype}, ... )
WHERE dsn = '{DSN Name}' AND query='{Cypher Query}'
Make sure to escape single quotes in your cypher query using \'.
Below is a basic test query against the Movies Dataset:
SELECT
x.name
FROM
nosql_query(dsn, query)(name NVARCHAR) x
WHERE
dsn = 'neo4j_aura_lt' AND query = 'MATCH (p:Person) RETURN p.name';
Note: When defining the column datatypes, use NVARCHAR for strings when using the Unicode ODBC-JDBC Bridge Driver, and VARCHAR for ANSI.
This SQL statement directly queries Neo4j, returning results which can then be integrated, joined, or combined with other Virtuoso SQL or SPARQL data sources, in addition to being transformed into RDF Views.
6a. Permissions
By default, only dba can execute newly created stored procedures an access DSN connections.
Using the nosql_query stored procedure requires permissions to be granted on both the procedure and DSN. For Example, SELECT permissions are added to the vdb user using:
GRANT REXECUTE ON 'neo4j_aura_lt' TO vdb;
GRANT EXECUTE ON nosql_query TO vdb;
6b. Live Demonstration
A live demonstration of this functionality is available using Virtuoso’s SPARQL-within-SQL Query Builder (SPASQLQB).
Click on this link and login using vdb as your username, and vdb as your password.
Once Authenticate, the query will run and populate the table with Neo4j Cypher query results from the remote Neo4j Aura Instance.
Modifying the Demo Query
Users of the live demonstration can also modify the query value and return results. The instance contains data from the Neo4j Movies and Northwind Demonstrations.
7. Creating SQL Views and Physical Tables of Cypher Query Results
Optionally, this query can be stored as a SQL view for simplified use:
CREATE VIEW db.dba.neo4j_demo
AS
(
SELECT
x.name,
x.age
FROM
nosql_query(dsn, query)(name NVARCHAR) x
WHERE
dsn = 'neo4j_aura_lt' AND query = 'MATCH (p:Person) RETURN p.name'
);
Or converted to a physical SQL table using:
CREATE TABLE db.dba.neo4j_demo_physical
AS
(
SELECT
x.name,
x.age
FROM
nosql_query(dsn, query)(name NVARCHAR) x
WHERE
dsn = 'neo4j_aura_lt' AND query = 'MATCH (p:Person) RETURN p.name'
)
WITH DATA;
You now have complete flexibility to leverage Neo4j graph queries directly from within your Virtuoso environment.