JDBC Driver - Graph Results

Run Cypher through the JDBC driver’s multimodel extension to read nodes, edges, paths, and their properties. Install the JDBC driver with Prism 2.3 support and enable the Prism interface on a Polypheny server with Prism 2.3 or later.

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.

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.

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 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;

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());
            }

            RelationalResult routes = statement.execute(namespace, "cypher",
                    "MATCH p=(:Person {name: 'Ada'})-[:KNOWS*1..3]->(:Person {name: 'Sam'}) "
                            + "RETURN p AS route, 'trip' AS title").unwrap(RelationalResult.class);
            for (PolyRow row : routes) {
                System.out.println(row.get("title").asString());
                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 the graph result. The second query prints trip followed by the same three names in path traversal order. Remove the fixture afterward with SQL.

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