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:

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

Note

• It’s always recommended to use the absolute path to the database directory in a Docker command.
• If you want to install a specific version of Kùzu Explorer, replace latest with the version number. For example: kuzudb/explorer:0.3.2. The version number of the explorer must match with the version number of Kùzu, so that the storage format is compatible.

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)
RETURN *;

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)
RETURN * LIMIT 10;

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 a.name AS name, a.age AS age;

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

This returns the following result:

name	age
Adam	30
Karissa	40
Zhang	50
Noura	25

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:

user1	user2	follows_since
Adam	Karissa	2020
Adam	Zhang	2020
Karissa	Zhang	2021
Zhang	Noura	2022

Match with equality predicates on node/rel properties

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

This returns:

user	follower	follows_since
Karissa	Adam	2020

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 b.name = "Karissa"
RETURN b.name AS user, a.name 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.

Introduction to Cypher Learn the basics of Cypher in Kùzu