<h1 align=center>GrandCypher</h1>
<div align=center><img src="https://img.shields.io/pypi/v/grand-cypher?style=for-the-badge" /> <img alt="GitHub Workflow Status (branch)" src="https://img.shields.io/github/actions/workflow/status/aplbrain/grand-cypher/python-package.yml?branch=master&style=for-the-badge"></div>
```shell
pip install grand-cypher
# Note: You will want a version of grandiso>=2.2.0 for best performance!
# pip install -U 'grandiso>=2.2.0'
```
GrandCypher is a partial (and growing!) implementation of the Cypher graph query language written in Python, for Python data structures.
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 grandcypher import GrandCypher
import networkx as nx
GrandCypher(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 grandcypher import GrandCypher
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")
GrandCypher(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 | ✅ Thanks @khoale88! |
| Backwards `()<-[]-()` edges | ✅ Thanks @khoale88! |
| Anonymous `()` nodes | ✅ Thanks @khoale88! |
| Undirected `()-[]-()` edges | ✅ Thanks @khoale88! |
| Boolean Arithmetic (`AND`/`OR`) | ✅ Thanks @khoale88! |
| `(:Type)` node-labels | ✅ Thanks @khoale88! |
| `[:Type]` edge-labels | ✅ Thanks @khoale88! |
| `DISTINCT` | ✅ Thanks @jackboyla! |
| `ORDER BY` | ✅ Thanks @jackboyla! |
| Aggregation functions (`COUNT`, `SUM`, `MIN`, `MAX`, `AVG`) | ✅ Thanks @jackboyla! |
| Aliasing of returned entities (`return X as Y`) | ✅ Thanks @jackboyla! |
| Negated edges (`where not (a)-->(b)`) | 🥺 |
| `OPTIONAL MATCH` | 🥺 |
| Graph mutations (e.g. `DELETE`, `SET`,...) | 🥺 |
| | | | |
| -------------- | -------------- | ----------------- | ---------------- |
| ✅ = Supported | 🛣 = On Roadmap | 🥺 = Help Welcome | 🔴 = Not Planned |
## Citing
If this tool is helpful to your research, please consider citing it with:
```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}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aplbrain/grandcypher",
"name": "grand-cypher",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Jordan Matelsky",
"author_email": "opensource@matelsky.com",
"download_url": "https://files.pythonhosted.org/packages/bd/91/4b61a4a833eca205791d81310aad061e5c7f82b9ed15b4c51a481be20c7d/grand-cypher-0.10.0.tar.gz",
"platform": null,
"description": "<h1 align=center>GrandCypher</h1>\n<div align=center><img src=\"https://img.shields.io/pypi/v/grand-cypher?style=for-the-badge\" /> <img alt=\"GitHub Workflow Status (branch)\" src=\"https://img.shields.io/github/actions/workflow/status/aplbrain/grand-cypher/python-package.yml?branch=master&style=for-the-badge\"></div>\n\n```shell\npip install grand-cypher\n# Note: You will want a version of grandiso>=2.2.0 for best performance!\n# pip install -U 'grandiso>=2.2.0'\n```\n\nGrandCypher is a partial (and growing!) implementation of the Cypher graph query language written in Python, for Python data structures.\n\nYou likely already know Cypher from the Neo4j Graph Database. Use it with your favorite graph libraries in Python!\n\n## Usage\n\n### Example Usage with NetworkX:\n\n```python\nfrom grandcypher import GrandCypher\nimport networkx as nx\n\nGrandCypher(nx.karate_club_graph()).run(\"\"\"\nMATCH (A)-[]->(B)\nMATCH (B)-[]->(C)\nWHERE A.club == \"Mr. Hi\"\nRETURN A.club, B.club\n\"\"\")\n```\n\nSee [examples.md](docs/examples.md) for more!\n\n### Example Usage with SQL\n\nCreate your own \"Sqlite for Neo4j\"! This example uses [grand-graph](https://github.com/aplbrain/grand) to run queries in SQL:\n\n```python\nimport grand\nfrom grandcypher import GrandCypher\n\nG = grand.Graph(\n backend=grand.backends.SQLBackend(\n db_url=\"my_persisted_graph.db\",\n directed=True\n )\n)\n\n# use the networkx-style API for the Grand library:\nG.nx.add_node(\"A\", foo=\"bar\")\nG.nx.add_edge(\"A\", \"B\")\nG.nx.add_edge(\"B\", \"C\")\nG.nx.add_edge(\"C\", \"A\")\n\nGrandCypher(G.nx).run(\"\"\"\nMATCH (A)-[]->(B)-[]->(C)\nMATCH (C)-[]->(A)\nWHERE\n A.foo == \"bar\"\nRETURN\n A, B, C\n\"\"\")\n```\n\n# Feature Parity\n\n| Feature | Support |\n| ----------------------------------------------------------- | --------------------- |\n| Multiple `MATCH` clauses | \u2705 |\n| `WHERE`-clause filtering on nodes | \u2705 |\n| Anonymous `-[]-` edges | \u2705 |\n| `LIMIT` | \u2705 |\n| `SKIP` | \u2705 |\n| Node/edge attributes with `{}` syntax | \u2705 |\n| `WHERE`-clause filtering on edges | \u2705 |\n| Named `-[]-` edges | \u2705 |\n| Chained `()-[]->()-[]->()` edges | \u2705 Thanks @khoale88! |\n| Backwards `()<-[]-()` edges | \u2705 Thanks @khoale88! |\n| Anonymous `()` nodes | \u2705 Thanks @khoale88! |\n| Undirected `()-[]-()` edges | \u2705 Thanks @khoale88! |\n| Boolean Arithmetic (`AND`/`OR`) | \u2705 Thanks @khoale88! |\n| `(:Type)` node-labels | \u2705 Thanks @khoale88! |\n| `[:Type]` edge-labels | \u2705 Thanks @khoale88! |\n| `DISTINCT` | \u2705 Thanks @jackboyla! |\n| `ORDER BY` | \u2705 Thanks @jackboyla! |\n| Aggregation functions (`COUNT`, `SUM`, `MIN`, `MAX`, `AVG`) | \u2705 Thanks @jackboyla! |\n| Aliasing of returned entities (`return X as Y`) | \u2705 Thanks @jackboyla! |\n| Negated edges (`where not (a)-->(b)`) | \ud83e\udd7a |\n| `OPTIONAL MATCH` | \ud83e\udd7a |\n| Graph mutations (e.g. `DELETE`, `SET`,...) | \ud83e\udd7a |\n\n| | | | |\n| -------------- | -------------- | ----------------- | ---------------- |\n| \u2705 = Supported | \ud83d\udee3 = On Roadmap | \ud83e\udd7a = Help Welcome | \ud83d\udd34 = Not Planned |\n\n## Citing\n\nIf this tool is helpful to your research, please consider citing it with:\n\n```bibtex\n# https://doi.org/10.1038/s41598-021-91025-5\n@article{Matelsky_Motifs_2021,\n title={{DotMotif: an open-source tool for connectome subgraph isomorphism search and graph queries}},\n volume={11},\n ISSN={2045-2322},\n url={http://dx.doi.org/10.1038/s41598-021-91025-5},\n DOI={10.1038/s41598-021-91025-5},\n number={1},\n journal={Scientific Reports},\n publisher={Springer Science and Business Media LLC},\n 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},\n year={2021},\n month={Jun}\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Query Grand graphs using Cypher",
"version": "0.10.0",
"project_urls": {
"Homepage": "https://github.com/aplbrain/grandcypher"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bd914b61a4a833eca205791d81310aad061e5c7f82b9ed15b4c51a481be20c7d",
"md5": "9305190582735dda8690f48052715311",
"sha256": "0443f9701a1bdc1b17c80691500fcd76794df3a636f208c01ff7de69a6156dd5"
},
"downloads": -1,
"filename": "grand-cypher-0.10.0.tar.gz",
"has_sig": false,
"md5_digest": "9305190582735dda8690f48052715311",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 24409,
"upload_time": "2024-10-18T14:00:31",
"upload_time_iso_8601": "2024-10-18T14:00:31.805945Z",
"url": "https://files.pythonhosted.org/packages/bd/91/4b61a4a833eca205791d81310aad061e5c7f82b9ed15b4c51a481be20c7d/grand-cypher-0.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-18 14:00:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aplbrain",
"github_project": "grandcypher",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "grand-cypher"
}
JSON
