Query HelixDB with Cypher

​

Run a statement

use std::collections::BTreeMap;

let result = client
    .cypher(
        "MATCH (p:Person) WHERE p.age >= $age RETURN p.name AS name ORDER BY name",
        BTreeMap::from([("age".to_string(), serde_json::json!(30))]),
        Some("adults"),
    )
    .await?;
// result.columns == ["name"]; result.rows == [["Ada"], ...]

const result = await client.cypher(
  "MATCH (p:Person) WHERE p.age >= $age RETURN p.name AS name ORDER BY name",
  { age: 30 },
  "adults",
);
// { columns: ["name"], rows: [["Ada"], ...] }

result, err := client.Cypher(ctx, helix.CypherRequest{
	Query:      "MATCH (p:Person) WHERE p.age >= $age RETURN p.name AS name ORDER BY name",
	Parameters: map[string]any{"age": 30},
	QueryName:  "adults",
})
// result.Columns == ["name"]; result.Rows == [["Ada"], ...]

result = client.cypher(
    "MATCH (p:Person) WHERE p.age >= $age RETURN p.name AS name ORDER BY name",
    {"age": 30},
    query_name="adults",
)
# {"columns": ["name"], "rows": [["Ada"], ...]}

{
  "query": "MATCH (p:Person) WHERE p.age >= $age RETURN p.name AS name ORDER BY name",
  "parameters": { "age": 30 },
  "query_name": "adults"
}

{ "columns": ["name"], "rows": [["Ada"], ["Grace"]] }

​

Over HTTP

curl http://localhost:6969/v2/cypher \
  -H 'Content-Type: application/json' \
  --data '{"query":"RETURN $name AS name","parameters":{"name":"Ada"}}'

curl "$HELIX_ENDPOINT/v2/cypher" \
  -H "Authorization: Bearer $HELIX_API_KEY" \
  -H "X-Helix-Database-Id: $HELIX_DATABASE_ID" \
  -H 'Content-Type: application/json' \
  --data '{"query":"MATCH (n) RETURN count(n) AS nodes"}'

​

From the CLI

helix cypher -e 'MATCH (p:Person) RETURN p.name AS name'
helix cypher -e 'RETURN $name AS name' --parameters '{"name":"Ada"}'
helix cypher --file query.cypher --parameters '{"minimumAge":30}'
helix cypher --explain -e 'MATCH (p:Person {name: "Ada"}) RETURN p'

​

Request options

​

Explain a statement

let plan = client
    .explain_cypher(
        "MATCH (p:Person {email: $email}) RETURN p.name AS name",
        BTreeMap::from([("email".to_string(), serde_json::json!("ada@example.com"))]),
        None,
    )
    .await?;
// plan["effect"] == "Read"

const plan = await client.explainCypher(
  "MATCH (p:Person {email: $email}) RETURN p.name AS name",
  { email: "ada@example.com" },
);
// plan.effect === "Read"

plan, err := client.ExplainCypher(ctx, helix.CypherRequest{
	Query:      "MATCH (p:Person {email: $email}) RETURN p.name AS name",
	Parameters: map[string]any{"email": "ada@example.com"},
})
// plan["effect"] == "Read"

plan = client.explain_cypher(
    "MATCH (p:Person {email: $email}) RETURN p.name AS name",
    {"email": "ada@example.com"},
)
# plan["effect"] == "Read"

{
  "query": "MATCH (p:Person {email: $email}) RETURN p.name AS name",
  "parameters": { "email": "ada@example.com" }
}

​

What is supported

CREATE (a:Person {name: 'Ada', age: 30})-[:KNOWS {since: 2020}]->(b:Person {name: 'Bob', age: 40})
RETURN a.name AS person, b.name AS friend

MATCH (a:Person)-[:KNOWS]->(b:Person)
WHERE a.age >= $minimumAge
RETURN a.name AS person, collect(b.name) AS friends
ORDER BY person

​

What is not supported

• CREATE INDEX ... is a syntax_error (unexpected_syntax). Create indexes with the native secondary, vector, and text index APIs; Cypher planning then uses compatible indexes automatically.
• A relationship in CREATE needs exactly one type and a direction, otherwise the statement is a syntax_error (no_single_relationship_type).
• A parameter map in a MATCH pattern, such as MATCH (n:User $props), is a syntax_error (invalid_parameter_use). Write the properties as a map literal, such as {email: $email}.
• An unrecognized function name is a syntax_error (unknown_function).
• A statement that is also invalid openCypher reports the standard error, such as variable_already_bound for a CREATE that redeclares a variable.

​

Values and parameters

​

Writes and transactions

• A created node needs exactly one non-empty label, and a created relationship exactly one non-empty type. MATCH without a label scans all nodes.
• Stored properties are scalars or lists of one scalar type. Maps and nested lists can be used in expressions but not stored, so storing one fails the statement.
• SET n += {...} updates the given keys and keeps the rest. SET n = {...} replaces every user property. Setting a property to null removes it. SET items run in order, so later items see earlier changes.
• A plain DELETE of a node that still has relationships fails the statement. DETACH DELETE removes the relationships and the node.
• Index rules still apply: a value an index cannot store fails the statement, including a string too large for an index key (about 64 KiB).
• Do not retry a write automatically when its commit outcome is uncertain; see error handling.

MATCH (p:Person {name: 'Ada'})
SET p += {age: 31, nickname: null}
RETURN properties(p) AS person

​

Functions, aggregation, and grouping

• toInteger() and toInt() convert decimal strings exactly, including scientific notation, and truncate fractions toward zero: toInteger('9007199254740993.0') returns 9007199254740993. Invalid text and values outside the signed 64-bit range return null.
• avg() ignores nulls, returns null for an empty group, and returns a float. A large total does not overflow while the inputs are finite. sum() reports integer overflow.
• Expressions in RETURN or WITH without aggregates define the groups. In an expression that mixes aggregation with other operations, everything outside the aggregate’s arguments must be a constant, a parameter, a grouped variable, or a projected property, following the openCypher grouping rules. An ambiguous aggregation is rejected before anything runs.
• ORDER BY can use an aggregate without returning it, as in RETURN 1 + sum(amount) AS total ORDER BY 2 - sum(amount).
• A simple CASE value WHEN ... evaluates value once, and null never matches null; test for a missing value with CASE WHEN value IS NULL THEN .... Only the selected branch is evaluated, but aggregate arguments inside CASE are always evaluated.

MATCH (p:Person)-[:LIVES_IN]->(c:City)
RETURN c.name AS city, count(*) AS people, avg(p.age) AS averageAge
ORDER BY people DESC
LIMIT 10

​

Indexes and performance

• An equality on a labeled node, such as MATCH (u:User {email: $email}) or WHERE u.email = $email, can read an equality index. So can IN lists of up to 64 values and ORed equalities on one property.
• A range such as WHERE u.age >= 21 AND u.age < $max can read a range index, and stops reading as soon as a LIMIT is satisfied.
• ORDER BY on a range-indexed property in the index’s direction, with a range bound and a LIMIT, reads the index in order instead of sorting.
• id(n) = $id and id(n) IN $ids read those nodes directly.
• An equality against an earlier variable, as in UNWIND $ids AS k MATCH (u:User {uid: k}), looks up the index once per row.
• An expansion only reads the relationship types it names, so -[:WROTE|LIVES_IN]-> skips a node’s other relationships.
• LIMIT stops scans and expansions early when the clauses before it cannot fail. Reading a stored property in RETURN can fail, so return whole nodes, or apply WITH ... LIMIT first and read properties afterwards: MATCH (u:User) WITH u LIMIT 10 RETURN u.name.

​

Limits

​

Errors

{
  "error": "unsupported_feature",
  "msg": "the Cypher MVP profile does not support MERGE",
  "details": { "detail": "merge", "phase": "compile", "span": { "start": 0, "end": 5 } }
}

​

Next steps