Skip to main content

OpenCypher AST and Builder API

Project description

# opencypher

[OpenCypher](https://www.opencypher.org/) AST and Builder API

OpenCypher defines an _abstract syntax tree_ based on the published OpenCypher
[EBNF grammar](https://s3.amazonaws.com/artifacts.opencypher.org/cypher.ebnf)
and a builder-oriented API for constructing Cypher queries.

OpenCypher leans heavily on Python 3.7 `dataclasses` and `typing`.


## Setup

pip install opencypher


## Usage

The core API exposes a fluent builder interface for constructing queries and patterns:

from opencypher.api import match, node

query = match(
node("person", "Person").rel_in().node("pet", "Pet")
).ret(
"person",
"pet",
)

print(query) # MATCH (person:Person)-[]->(pet :Pet) RETURN person, pet

The builder supports chaining patterns and chaining clauses; queries may terminate on either
a return statement (`.ret()`) or on any updating clause (e.g. `create()`, `delete()`, `merge()`,
and so forth.

from opencypher.api import match, node

query = match(
node("alice", "Person", {"name": "Alice"}),
).match(
node("bob", "Person", {"name": "Bob"}),
).merge(
node("bob").rel_in(types="IS_FRIENDS_WITH").node("alice"),
).merge(
node("alice").rel_in(types="IS_FRIENDS_WITH").node("bob"),
)

The resulting `Cypher` query object integrates with -- but does not depend on -- the
[Neo4J Python driver](https://github.com/neo4j/neo4j-python-driver):

from neo4j import GraphDatabase

driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))

with driver.session() as session:
session.run(str(query), dict(query))


## Caveats

Some compromises have been made with respect to the completeness of the AST:

1. The grammar for expressions (and literals, atoms, etc.) has been deliberately simplified
and reduces to `str` in many cases. The expression grammar is likely to get more complete
over time.

2. Some forms of argumementation (e.g. `Set` items) are not easy to construct using the builder
API (although these remain available within the AST).

3. Several top level query clauses are not yet implemented, including:

- `CALL`
- `WITH`

4. Parameters do not automatically generate unique identifiers/prefixes. Parameter names will be
derived from variable names where known, but no fallback exists yet for anonyomous pattern terms.

5. Parameters do not support numeric values (`$1`); symbolic names (`$foo`) *are* supported.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

opencypher-0.3.0.tar.gz (15.7 kB view details)

Uploaded Source

File details

Details for the file opencypher-0.3.0.tar.gz.

File metadata

  • Download URL: opencypher-0.3.0.tar.gz
  • Upload date:
  • Size: 15.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: Python-urllib/3.7

File hashes

Hashes for opencypher-0.3.0.tar.gz
Algorithm Hash digest
SHA256 a4ff374c0abce993eb94eb93cb9b013cb35f2e6f3ee635bda408bfe8097bd2d9
MD5 28daad6c47fa6a56ced1e8036fc9fb98
BLAKE2b-256 e7df25b2b6bdb3179d171e487aa1fd2239fe22403663f01d764a99fac60d533f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page