Skip to content
Kùzu
Blog

Syntax

In this page, we list the syntactic features of Cypher as implemented in Kùzu. As described in the overview page, Cypher is a declarative graph query language, and Kùzu’s implementation is based on openCypher.

Parsing

Encoding

The Cypher query parser looks for an input STRING that consists of ASCII or unicode characters from non-English languages. An example is shown below for creating and querying from a node table of German books.

// Create a node table of books in German
CREATE NODE TABLE Bücher (title STRING, price INT64, PRIMARY KEY (title))
CREATE (n:Bücher {title: 'Der Thron der Sieben Königreiche'}) SET n.price = 20
// Query using the unicode representation of the table name
MATCH (n:Bücher) RETURN label(n)
┌─────────┐
│ Bücher  │
│ STRING  │
├─────────┤
│ Bücher  │
└─────────┘

Escaping

To use special characters in identifiers, you can escape them by encapsulating the identifier in backticks `. An example is shown below for creating a node table of house names that contain special characters.

// Create a node table of house names that contain special characters
CREATE NODE TABLE `HouseΨ` (id INT64, member STRING, PRIMARY KEY (id))
CREATE (n:`HouseΨ` {id: 1}) SET n.member = 'Alice'
// Query on the unicode table name
MATCH (n:`HouseΨ`) RETURN n.*
┌───────┬──────────┐
│ n.id  │ n.member │
│ INT64 │ STRING   │
├───────┼──────────┤
│ 1     │ Alice    │
└───────┴──────────┘

Multiline statements and termination

Breaking a query into multiple lines is allowed (and recommended for readability reasons). The query parser ignores leading and trailing whitespaces.

MATCH (a:Person)
WHERE a.age < 30
RETURN a.*;

Termination is always indicated by a semicolon ;, and the parser looks for this symbol to know when a statement is complete.

Clauses

A Cypher query may contain one or more clauses and their associated subclauses, and can span multiple lines. The end of a statement is marked with a semicolon ;, and the query parser looks for this symbol to know when a statement is complete.

Examples of clauses include:

  • MATCH: Find patterns in the graph
  • RETURN: Specify what subset of the matched data to return

Examples of subclauses (that must reside under a clause) include:

  • WHERE: Filter the results of a MATCH clause
  • LIMIT: Limit the number of results returned by a query

Comments

Comments are for humans to read and document their code, and are ignored by the query parser.

  • Single line comments begin with a double slash (//) and continue up until the end of the line. They can be placed at the beginning, in the middle, or at the end of a query.
  • Multi-line comments begins with a slash and asterisk (/*) and continues until it ends with an asterisk and a slash (*/). They can be useful for comments that are too long for one line.

Some examples are below.

// Whole-line comment before a query
MATCH (a:Person) RETURN a.*
MATCH (a:Person) RETURN a.*  // Comment at the end of a query
MATCH (a:Person)
// Comment in the middle of a query
WHERE a.age < 30
RETURN a.*
/*
This is a comment
spanning multiple lines
*/
MATCH (a:Person) RETURN a.*

Naming rules and recommendations

As a general rule of thumb, ensure the following:

  • Names should begin with an valid alphabetic character of type unicode string — Person, CarOwner
  • Names should not begin with a number — 1Person is invalid, but Person1 is valid
  • Names should not contain whitespaces or special characters other than underscores — CarOwner is valid, but Car Owner is invalid
  • Names are generally case-insensitive — Person is the same as person, during table creation and querying

The following naming conventions are recommended for node and relationship tables:

TypeNaming conventionDoDon’t
Node tablesCamelCase (begin with upper case letter)CarOwnercar_owner
Relationship tablesCamelCase or UPPERCASE separated by underscoresIsPartOf/IS_PART_OFisPartOf or is_part_of

Parameters

Parameters in Cypher queries are placeholders for values that are provided at runtime. Parameters are prefixed with a dollar sign $ and can be used in any part of a query. They are useful for preventing Cypher injection attacks, and for reusing query templates with different values.

See the prepared statements guide for more information on how to use parameters in Kùzu.

Reserved keywords

Reserved keywords are words that have a special meaning in Cypher. They cannot be used as identifiers in the following contexts:

  • Variables
  • Function names
  • Parameters

To use a reserved keyword as an identifier in the above contexts, you can escape it by encapsulating the keyword in backticks `, such as `DEFAULT`, and this makes it a valid identifier.

The following list shows the reserved keywords in Cypher, organized by category:

Clauses

  • COLUMN
  • CREATE
  • DBTYPE
  • DEFAULT
  • GROUP
  • HEADERS
  • INSTALL
  • MACRO
  • OPTIONAL
  • PROFILE
  • RDFGRAPH
  • UNION
  • UNWIND
  • WITH

Subclauses

  • LIMIT
  • ONLY
  • ORDER
  • WHERE

Expressions

  • ALL
  • CASE
  • CAST
  • ELSE
  • END
  • ENDS
  • EXISTS
  • GLOB
  • SHORTEST
  • THEN
  • WHEN

Literals

  • NULL
  • FALSE
  • TRUE

Modifiers

  • ASC
  • ASCENDING
  • DESC
  • DESCENDING
  • ON

Operators

  • AND
  • DISTINCT
  • IN
  • IS
  • NOT
  • OR
  • STARTS
  • XOR

Schema

  • FROM
  • PRIMARY
  • TABLE
  • TO