Skip to content

Query & visualize your graph

Cypher is a declarative query language for graphs, and should be simple to read and write for anyone who is familiar with SQL. Kùzu’s implementation of Cypher is based on the openCypher standard.

This section will briefly cover how to use Cypher to query the graph created in the previous section. For a detailed guide on using Cypher in Kùzu and to see all the available functions, see the Cypher manual.

Query interfaces

There are three ways you can query an existing Kùzu database:

  • CLI: Write Cypher queries directly in the Kùzu CLI shell
  • Kùzu Explorer: Interactively write and run Cypher queries using Kùzu Explorer, a web-based query interface that also provides graph visualization
  • Client API: Integrate Kùzu with your application in your preferred programming language

Cypher introduction

For simplicity, we’ll demonstrate how to run Cypher queries in this section using Kùzu Explorer — though you are welcome to run the queries via the CLI or your preferred client language API.

The advantage of using Kùzu Explorer to run queries during the prototyping and exploration phase is that you can visualize the graph as you query it. Additionally, you can also view the query results as a table or as JSON, allowing you to easily design your application logic.

Open database in Kùzu Explorer

Run the appropriate version of Kùzu Explorer via Docker as follows:

Terminal window
docker run -p 8000:8000 \
-v /absolute/path/to/demo_db:/database \
--rm kuzudb/explorer:latest

Visualize nodes and rels

The simplest Cypher query one can write is to display all nodes and rels, regardless of the table name, using a MATCH statement as follows:

MATCH (a)-[b]->(c)

Of course, this is a sample graph with only a few nodes/rels. In a real-world scenario, you would likely limit the number of nodes/rels returned by using the LIMIT clause.

MATCH (a)-[b]->(c)

Match nodes of a particular label

You can match on a particular node label using its table name as shown below:

MATCH (a:User) RETURN AS name, a.age AS age;

Note how the name and age properties are aliased in the RETURN statement.

This returns the following result:


Match relationships of a particular label

Similarly, you can match on a particular relationship label using its table name as shown below:

MATCH (a)-[e:Follows]->(b) RETURN e.*;

This returns the following result:


Match with equality predicates on node/rel properties

MATCH (a:User)-[e:Follows {since: 2020}]->(b:User {name: "Karissa"})
RETURN AS user, AS follower, e.since AS follows_since;

This returns:


Note that the predicates on properties are enclosed in curly braces {}. This is functionally equivalent to using a WHERE clause in Cypher. The following query would return the same result:

MATCH (a:User)-[e:Follows]->(b:User)
WHERE e.since = 2020 AND = "Karissa"
RETURN AS user, AS follower, e.since AS follows_since;

Cypher tutorial

The following tutorial covers the basics of Cypher in much greater depth. You can work with it Python by launching the Google Colab notebook in your browser.