nxcypher 1.0.0

Query NetworkX graphs using Cypher syntax. Extended fork of GrandCypher.

nxCypher

nxCypher is an extended fork of GrandCypher, a partial (and growing!) implementation of the Cypher graph query language written in Python, for Python data structures.

pip install nxcypher
# Note: You will want a version of grandiso>=2.2.0 for best performance!

You likely already know Cypher from the Neo4j Graph Database. Use it with your favorite graph libraries in Python!

Usage

Example Usage with NetworkX:

from nxcypher import NXCypher
import networkx as nx

NXCypher(nx.karate_club_graph()).run("""
MATCH (A)-[]->(B)
MATCH (B)-[]->(C)
WHERE A.club == "Mr. Hi"
RETURN A.club, B.club
""")

See examples.md for more!

Example Usage with SQL

Create your own "Sqlite for Neo4j"! This example uses grand-graph to run queries in SQL:

import grand
from nxcypher import NXCypher

G = grand.Graph(
    backend=grand.backends.SQLBackend(
        db_url="my_persisted_graph.db",
        directed=True
    )
)

# use the networkx-style API for the Grand library:
G.nx.add_node("A", foo="bar")
G.nx.add_edge("A", "B")
G.nx.add_edge("B", "C")
G.nx.add_edge("C", "A")

NXCypher(G.nx).run("""
MATCH (A)-[]->(B)-[]->(C)
MATCH (C)-[]->(A)
WHERE
    A.foo == "bar"
RETURN
    A, B, C
""")

Feature Parity

Feature	Support
Multiple MATCH clauses	✅
WHERE-clause filtering on nodes	✅
Anonymous -[]- edges	✅
LIMIT	✅
SKIP	✅
Node/edge attributes with {} syntax	✅
WHERE-clause filtering on edges	✅
Named -[]- edges	✅
Chained ()-[]->()-[]->() edges	✅
Backwards ()<-[]-() edges	✅
Anonymous () nodes	✅
Undirected ()-[]-() edges	✅
Boolean Arithmetic (AND/OR)	✅
(:Type) node-labels	✅
[:Type] edge-labels	✅
DISTINCT	✅
ORDER BY	✅
IN	✅
Aggregation functions (COUNT, SUM, MIN, MAX, AVG)	✅
COUNT(*) aggregate	✅
DISTINCT in aggregates (COUNT(DISTINCT x))	✅
COLLECT() aggregation	✅
Aliasing of returned entities (return X as Y)	✅
Negated edges (WHERE NOT (a)-->(b))	✅
OPTIONAL MATCH	✅
Multiple independent OPTIONAL MATCH	✅
WITH clause	✅
UNWIND clause	✅
Graph mutations (CREATE, SET, DELETE, DETACH DELETE)	✅
REMOVE clause	✅
MERGE clause with ON CREATE/ON MATCH	✅
String functions (toLower, toUpper, trim)	✅
List functions (size, head, tail)	✅
Type functions (type, labels, keys)	✅
CASE expressions (searched and simple)	✅
UNION / UNION ALL	✅
List comprehensions	✅

✅ = Supported	🛣 = On Roadmap	🥺 = Help Welcome	🔴 = Not Planned

Attribution

nxCypher is an extended fork of GrandCypher by APL Brain. The original project provides the foundation for this implementation.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines, including the DCO sign-off requirement.

License

nxCypher is licensed under the Apache License 2.0.

This project implements a subset of the Cypher query language. Cypher is a registered trademark of Neo4j, Inc. This project is not affiliated with or endorsed by Neo4j, Inc.

Citing

If this tool is helpful to your research, please consider citing the original GrandCypher work:

# https://doi.org/10.1038/s41598-021-91025-5
@article{Matelsky_Motifs_2021,
    title={{DotMotif: an open-source tool for connectome subgraph isomorphism search and graph queries}},
    volume={11},
    ISSN={2045-2322},
    url={http://dx.doi.org/10.1038/s41598-021-91025-5},
    DOI={10.1038/s41598-021-91025-5},
    number={1},
    journal={Scientific Reports},
    publisher={Springer Science and Business Media LLC},
    author={Matelsky, Jordan K. and Reilly, Elizabeth P. and Johnson, Erik C. and Stiso, Jennifer and Bassett, Danielle S. and Wester, Brock A. and Gray-Roncal, William},
    year={2021},
    month={Jun}
}