Metadata-Version: 2.4
Name: nxcypher
Version: 1.0.0
Summary: Query NetworkX graphs using Cypher syntax. Extended fork of GrandCypher.
Author: Gregorio Momm
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.10
Requires-Dist: cachetools>=6.2.1
Requires-Dist: grandiso>=2.2.0
Requires-Dist: lark>=1.2.2
Requires-Dist: networkx>=3.4.2
Description-Content-Type: text/markdown

<h1 align=center>nxCypher</h1>

<p align=center>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a>
</p>

**nxCypher** is an extended fork of [GrandCypher](https://github.com/aplbrain/grand-cypher), a partial (and growing!) implementation of the Cypher graph query language written in Python, for Python data structures.

```shell
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:

```python
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](docs/examples.md) for more!

### Example Usage with SQL

Create your own "Sqlite for Neo4j"! This example uses [grand-graph](https://github.com/aplbrain/grand) to run queries in SQL:

```python
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](https://github.com/aplbrain/grand-cypher) by [APL Brain](https://github.com/aplbrain). The original project provides the foundation for this implementation.

## Contributing

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

## License

nxCypher is licensed under the [Apache License 2.0](LICENSE).

This project implements a subset of the [Cypher](https://opencypher.org) 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:

```bibtex
# 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}
}
```
