Cypher to AQL Translation Service

Translate Cypher queries to AQL for use with ArangoDB using the arango-cypher2aql service, available for the Arango Contextual Data Platform

The Cypher to AQL service is experimental. The API and supported Cypher subset may change in future releases.

The arango-cypher2aql service translates Cypher queries into AQL (ArangoDB Query Language). You send a Cypher query to the service and receive the equivalent AQL query, which you can then run against your ArangoDB deployment.

This service uses a deterministic parser and translation pipeline. It does not use a Large Language Model (LLM).

Purpose

Bridge to AQL: Get executable AQL that runs on ArangoDB, so you can reuse existing Cypher knowledge or scripts without rewriting them manually.
Single read-query flow: The service focuses on read-only query translation (e.g. MATCH ... RETURN). It does not execute the query; you run the returned AQL yourself against ArangoDB.
API use only: The translation service can be used via an HTTP API but not the web interface of the Contextual Data Platform.

High-level workflow

Start the service:
Use the Arango Control Plane (ACP) to start an instance of the Cypher to AQL service (arango-cypher2aql) in your data platform deployment.
Determine the API path:
The platform exposes the service at a base URL (/cypher2aql/<SERVICE_ID>/v1).
Send a Cypher query:
Send a POST request to the translate endpoint (/cypher2aql) with a JSON body containing your Cypher query string
Receive AQL query:
The response contains both the original Cypher query as well as the translated AQL query in the cypher and AQL attributes when translation succeeds. If the Cypher is unsupported or invalid, the response includes an error flag and message.
Validate the query:
Review the generated AQL query and adjust it if needed.
Run the query:
Execute the returned AQL query against your ArangoDB database.

HTTP API

The service exposes a small HTTP API under the versioned path /v1/. In the examples, replace <EXTERNAL_ENDPOINT> with your data platform endpoint (e.g. data-platform.example.org).

All requests and responses use JSON and the application/json content type.

If your deployment uses a self-signed certificate, you may need to specify the -k or --insecure option of cURL.

Deploy an `arango-cypher2aql` service

Use the ACP service to create a generic service.

POST https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/service

Deploy a Cypher to AQL service with the Arango Control Plane (ACP).

Request Body application/json object

service_name string, required
Set this to the value: "arango-cypher2aql"
The name of the service to deploy, here "arango-cypher2aql".

Responses

200 OK
Successfully deployed the service. It may not be ready immediately for responding to requests.
- serviceInfo object, optional
  Information about the deployed service.
  description string, optional
  A human-readable status message about the deployment.
  Example: "Install complete"
  managingEntity string, optional
  The entity managing the service.
  Example: "ACP"
  namespace string, optional
  The namespace in which the service is deployed.
  serviceId string, optional
  The unique identifier assigned to the service.
  Example: "arango-cypher2aql-z8fue"
  status string, optional
  The deployment status of the service.
  Example: "DEPLOYED"
400 Bad Request
The request body has invalid JSON syntax.
- code integer, optional
  The gRPC status code. 3 corresponds to INVALID_ARGUMENT.
  Example: 3
- details array of objects, optional
  Additional error details (typically empty).
- message string, optional
  A message describing the syntax error.
401 Unauthorized
The data platform has authentication enabled but the request misses or contains invalid credentials.
- message string, optional
  An error message indicating that the request is unauthorized.
  Example: "Unauthorized"
500 Internal Server Error
An internal server error occurred, for example, because the service could not be found or a required field is missing.
- code integer, optional
  The gRPC status code. 13 corresponds to INTERNAL.
  Example: 13
- details array of objects, optional
  Additional error details (typically empty).
- message string, optional
  A message describing the internal error.

Example

curl -s "https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/service" \
  -H "Authorization: bearer <YOUR_TOKEN>" \
  -d '{"service_name":"arango-cypher2aql"}'

Show output

{
  "serviceInfo": {
    "serviceId": "arango-cypher2aql-z8fue",
    "description": "Install complete",
    "status": "DEPLOYED",
    "namespace": "arango",
    "managingEntity": "ACP"
  }
}

Translate Cypher to AQL

POST https://<EXTERNAL_ENDPOINT>:8529/cypher2aql/:serviceIdPostfix/v1/cypher2aql

Translates a query string from Cypher to AQL.

Path Parameters

serviceIdPostfix string
The trailing segment of the arango-cypher2aql service identifier (after the last -).
Example: z8fue

Query Parameters

HTTP Headers

Request Body application/json object

cypher string, required
The Cypher query to translate.
database string
Reserved for future use; can be omitted.

Responses

200 OK
Translation result. When translation succeeds, error is false. When the Cypher query is invalid or uses unsupported features, the service still returns the HTTP status code 200 but sets error to true, errorCode to 422, and errorMessage to an explanation of the problem.
- AQL string
  The translated AQL query when successful; empty on translation failure.
- cypher string
  The original Cypher query.
- error boolean
  false on success; true when translation failed or request was invalid.
- errorCode number
  0 on success; 422 on translation failure; 400 on client error.
- errorMessage string
  Empty on success; short explanation of the error otherwise.
400 Bad Request
The request body is missing, not valid JSON, or cannot be read.
- AQL string
  Empty string.
- cypher string
  Empty string.
- error boolean
  Always true for this status code.
  Example: true
- errorCode number
  Always 400 for this status code.
  Example: 400
- errorMessage string
  A message describing why the request body could not be parsed.
401 Unauthorized
The data platform has authentication enabled but the request misses or contains invalid credentials.
- message string, optional
  An error message indicating that the request is unauthorized.
  Example: "Unauthorized"

Example: successful translation

curl -s -X POST "https://<EXTERNAL_ENDPOINT>:8529/cypher2aql/<SERVICE_ID>/v1/cypher2aql" \
  -H "Content-Type: application/json" \
  -H "Authorization: bearer <YOUR_TOKEN>" \
  -d '{"cypher":"MATCH (n:Person) RETURN n"}'

Show output

{
  "cypher": "MATCH (n:Person) RETURN n",
  "AQL": "FOR n IN person FILTER n != null RETURN n",
  "error": false,
  "errorMessage": "",
  "errorCode": 0
}

Get the service version

GET https://<EXTERNAL_ENDPOINT>:8529/cypher2aql/:serviceIdPostfix/v1/version

Returns the service version.

Path Parameters

serviceIdPostfix string
The trailing segment of the arango-cypher2aql service identifier (after the last -).
Example: z8fue

Query Parameters

HTTP Headers

Responses

200 OK
Version identifier of the service.
- version string, optional
  Version identifier of the service.
  Example: "0.9.5"
401 Unauthorized
The data platform has authentication enabled but the request misses or contains invalid credentials.
- message string, optional
  An error message indicating that the request is unauthorized.
  Example: "Unauthorized"

Example

curl -s "https://<EXTERNAL_ENDPOINT>:8529/cypher2aql/<SERVICE_ID>/v1/version" \
  -H "Authorization: bearer <YOUR_TOKEN>"

Show output

{
  "version": "0.9.5"
}

Check the service health

GET https://<EXTERNAL_ENDPOINT>:8529/cypher2aql/:serviceIdPostfix/v1/health

Returns a simple health status.

Path Parameters

serviceIdPostfix string
The trailing segment of the arango-cypher2aql service identifier (after the last -).
Example: z8fue

Query Parameters

HTTP Headers

Responses

200 OK
The health status.
- status string, optional
  The service is healthy.
  Example: "ok"
401 Unauthorized
The data platform has authentication enabled but the request misses or contains invalid credentials.
- message string, optional
  An error message indicating that the request is unauthorized.
  Example: "Unauthorized"

Example

curl -s "https://<EXTERNAL_ENDPOINT>:8529/cypher2aql/<SERVICE_ID>/v1/health" \
  -H "Authorization: bearer <YOUR_TOKEN>"

Show output

{
  "status": "ok"
}

Uninstall a `arango-cypher2aql` service

Use the ACP service to delete the service.

DELETE https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/service/:serviceId

Stop a service using the Arango Control Plane (ACP).

Path Parameters

serviceId string
The identifier of the service to stop, here the ID of the arango-cypher2aql service.
Example: arango-cypher2aql-z8fue

Query Parameters

HTTP Headers

Responses

200 OK
The service was successfully stopped.
- serviceInfo object, optional
  Information about the uninstalled service.
  description string, optional
  A human-readable status message about the uninstallation.
  Example: "Uninstallation complete"
  managingEntity string, optional
  The entity that managed the service.
  Example: "ACP"
  namespace string, optional
  The namespace the service was deployed in.
  serviceId string, optional
  The unique identifier assigned to the service.
  Example: "arango-cypher2aql-z8fue"
  status string, optional
  The status of the service after deletion.
  Example: "UNINSTALLED"
401 Unauthorized
The data platform has authentication enabled but the request misses or contains invalid credentials.
- message string, optional
  An error message indicating that the request is unauthorized.
  Example: "Unauthorized"
500 Internal Server Error
An internal server error occurred, for example, because the service ID is unknown or missing from the request path.
- code integer, optional
  The gRPC status code. 13 corresponds to INTERNAL.
  Example: 13
- details array of objects, optional
  Additional error details (typically empty).
- message string, optional
  A message describing the internal error.

Example

curl -s -X DELETE "https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/service/<SERVICE_ID>" \
  -H "Authorization: bearer <YOUR_TOKEN>"

Show output

{
  "serviceInfo": {
    "serviceId": "arango-cypher2aql-z8fue",
    "description": "Uninstallation complete",
    "status": "UNINSTALLED",
    "namespace": "arango",
    "managingEntity": "ACP"
  }
}

Supported Cypher subset and limitations

The translator supports a subset of Cypher focused on read-only query patterns:

Supported:

Single-statement queries with MATCH, optionally WHERE, ORDER BY, SKIP, LIMIT, WITH, and RETURN.
Node and relationship patterns are constrained (e.g. no variable-length relationships, no OPTIONAL MATCH).
The pattern graph must be connected and acyclic.
Only simple label expressions for nodes and relationship types (no union/intersection-style expressions).
Aggregations are limited to standard aggregation functions.

Not supported:

Schema changes
Write statements (CREATE, DELETE, etc.)
UNION
OPTIONAL MATCH
SHORTEST_PATH
Variable-length relationships
More complex label or type expressions

If you send unsupported or invalid Cypher, the service returns an errorMessage describing the issue. Use that message to adjust your query or fall back to writing AQL directly.

Cypher to AQL Translation Service

Purpose

High-level workflow

HTTP API

Deploy an arango-cypher2aql service

Translate Cypher to AQL

Get the service version

Check the service health

Uninstall a arango-cypher2aql service

Supported Cypher subset and limitations

Deploy an `arango-cypher2aql` service

Uninstall a `arango-cypher2aql` service