{"id":13656084,"url":"https://github.com/opencypher/cypher-for-gremlin","last_synced_at":"2025-05-15T14:06:53.073Z","repository":{"id":57743433,"uuid":"118768968","full_name":"opencypher/cypher-for-gremlin","owner":"opencypher","description":"Cypher for Gremlin adds Cypher support to any Gremlin graph database.","archived":false,"fork":false,"pushed_at":"2025-03-24T16:01:04.000Z","size":19391,"stargazers_count":364,"open_issues_count":36,"forks_count":46,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-12T12:50:22.756Z","etag":null,"topics":["cypher","graph","gremlin","tinkerpop","tinkerpop3"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opencypher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-01-24T13:27:48.000Z","updated_at":"2025-03-24T16:01:08.000Z","dependencies_parsed_at":"2025-04-12T11:46:03.672Z","dependency_job_id":"f766dc9f-74c7-4afe-a2fd-4e56a4cf15da","html_url":"https://github.com/opencypher/cypher-for-gremlin","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencypher%2Fcypher-for-gremlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencypher%2Fcypher-for-gremlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencypher%2Fcypher-for-gremlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencypher%2Fcypher-for-gremlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opencypher","download_url":"https://codeload.github.com/opencypher/cypher-for-gremlin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254355335,"owners_count":22057354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cypher","graph","gremlin","tinkerpop","tinkerpop3"],"created_at":"2024-08-02T04:00:49.409Z","updated_at":"2025-05-15T14:06:48.053Z","avatar_url":"https://github.com/opencypher.png","language":"Java","funding_links":[],"categories":["Query engines"],"sub_categories":[],"readme":"# **_NOTE:_**  The cypher-to-gremlin transpiler is not maintained anymore.\n\n\n# Cypher for Gremlin\n\n[![CircleCI](https://circleci.com/gh/opencypher/cypher-for-gremlin.svg?style=shield)](https://circleci.com/gh/opencypher/cypher-for-gremlin)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.opencypher.gremlin/translation/badge.svg?style=shield)](https://search.maven.org/#search%7Cga%7C1%7Corg.opencypher.gremlin)\n\nCypher for Gremlin is a toolkit for users of [Apache TinkerPop™](https://tinkerpop.apache.org/) that allows querying Gremlin databases with [Cypher](https://neo4j.com/docs/developer-manual/current/cypher/), the industry's most widely used [property graph](https://github.com/opencypher/openCypher/blob/master/docs/property-graph-model.adoc) query language defined and maintained by the [openCypher](http://www.opencypher.org) project.\n\nCypher query is translated to one of Gremlin representations (Gremlin Groovy string, Traversal object or Gremlin bytecode):\n\n\u003cimg src=\"https://drive.google.com/uc?export=view\u0026id=1HPxZrNkJxrmnd8BlB8YQqX5-pc9TWKUn\" width=\"600\" /\u003e\n\n## Table of Contents\n\n* [Overview](#overview)\n* [Highlights](#highlights)\n* [Quick Start](#quick-start)\n* [Toolkit](#toolkit)\n* [Language Support](#language-support)\n* [Related](#related)\n* [Implementation](#implementation)\n* [Development](#development)\n* [How to contribute](#how-to-contribute)\n* [License](#license)\n* [Copyright](#copyright)\n\n## Overview\n\n\u003cimg src=\"https://drive.google.com/uc?export=view\u0026id=1jSZH9sJtm4sBu8ZoAaEdb7CLXzRWdUlq\" /\u003e\n\n## Highlights\n\n### Gremlin Console Plugin\n\n[Gremlin Console plugin](tinkerpop/cypher-gremlin-console-plugin) that enables client-side translation of Cypher queries \nor communication with a Cypher-enabled Gremlin Server (click to play/[view source](testware/integration-tests/src/test/resources/snippets/console-demo.out)):\n\n\u003cimg src=\"https://drive.google.com/uc?export=view\u0026id=1vncDfbO8o9Ef060SFOBmlQpt4v7etGrJ\" /\u003e\n\n### Gremlin Server Client\n\n[Gremlin Server client](tinkerpop/cypher-gremlin-server-client) wrapper that can send Cypher queries to a Cypher-enabled Gremlin Server or translate Cypher queries to Gremlin on client side, and send translated query to servers:\n\n\u003c!-- [freshReadmeSource](testware/integration-tests/src/test/java/org/opencypher/gremlin/snippets/CypherGremlinServerClientSnippets.java#demo) --\u003e\n```java\nString cypher = \"MATCH (p:person) WHERE p.age \u003e 25 RETURN p.name\";\n\nCluster cluster = Cluster.open(configuration);\nClient gremlinClient = cluster.connect();\n\n// Server has Gremlin Server plugin installed\n// Send Cypher to server\nCypherGremlinClient cypherGremlinClient = CypherGremlinClient.plugin(gremlinClient);\nList\u003cMap\u003cString, Object\u003e\u003e cypherResults = cypherGremlinClient.submit(cypher).all();\n\n// Client side translation\n// Send Gremlin to server\nCypherGremlinClient translatingGremlinClient = CypherGremlinClient.translating(gremlinClient);\nList\u003cMap\u003cString, Object\u003e\u003e gremlinResults = translatingGremlinClient.submit(cypher).all();\n\nassertThat(cypherResults).isEqualTo(gremlinResults);\n\n```\n\n### Gremlin Neo4j Driver\n\n[Implementation of Neo4j API interfaces](tinkerpop/cypher-gremlin-neo4j-driver) for users familiar with Neo4j:\n\n\u003c!-- [freshReadmeSource](testware/integration-tests/src/test/java/org/opencypher/gremlin/snippets/CypherGremlinNeo4jDriverSnippets.java#demo) --\u003e\n```java\nDriver driver = GremlinDatabase.driver(uri);\n\ntry (Session session = driver.session()) {\n    StatementResult result = session.run(\"MATCH (n) RETURN count(n) as count\");\n    int n = result.single().get(\"count\").asInt();\n\n    assertThat(n).isEqualTo(0); // 0\n}\n```\n\n### Gremlin Server Plugin\n\n[Gremlin Server plugin](tinkerpop/cypher-gremlin-server-plugin) that enables Cypher query processing on Gremlin Server. For example connect using [Gremlin-JavaScript](http://tinkerpop.apache.org/docs/current/reference/#gremlin-javascript) 3.4.2+ by setting `processor` to `cypher`:\n\n\u003c!-- [freshReadmeSource](testware/integration-tests/src/test/resources/snippets/gremlin-javascript.js#example) --\u003e\n```js\n// npm install gremlin@3.4.2\n\nconst gremlin = require('gremlin');\nconst client = new gremlin.driver.Client('ws://localhost:8182/gremlin', { traversalSource: 'g', processor: 'cypher'});\nconst cypherQuery = 'MATCH (n) RETURN n.name'\n\nconst results = await client.submit(cypherQuery);\n\nfor (const result of results) {\n  console.log(result);\n}\n```\n\nSee examples for [Gremlin-Java](tinkerpop/cypher-gremlin-server-plugin#gremlin-javagremlin-groovy), [Gremlin-Groovy](tinkerpop/cypher-gremlin-server-plugin#gremlin-javagremlin-groovy), [Gremlin-Python](tinkerpop/cypher-gremlin-server-plugin#gremlin-python) and [Gremlin.Net](tinkerpop/cypher-gremlin-server-plugin#gremlinnet)\n\n### Cypher Traversal Source\n\nFor [Gremlin Console Plugin](https://github.com/opencypher/cypher-for-gremlin/tree/master/tinkerpop/cypher-gremlin-console-plugin#combining-cypher-and-gremlin) and [Gremlin Server Client](https://github.com/opencypher/cypher-for-gremlin/tree/master/tinkerpop/cypher-gremlin-server-client#cypher-traversal-source)\nits possible to combine Cypher and Gremlin in single query. Traversal can start with `cypher` step that allows to run Cypher \nquery (which will be translated to Gremlin and works `withRemote`) then continue traversal using other Gremlin steps:\n\n\u003c!-- [freshReadmeSource](testware/integration-tests/src/test/java/org/opencypher/gremlin/snippets/CypherGremlinServerClientSnippets.java#cypherTraversalSource) --\u003e\n```java\nCypherTraversalSource g = graph.traversal(CypherTraversalSource.class);\n\nGraphTraversal\u003cMap\u003cString, Object\u003e, String\u003e query = g\n    .cypher(\"MATCH (n) RETURN n\")\n    .select(\"n\")\n    .outE()\n    .label()\n    .dedup();\n```\n\n## Quick Start\n\n1. Run [Docker images](docker)\n2. Start experimenting with Cypher for Gremlin with the [Gremlin Console Cypher plugin](tinkerpop/cypher-gremlin-console-plugin). Follow the link for installation and usage instructions.\n3. For API usage take a look at the [Cypher for Gremlin Demo](https://github.com/neueda/cypher-for-gremlin-demo) project.\n\n## Toolkit\n\nThe toolkit is composed of:\n\n- [translation](translation): Cypher to Gremlin translation library for Java\n- [tinkerpop/cypher-gremlin-extensions](tinkerpop/cypher-gremlin-extensions): Extensions to Gremlin to enable full support for Cypher functionality\n- [tinkerpop/cypher-gremlin-server-plugin](tinkerpop/cypher-gremlin-server-plugin): Gremlin Server plugin that enables Cypher query processing (also includes extensions above)\n- [tinkerpop/cypher-gremlin-console-plugin](tinkerpop/cypher-gremlin-console-plugin): Gremlin Console plugin that enables client-side translation of Cypher queries or communication with a Cypher-enabled Gremlin Server\n- [tinkerpop/cypher-gremlin-server-client](tinkerpop/cypher-gremlin-server-client): Gremlin Server client wrapper that can send Cypher queries to a Cypher-enabled Gremlin Server\n- [tinkerpop/cypher-gremlin-neo4j-driver](tinkerpop/cypher-gremlin-neo4j-driver): Neo4j Java API wrapper for users familiar with Neo4j\n\n## Language Support\n\nWith Cypher for Gremlin you can use the following Cypher language features:\n\n- `MATCH` and `OPTIONAL MATCH`\n- `WHERE`, `ORDER BY`, `SKIP`, and `LIMIT` sub-clauses\n- `RETURN`, `WITH`, and `UNWIND` projections, including basic support for list and path comprehensions\n- `CREATE`, `MERGE`, `SET`, `REMOVE`, and `(DETACH) DELETE`\n- `CASE` expressions\n- `UNION (ALL)` operations\n- `CALL` procedures\n\nIt is not guaranteed that all instances and combinations of the listed features will work. However, in addition to [integration tests](testware), correctness of translation is verified by the [Cypher Technology Compatibility Kit](https://github.com/opencypher/openCypher/tree/master/tck) (TCK). The TCK is an openCypher artifact and contains a comprehensive set of test scenarios validating different features of the Cypher language.\n\nCoverage of TCK M13 ([excluding Temporal Types](tinkerpop/cypher-gremlin-extensions#temporal-types)) on TinkerGraph:\n\n- 75% of the scenarios are supported with common Gremlin steps\n- Additional 15% with [extensions](tinkerpop/cypher-gremlin-extensions) to Gremlin to enable full support for Cypher functionality\n- See [latest TCK Report](https://opencypher.github.io/cypher-for-gremlin/test-reports/1.0.4/cucumber-html-reports/overview-features.html) for a detailed overview of language coverage.\n\n\u003cimg src=\"https://docs.google.com/spreadsheets/d/e/2PACX-1vRn3d4ross5VEuEX6m7IZpttIEzzJrtt00UbkDH0UD3A0VAWU7i-ClZU4PSaI3YbDGCQn5vKEX1Hkyr/pubchart?oid=130625852\u0026format=image\" width=\"500\"\u003e\n\nYou are very welcome to report any [issues](https://github.com/opencypher/cypher-for-gremlin/issues) with the translation that you encounter.\n\n### Gremlin Implementations\n\nCypher for Gremlin is tested on following Gremlin implementations:\n\n* With [Gremlin Extensions for Cypher Support](https://github.com/opencypher/cypher-for-gremlin/tree/master/tinkerpop/cypher-gremlin-extensions)\n    - [TinkerGraph](https://github.com/opencypher/cypher-for-gremlin/wiki/Gremlin-implementations#tinkergraph-with-gremlin-extensions-for-cypher-support)\n    - [JanusGraph](https://github.com/opencypher/cypher-for-gremlin/wiki/Gremlin-implementations#janusgraph-with-cypher-plugin)\n    - [Neo4j-Gremlin](https://github.com/opencypher/cypher-for-gremlin/wiki/Gremlin-implementations#neo4j-gremlin-with-cypher-plugin)\n* Without extensions\n    - [TinkerGraph](https://github.com/opencypher/cypher-for-gremlin/wiki/Gremlin-implementations#tinkergraph)\n    - [Neptune](https://github.com/opencypher/cypher-for-gremlin/wiki/Gremlin-implementations#neptune) with `neptune` [flavor](https://github.com/opencypher/cypher-for-gremlin/wiki/Gremlin-implementations#flavors)\n    - [CosmosDB](https://github.com/opencypher/cypher-for-gremlin/wiki/Gremlin-implementations#cosmos-db) with `cosmosDb` [flavor](https://github.com/opencypher/cypher-for-gremlin/wiki/Gremlin-implementations#flavors)\n\nEach Gremlin implementation has its own level of Gremlin support and Gremlin step implementation specifics. In some cases, queries need to be adapted for target implementation using [flavor](https://github.com/opencypher/cypher-for-gremlin/wiki/Gremlin-implementations#flavors). \n\nBecause of these specifics, Cypher support varies on different implementations. Refer to [wiki](https://github.com/opencypher/cypher-for-gremlin/wiki/Gremlin-implementations) for more details.\n\n\u003cimg width=\"600\" src=\"https://docs.google.com/spreadsheets/d/e/2PACX-1vRn3d4ross5VEuEX6m7IZpttIEzzJrtt00UbkDH0UD3A0VAWU7i-ClZU4PSaI3YbDGCQn5vKEX1Hkyr/pubchart?oid=1484632847\u0026amp;format=image\"/\u003e\n\n\u003cimg width=\"600\" src=\"https://docs.google.com/spreadsheets/d/e/2PACX-1vRn3d4ross5VEuEX6m7IZpttIEzzJrtt00UbkDH0UD3A0VAWU7i-ClZU4PSaI3YbDGCQn5vKEX1Hkyr/pubchart?oid=1517076405\u0026amp;format=image\"/\u003e\n\n\n## Related\n\n* [Gizmo](https://github.com/rebar-cloud/gizmo) is a Web UI that makes it easy to interact with TinkerPop graph databases such as AWS Neptune and Azure CosmosDB with the Cypher query language. Uses [Cypher Gremlin Neo4j Driver](tinkerpop/cypher-gremlin-neo4j-driver) for translation.\n* [Graph Database support plugin for JetBrains](https://github.com/neueda/jetbrains-plugin-graph-database-support) allows you to work with Tinkerpop and Neo4j databases using Cypher without leaving IDE. Uses [Cypher for Gremlin](translation) for translation.\n\n## Implementation\n\n\u003cimg src=\"https://drive.google.com/uc?export=view\u0026id=1-7jcZiVaNBfP1-6S9eFemu_NhazIBnqG\" /\u003e\n\nThe translation process uses a reasonably sophisticated and flexible approach. Cypher query is parsed by the [openCypher Frontend](https://github.com/opencypher/front-end) and translated to an [internal representation](translation/src/main/scala/org/opencypher/gremlin/translation/ir/model) by the Cypher for Gremlin. The internal representation is transformed by a set of [rewriters](translation/src/main/scala/org/opencypher/gremlin/translation/ir/rewrite) to adapt the query for system specifics of different Gremlin implementations (JanusGraph, Cosmos DB, AWS Neptune), then converted to one of Gremlin representations (Gremlin Groovy string, Traversal object or Gremlin bytecode).\n\nSee also [How to implement new Cypher feature?](https://github.com/opencypher/cypher-for-gremlin/wiki/How-to-implement-new-Cypher-feature%3F)\n\n## Development\n\nTo build and run Cypher for Gremlin you need Java 8.\nThe project is built using [Gradle](https://gradle.org/) or the provided wrapper.\n\nTo build and run unit and integration tests:\n\n```\n./gradlew build\n```\n\nTo automatically fix formatting errors in your changes:\n\n```\n./gradlew spotlessApply\n```\n\n## How to contribute\n\nWe would love to find out about any [issues](https://github.com/opencypher/cypher-for-gremlin/issues) you encounter and are happy to accept contributions following a Contributors License Agreement (CLA) signature as per the process outlined in our [contribution guidelines](CONTRIBUTING.md).\n\n## License\n\nThe project is licensed under the Apache Software License, Version 2.0\n\n## Copyright\n\n© Copyright 2018-2019 Neo4j, Inc.\n\nApache TinkerPop™, TinkerPop, and Apache are registered trademarks of the [Apache Software Foundation](https://www.apache.org/).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencypher%2Fcypher-for-gremlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopencypher%2Fcypher-for-gremlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencypher%2Fcypher-for-gremlin/lists"}