BKN 知识网络 · Cypher 查询 API (0.1.0)

The Cypher query. Supported shape: MATCH (a:Label [{property: value, ...}]) [-[:RELATION]-(b:Label) ...] [WHERE ] RETURN [DISTINCT] a.property | aggregate(a.property) | | a | r | collect(x) | {k: x} [AS alias], ... [ORDER BY a.property | alias | aggregate(a.property) [DESC]] [SKIP n] [LIMIT n]

or, to filter after aggregating, with WITHs after every MATCH: MATCH ... [WHERE ] WITH a | a.property AS name | aggregate(...) AS name | collect(a.property) AS list, ... [WHERE ] [WITH name | AS name, ... [WHERE ...]] ... RETURN name | a.property | [AS alias], ... [ORDER BY ...] [SKIP n] [LIMIT n] | RETURN count(*) | aggregate([DISTINCT] name) [AS alias], ... [SKIP n] [LIMIT n]

or, to filter by the values of an earlier stage (a semi-join): MATCH ... [WHERE ...] WITH [DISTINCT] a.property AS v | collect(a.property) AS s MATCH ... WHERE b.property = v | b.property IN s [AND ...] RETURN ...

or, to pass nodes on to the next MATCH: MATCH ... [WHERE ...] WITH a, ..., aggregate(...) AS name, ... [WHERE ...] MATCH (a)-[...]-(b...) [WHERE ] RETURN a | b | b.property | name | aggregate(...) | [AS alias], ...

or, to compare two collected lists: MATCH ... [WHERE ...] WITH collect([DISTINCT] a.property) AS l1 MATCH ... [WHERE ...] WITH l1, collect([DISTINCT] b.property) AS l2 RETURN size([x IN l1 WHERE x IN l2]) | size(l1) | size(l2) [AS alias], ...

Each form may open with WITH | [, ...] | $param AS name, ..., whose names the conditions of the MATCH that follows use, as in WITH ['a', 'b'] AS codes MATCH (n:Label) WHERE n.code IN codes.

A condition compares a property with =, <>, <, >, <= or >= against a literal, a parameter or another property (o.shipped < o.ordered, a.code = b.code; properties the model types as a string and a number cannot be compared), or tests it with IN [ ... ], IN $list (the whole list as one parameter), IS NULL or IS NOT NULL. A string property can also be matched with STARTS WITH, ENDS WITH or CONTAINS against a string literal or parameter: the match is a literal substring match (% and _ are not wildcards), a null property never matches, case sensitivity follows the column collation, and using them on a non-string property is refused with 400. Conditions combine with AND, OR and NOT, and parentheses group them. XOR is not supported. Not-equal is written <>; != is read as <> too. A date or time property can be compared with date('2026-08-13'), datetime(...) or localdatetime(...) over a string literal or parameter; functions other than these, coalesce, size (of a list a WITH collected) and the aggregates, and date() with no argument, are refused.

CASE and coalesce compute a value wherever arithmetic may stand: in RETURN, WITH, ORDER BY, either side of a comparison and the argument of an aggregate, as in sum(CASE WHEN g.penalty = '1' THEN 1 ELSE 0 END) or coalesce(o.region, 'unknown'). Both forms of CASE are accepted (CASE WHEN THEN ... and CASE x WHEN v THEN ...); without ELSE an unmatched row gives null. The branches of a CASE, and the arguments of coalesce, must all be numbers or all be other values (a null literal fits either), and none may be a boolean: return the condition itself for that, a boolean property included. Compared with something, a string result takes a string literal, parameter or property on the other side and a number result a number; a string against a number is refused, since MySQL would convert the string. After a WITH a branch's condition may test the names the WITH passed on, including aggregates (CASE WHEN n > 10 THEN ... where n is count(*)); before one, aggregates belong in RETURN, not in a branch's condition. Queries using CASE or coalesce always run on the SQL path.

RETURN can also return a condition, written as in WHERE, as in g.tournament_name CONTAINS 'Men' AS mens. Its value is true, false, or null when the condition cannot be decided (a null property, or a node an OPTIONAL MATCH did not find). Like any other returned value it groups an aggregated result. To sort by a condition, return it with an alias and sort by the alias.

A WITH groups by what it passes on that is not an aggregate; a node groups by its primary key, so two objects that share a name stay two groups. Values in WITH are named with AS. Its WHERE compares those names, properties of the nodes it passed on, values computed from them, literals and parameters: a condition on grouping keys filters rows before grouping, and one on aggregates is tested per group (SQL HAVING). A list a WITH collected is read only as size(list), the count of what it collected. Further WITHs pass on names and values computed from them, each with its own WHERE; only the first may aggregate. RETURN lists the names, properties of the nodes and values computed from them; after a WITH that does not aggregate, count() may follow. After a WITH that aggregates, RETURN may instead aggregate its groups, as in RETURN count() AS groups: then it holds only such aggregates and returns one row. Refused: MATCH after a second WITH, a WITH after the second MATCH other than to compare two lists, WITH DISTINCT, WITH *, ORDER BY / SKIP / LIMIT on WITH, IN / string predicates in its WHERE, and aggregating in a WITH after the first.

Object types bound to a resource outside a SQL data source (a dataset or an index), or read from more than one data source, are read through the resource data API and joined instead of as one SQL statement. There only the basic forms run: CASE, coalesce, totals over groups, comparing two lists, passing nodes on and collect are refused with 400, and a read too large or too slow is refused too. Nodes, relationships and derived relationships are returned as on a SQL data source, and UNION works, each part read on its own.

In the semi-join form each row of the second stage is kept once if its value is among the first stage's, however often the first stage produced it; v may also be an inline property value ({property: v}). The first stage's properties and rows are authorized like any other part of the query. The WITH holds one item; without DISTINCT, RETURN must be DISTINCT and not aggregate. v is used only as = and s only as IN, each as a condition of its own at the top of WHERE (not under OR or NOT).

Passing nodes on joins each row the WITH passed on to the rows the next MATCH finds for its nodes, matched up by primary key; the nodes may be written there without their labels. The WITH's named values may be returned, sorted by and computed with; when the query aggregates, those read in an expression or ORDER BY must also be returned on their own, as grouping keys. They cannot be tested in the next MATCH's WHERE (test them in the WITH's WHERE). Every node passed on must be used in the next MATCH, nodes cannot be renamed or passed beside a collected list, the next MATCH cannot be OPTIONAL, and that WITH takes no DISTINCT, ORDER BY, SKIP or LIMIT. After any WITH, RETURN may return the nodes it passed on. Such a query always runs on the SQL path.

Comparing two lists returns one row of sizes: of each list, and of the elements of one list the other also holds, size([x IN l1 WHERE x IN l2]). A list collected without DISTINCT keeps its repeats, and the shared count counts the filtered list's repeats, as Cypher does; counting both ways round needs DISTINCT on both lists. When the second stage matches nothing there is no row. Neither WITH takes a WHERE, the second MATCH may not use the first list, the lists themselves cannot be returned (to list shared values, share a node in one MATCH), and the two properties must not be a string and a number. UNWIND is refused. Such a query always runs on the SQL path.

RETURN can return a node or a relationship itself. A node is its object type and its full primary key, each key value as exact text with its declared type, plus the properties object_properties names; a relationship is its relation type, the identities of its two ends and the key pairs that joined them. collect(x) gathers x over each group into a list, keeping duplicates and skipping null; {k: x} builds a map. Nodes and relationships group by identity, so RETURN t, count(*) counts per object. Such a query runs as one SQL statement, whatever executor is configured. With collect, each result row is a conclusion, the values beside collect, and LIMIT counts conclusions: every matched row of each conclusion it keeps is collected. The answer is complete or refused: evidence reaching 10000 rows fails with 400 BknBackend.Cypher.ReadBudgetExceeded rather than returning part of it. Graph values cannot be sorted or made DISTINCT, collect cannot be mixed with other aggregates, beside collect only nodes, relationships, properties and constants may be returned and sorting is by the alias of a returned property, and relationships have no properties of their own (r.x is refused).

Aggregates are count, sum, avg, min and max, each also in its DISTINCT form, plus count(*). count(n) counts the rows where node n was found, and count(DISTINCT n) counts distinct objects by their primary key, by all its properties together when it has several (an object type without one is refused). Cypher has no GROUP BY, and writing one is a syntax error that says so: aggregating anything groups by everything else the query returns. A grouped or DISTINCT result can only be sorted by a value it returns.

A MATCH may contain several comma-separated paths, and a query may contain several MATCH clauses; both mean one shape. A variable written twice is the node it named the first time, which is how two paths meet, and paths that share no variable combine pairwise. Two parts that are neither connected nor narrowed by any condition (every row of one table against every row of another) are refused with 400 Unsupported. The first mention of a node names its object type; a later one may omit the label but must not contradict it.

A path may contain several relationships. Each names exactly one relation type and may be written -[:R]->, <-[:R]- or undirected as -[:R]-; each node names exactly one object type and may carry an inline property map, which means the equalities it stands for.

Cypher forbids one MATCH from traversing the same relationship twice, and that is enforced: within one MATCH, every pair of hops over one relation type must differ in its source row or its target row, which needs those object types to have a primary key. Where one of the hops is undirected the requirement cannot be stated, and the query is refused rather than answered with paths Cypher would not return. Hops in different MATCH clauses are not compared: writing MATCH (a)-[:R]->(b) MATCH (a)-[:R]->(c) is how one asks for every pair of things a reaches, b and c being the same included. One query's patterns may hold at most eight relationships and nine nodes, because each relationship is a join and each node is a table -- one that no relationship reaches is joined to the rest by nothing -- and the row limit bounds what comes back rather than what it costs to produce.