Goals This guide will show some of the syntax recommendations for building clean, easy-to-read Cypher queries. At the end of this page, you will know how to improve readability of keywords, properties, labels, clauses, and other components. Prerequisites You should… Read more →
This guide will show some of the syntax recommendations for building clean, easy-to-read Cypher queries. At the end of this page, you will know how to improve readability of keywords, properties, labels, clauses, and other components.
There are a few recommended ways to format and organize Cypher queries so that data naming and formatting is consistent and easy-to-read. The next few paragraphs will show the recommendations with some examples.
Styling in the Data Model
Formatting nodes, relationships, labels, and properties help to make queries cleaner. If each of these components has a different style, then it is easy to pick out these items in a query and visually separate each to understand the syntax better. Let us look at each recommendation.
Node labels are styled in CamelCase where the first letter of each word begins with a capital letter. They are also case-sensitive. This means that however you create them in the graph must match the queries you plan to run later. For instance, if you use incorrect camelcase when you create the label in the graph, then you will need to write your queries with the same incorrect camelcasing.
Relationship types are styled with all upper-case and use the underscore between words. They are case-sensitive, so queries syntax must match the format in which they were created in the database.
Property Keys, Variables, Parameters, Aliases, and Functions
Property keys, variables, parameters, aliases, and functions are styled in camelCase where the first letter of the component begins with a lower-case letter, and the first letter of each following word is a capital letter. All of these are also case-sensitive, so capitalization must match either what is in the database (properties), what is already defined in the query (variables, parameters, aliases), or Cypher definitions (functions).
Clauses are styled in all capital letters, placed at the beginning of a new line, and are not case sensitive.
It is possible to change casing (
mAtCh), put multiple keywords on a line, or mistype clauses.
Cypher will still execute the query.
However, for readability and supportability of queries, we recommend clauses are in all capital letters and placed at the beginning of a new line.
Keywords, similar to clauses, should be styled in all capital letters and are not case-sensitive, but do not need to be placed on a separate line.
This includes words such as
AND, and others.
Indentation and Line Breaks
As we started with above, separating clauses to new lines helps with readability of queries and breaking logic into visual blocks.
We can also make queries a bit easier to read by indenting
ON CREATE or
ON MATCH and any subqueries.
Each of these blocks is indented with 2 spaces on a new line.
Notice that in the query with a subquery, we use braces to group the subquery block (similar to methods or functions in other programming languages).
The beginning curly brace is on the same line as the start of the subquery (
The two lines of subquery (
MATCH…WHERE) are indented with 2 spaces, and then the closing curly brace is on the next line with no indent.
If the subquery is only one line, you do not need to put it on its own line or indent it. Instead, you can write it like the query below. These are the recommended guidelines if you need to use a subquery.
Metacharacters include things like single or double quotes, backticks, and semicolons. In Cypher, there are special uses and recommended cases for using these characters. They are easily misused, so we will show what to avoid, as well as proper use of them.
It is recommended to use single quotes for literal string values. There are exceptions to this rule, however, when single quotes are part of the string. If the string has both double and single quotes, use the form that creates the fewest escaped characters. In the case of a tie, preference is still to use single quotes.
Backticks should be avoided to escape characters and keywords. In the examples below, backticks are used to ignore special characters and spaces in properties and labels.
If we follow the recommended styling guidelines on those components that we discussed above with camelcasing and joined words, then we should never see these types of backticks needed. Note that there are some cases with certain string values or other unusual syntax where backticks are appropriate.
Clean, recommended syntax:
Most of the time, there is no need to use a semicolon at the end of a Cypher query. Adding a semicolon to the end of a Cypher query is a redundant character because Cypher executes the block as an entire unit.
The exception to this is when you have a Cypher script or a block with multiple, separate Cypher statements. In this case, you would need the semicolon to tell Cypher where the end of one query is and the beginning of the next query. This allows Cypher to execute each statement separately.
If you do not include a semicolon between a block with multiple statements, Cypher will try to execute them as a single statement, causing an error.
Recommended syntax for multi-query block:
Null and Boolean Values
null value and boolean literals should be written in lower case in a query.
Dealing with Patterns
There are a few recommended styling practices for different scenarios using patterns. We will review those in the lines below.
- When you have patterns that wrap lines, it is recommended to break after arrows, not before.
- Use anonymous nodes and relationships when the variable will not be used later in the query.
- Chain patterns together to avoid repeating variables.
Unnecessary variable repeated:
Put named nodes (that use variables) before anonymous nodes and relationships when possible and put anchor node (starting point or central focus) at the beginning of the
- Prefer outgoing (left to right) pattern relationships to incoming pattern relationships.
Whether spacing is used and where it is placed can have a big impact on the readability of queries. In the next few examples, we will show some comparisons of less effective spacing, as well as the recommmended practice.
- One space between label or type predicates and property predicates in patterns.
- No space in label predicates.
- No space in patterns.
- One space on either side of operators.
- One space after each comma in lists and enumerations.
- No padding space within function call parentheses.
- Use padding space within simple subquery expressions.
Map Literal recommendations –
- No space between opening brace and first key or between key and colon
- One space between colon and value
- No space between value and comma, but one space between comma and next key
- No space between last value and closing brace
Now that you are familiar with recommended styling and formatting of Cypher syntax, you will be able to write cleaner and more readable queries. This is especially helpful for knowledge tranfers to other developers and supportability of the code.
In the next guide, we will show how to ensure good data integrity using indexes and constraints to maintain uniqueness and query performance.