<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 [openCypher](https://opencypher.org) graph query language implementation written in Python, for Python data structures. Originally forked from [GrandCypher](https://github.com/aplbrain/grand-cypher).

```shell
pip install nxcypher
```

You likely already know openCypher 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!

## 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 |

## 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 the [openCypher](https://opencypher.org) query language. Cypher is a registered trademark of Neo4j, Inc. This project is not affiliated with or endorsed by Neo4j, Inc.

