JDBC Driver - Graph Results

Run Cypher through the JDBC driver’s multimodel extension to read nodes, edges, paths, and their properties. The examples use JDBC driver 3.2 and a server build with Cypher over Prism. Install the JDBC driver

Choose a result type

Open a JDBC connection and call connection.unwrap(PolyConnection.class).createPolyStatement(). Pass the graph namespace, cypher, and the query text to PolyStatement.execute. The table shows the default result format, auto.

Cypher projection Result type How to read it
RETURN n, RETURN r, or RETURN p for a node, relationship, or path GRAPH Iterate GraphResult to read projected nodes and edges as one sequence. A path appears as alternating nodes and edges in traversal order.
RETURN n.name AS name RELATIONAL Iterate RelationalResult and read the named scalar column.
RETURN n AS person, n.name AS name or RETURN p AS route, 'trip' AS title RELATIONAL Read graph values and scalar values by column alias. Each node, edge, path, or graph occupies one cell.

Check Result.getResultType() before calling unwrap when the projection is chosen at runtime. An empty mixed projection still returns a RelationalResult with column metadata.

Call connection.setClientInfo("CypherResultFormat", "relational") to keep the columns, row boundaries and null cells even when every projected value is a graph value. In this mode, RETURN p AS route returns an intact path in a single cell. Call connection.setClientInfo("CypherResultFormat", "auto") to restore automatic selection. The setting applies to subsequent executions on that connection. Prism result formats

Read nodes, edges, paths, and graphs

Each item in a GraphResult is a PolyGraphElement whose concrete type is PolyNode or PolyEdge. Use getId() for the element ID, getLabels() for its labels, and getProperties() for a read-only map of property names to TypedValue instances. To look up one property, use get("property"). It returns Java null when the property is absent.

  • PolyEdge.getLeft() and getRight() return the stored endpoint IDs. getDirection() describes the stored direction relative to those endpoints.
  • In a relational row, use asNode(), asEdge(), asPath(), or asGraph() on the cell. These readers return Java null for a Prism null.
  • PolyPath.getNodes() and getEdges() follow traversal order. Edge i connects nodes i and i + 1. A path can revisit a node. Traversing an edge in reverse leaves its stored orientation intact.
  • PolyGraph.getNodes() includes isolated nodes, and getEdges() returns the graph’s edges. The lists have unspecified order.

Fetch pages

Set PolyStatement.setFetchSize(int) before execution to request a page size in projected rows. Flattening a path can add several graph elements for one row. Iteration fetches additional pages on demand and keeps the fetched items in memory for subsequent iterators. Consume each result before reusing its statement and use try-with-resources to release the statement and connection when you finish. See request timeouts for handling a stalled response or failed fetch.

Run a Cypher example

In a development database, create a graph namespace using SQL.

CREATE GRAPH NAMESPACE jdbc_demo_graph;

Switch to jdbc_demo_graph in the Cypher interface and run the fixture.

CREATE (:Person {id: 1, name: 'Ada'})-[:KNOWS]->
       (:Person {id: 2, name: 'Lin'})-[:KNOWS]->
       (:Person {id: 3, name: 'Sam'})

Save this example as JdbcGraphExample.java. It uses the local development endpoint by default. Set POLYPHENY_JDBC_URL, POLYPHENY_USER, and POLYPHENY_PASSWORD for a different connection.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.Collections;
import org.polypheny.jdbc.PolyConnection;
import org.polypheny.jdbc.multimodel.GraphResult;
import org.polypheny.jdbc.multimodel.PolyRow;
import org.polypheny.jdbc.multimodel.PolyStatement;
import org.polypheny.jdbc.multimodel.RelationalResult;
import org.polypheny.jdbc.types.PolyGraphElement;
import org.polypheny.jdbc.types.PolyNode;
import org.polypheny.jdbc.types.PolyPath;
import org.polypheny.jdbc.types.TypedValue;

public class JdbcGraphExample {
    public static void main(String[] args) throws SQLException {
        String url = System.getenv().getOrDefault(
                "POLYPHENY_JDBC_URL", "jdbc:polypheny://localhost:20590");
        String user = System.getenv().getOrDefault("POLYPHENY_USER", "pa");
        String password = System.getenv().getOrDefault("POLYPHENY_PASSWORD", "");
        String namespace = "jdbc_demo_graph";

        try (Connection connection = DriverManager.getConnection(url, user, password);
             PolyStatement statement = connection.unwrap(PolyConnection.class).createPolyStatement()) {
            statement.setFetchSize(1);
            GraphResult people = statement.execute(namespace, "cypher",
                    "MATCH (n:Person) RETURN n ORDER BY n.id").unwrap(GraphResult.class);
            for (PolyGraphElement person : people) {
                System.out.println(person.get("name").asString());
            }

            connection.setClientInfo("CypherResultFormat", "relational");
            statement.prepareNamed(namespace, "cypher",
                    "MATCH p=(source:Person)-[:KNOWS*]->(target:Person) "
                            + "WHERE source.name = $start AND target.name = 'Sam' "
                            + "RETURN p AS route");
            RelationalResult routes = statement.executePrepared(
                    Collections.singletonMap("start", TypedValue.fromString("Ada")))
                    .unwrap(RelationalResult.class);
            for (PolyRow row : routes) {
                PolyPath route = row.get("route").asPath();
                for (PolyNode node : route.getNodes()) {
                    System.out.println(node.get("name").asString());
                }
            }
        }
    }
}

If you use the bundled JAR directly, save it as polypheny-jdbc-driver.jar next to the example.

javac -cp polypheny-jdbc-driver.jar JdbcGraphExample.java
java -cp .:polypheny-jdbc-driver.jar JdbcGraphExample

The first query prints Ada, Lin, and Sam from a flat graph result. The second binds the starting name, follows the unbounded [:KNOWS*] pattern, and prints the same three names in traversal order from a typed path cell. Remove the fixture afterward with SQL.

DROP NAMESPACE jdbc_demo_graph;
© Polypheny GmbH. All Rights Reserved.