CODEWITHSUNDEEP
syntaxneo4jcypherbnf
jameshfisher
jameshfisher

Reputation: 36403

Is there a Cypher syntax definition anywhere?

I'm looking for a definition of the syntax for the Cypher query language. I tried the docs but they're very vague.

Ideally, I'd like a BNF (or any variant) definition, or one of those "graph" definitions like this or this. Really, anything resembling a formal definition.

Upvotes: 3

Views: 2265

Answers (3)

FrobberOfBits
FrobberOfBits

Reputation: 18002

Update!

Neo4j has changed a lot since this answer was written. In 2017 the simple answer is yes, you can download the grammar files from https://www.opencypher.org/

Below is the old answer, which was accurate in 2014

As far as I can tell, the only formal definition is in the code. That's the bad news.

The good news is that the code uses a scala library to do the parsing which makes the code rules look kinda/sorta like BNF. And there's some documentation on how to read it.

Here's a link into a scala object that defines what a query is.

This general package on github looks to me like it contains all of the cypher command implementations, and should have everything you're asking for.

Code in this package is written in scala, and looks like this:

object Query {
  def start(startItems: StartItem*) = new QueryBuilder().startItems(startItems:_*)
  def matches(patterns:Pattern*) = new QueryBuilder().matches(patterns:_*)
  def optionalMatches(patterns:Pattern*) = new QueryBuilder().matches(patterns:_*).makeOptional()
  def updates(cmds:UpdateAction*) = new QueryBuilder().updates(cmds:_*)
  def unique(cmds:UniqueLink*) = new QueryBuilder().startItems(Seq(CreateUniqueStartItem(CreateUniqueAction(cmds:_*))):_*)
(...)

This matches roughly with the upper right hand quadrant of the Cypher refcard. You can sorta see that there can be a start clause, a match clause, and so on. This includes links to other implementation classes (like UpdateAction which further define clauses considered update actions.

Make sure to also read How Neo4J Uses Scala's Parser Combinator: Cypher's Internals Part 1 for more information on what's going on here, and the mapping between the scala classes and what we'd normally consider EBNF. This blog post is old (2011) and the specific code examples it gives shouldn't be trusted, but I think it has good general information on how the implementation works, and what to look for if you want to understand the EBNF behind cypher.

Upvotes: 5

jjaderberg
jjaderberg

Reputation: 9952

What you are looking for will be available in openCypher. Several items will be released as part of the project, one of the first of which is the BNF grammar.

  • Update 2016-01-30: A first draft of the grammar is now avialable at \https://github.com/opencypher/openCypher/blob/master/grammar.ebnf.
  • Update: 2016-10-17: EBNF and Antlr grammars, TCK, railroad diagrams, and a list of community projects are available at http://www.opencypher.org/#resources

Take a look at the recently announced (Oct 2015) openCypher project. It involves releasing the language specification, among other things.

From the announcement:

1. Cypher reference documentation: A comprehensive user documentation describing use of the Cypher query language with examples and tutorials.

2. Technology compatibility kit (TCK): The TCK consists of a number of tests that a software supplier would run in order to self-certify support for a given version of Cypher.

3. Reference implementation: Distributed under the Apache 2.0 license, the reference implementation is a fully functional implementation of key parts of the stack needed to support Cypher inside a data platform or tool. The first planned deliverable is a parser that will take a Cypher statement and parse it into an AST (abstract syntax tree) representation. The reference implementation complements the documentation and tests by providing working implementations of Cypher – which are permissively licensed – and can be used as examples or as a foundation for one’s own implementation.

4. Cypher language specification: Licensed under a Creative Commons license, the Cypher language specification is a technical expression of the language syntax to enable parsers to auto-generate the query syntax. A full semantic specification is also planned as a part of the openCypher project.

The same announcement also says that the process is open and that it is possible to submit, review and comment on language proposals.

Upvotes: 6

jameshfisher
jameshfisher

Reputation: 36403

(Michael Hunger answered in a comment, so I can't accept his answer. Here's his answer:)

Cypher uses parboiled as parser, the parboiled rule DSL are pretty easy to read and understand. https://github.com/neo4j/neo4j/blob/d18583d260a957ab1a14bd27d34eb5625df42bc5/community/cypher/cypher-compiler-2.2/src/main/scala/org/neo4j/cypher/internal/compiler/v2_2/parser/Clauses.scala

Upvotes: 1

Related Questions