CyQL
CyQL is the query language for both collections and graphs. If you know Cypher you will be at home immediately; the additions are vector similarity, full-text search and CSV loading as first-class clauses rather than bolted-on functions.
Reading data
A query matches a pattern and returns fields:
MATCH (m:Movie)
WHERE m.released > 2000
RETURN m.title, m.released
ORDER BY m.released DESC
LIMIT 10
MATCH binds a variable to things that fit a pattern, WHERE filters, RETURN projects.
Documents in a collection are matched as label-less, edge-less nodes:
MATCH (d)
WHERE d.category = 'billing'
RETURN d.title, d.body
Vector similarity
SIMILAR TO … ON … TOP ranks matches by meaning:
MATCH (m:Movie)
SIMILAR TO $qv ON embedding TOP 5
RETURN m.title, score(m)
-
The seed is either a vector or text.
$qvis a vector parameter - the query embedding, supplied with the statement. Alternatively, pass text - a string literal (SIMILAR TO 'a heist that goes wrong' ON embedding TOP 5) or a text$parameter- and the server embeds it with the field’s configuredMODEL(the same model the field was written with), so no client-side embedding is needed. A text seed needs aMODELon the field and an embedding provider configured on the server, or the query is refused. Java SDK and Python SDK each show a request carrying a vector. -
ON embeddingnames the vector field, so a record with several vector fields can be searched on each independently. -
TOP 5is how many nearest neighbours to consider. It takes a literal, not a parameter. -
score(m)returns the similarity. It takes the variable it scores, so it isscore(m)here andscore(d)in a collection query - a barescore()will not parse.
WHERE comes after the clauses that belong to the MATCH - the similarity, the full-text search and
the edge pattern - and filters apply before ranking, so a narrow filter still returns a full
result set:
MATCH (m:Movie)
SIMILAR TO $qv ON embedding TOP 10
WHERE m.released > 2000 AND m.genre = 'thriller'
RETURN m.title, m.released, score(m)
ORDER BY score(m) DESC
Full-text search
SEARCH … ON … TOP does BM25 keyword scoring, which beats vector search when the user typed an
exact term - a product code, a name, an error string:
MATCH (d)
SEARCH 'connection timeout' ON body TOP 10
RETURN d.title, score(d)
Running both and combining them is hybrid retrieval, and it is usually better than either alone.
Traversal
Edges are arrow patterns. Direction and type both matter:
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE m.title = 'The Matrix'
RETURN p.name
Bind the edge itself when you want its properties:
MATCH (p:Person)-[r:RATED]->(m:Movie)
WHERE r.stars >= 4
RETURN p.name, m.title, r.stars
Variable-length traversal follows a chain to a bounded depth:
MATCH (p:Person)-[:KNOWS*1..3]->(other:Person)
WHERE p.name = 'Alice'
RETURN other.name
Always bound the depth. An unbounded traversal on a well-connected graph will visit most of it.
Combining vector search and traversal
This is the pattern that motivates the engine: find an entry point semantically, then use structure to gather context.
MATCH (m:Movie)
SIMILAR TO $qv ON embedding TOP 3 -[:ACTED_IN]-(p:Person)
RETURN m.title, p.name, score(m)
Retrieval that includes a record’s neighbourhood gives a language model considerably more to work with than the record alone.
Paging
SKIP (or OFFSET, which means the same thing) with LIMIT:
MATCH (m:Movie)
RETURN m.title
ORDER BY m.title
SKIP 20 LIMIT 10
Always ORDER BY when paging. Without a sort, "page 3" is not a stable idea.
Expressions
RETURN, WHERE and ORDER BY take expressions, not just bare fields. Arithmetic (+ - * / %),
comparisons and the built-in functions all compose:
MATCH (m:Movie)
WHERE m.rating * 2 >= 9 AND toLower(m.title) = 'the matrix'
RETURN m.title, m.rating * 10 AS percent, toUpper(m.genre) AS genre
On a graph query WHERE accepts a general expression on the left, not only a field -
WHERE size(n.name) > 5 or WHERE n.a + n.b > 10 are valid. (A collection WHERE is narrower:
it filters on metadata comparisons and the document id, d.id = <value>, so a function or arithmetic
on the left is rejected there.) + also concatenates strings and lists. Conversion, string, numeric,
temporal and collection functions (toInteger, substring, round, size, coalesce, and more)
are available in any expression position (RETURN, ORDER BY, and a graph WHERE).
Shaping results: WITH, aggregations and UNWIND
WITH projects the row mid-pipeline the way RETURN projects at the end, but lets the query carry on -
rename, filter on the projection, or feed a later clause:
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WITH p, count(m) AS films
WHERE films >= 3
RETURN p.name, films
ORDER BY films DESC
An item that is an aggregate (count, collect, sum, avg, min, max) groups over the other,
non-aggregate items - here one row per p, counting its movies. count(*) counts rows, WITH DISTINCT
(or RETURN DISTINCT) drops duplicate rows, and WITH * carries every bound variable forward.
UNWIND expands a list into one row per element - handy to turn a list field, or a collect(…), back
into rows:
MATCH (m:Movie)
UNWIND m.tags AS tag
RETURN tag, count(*) AS movies
ORDER BY movies DESC
WITH and UNWIND may chain and interleave, each stage re-scoping to its output names for the next.
Writing data
CREATE (m:Movie {title: 'Arrival', released: 2016})
MERGE creates only if nothing matches, which makes an import safe to re-run:
MERGE (p:Person {name: 'Denis Villeneuve'})
Update and delete:
MATCH (m:Movie) WHERE m.title = 'Arrival'
SET m.tagline = 'Why are they here?'
MATCH (m:Movie) WHERE m.released < 1950
DELETE m
An edge is written as part of a pattern, so one statement creates both ends and the edge between them:
CREATE (p:Person {name: 'Denis Villeneuve'})-[:DIRECTED]->(m:Movie {title: 'Arrival'})
Each write statement is one atomic transaction: everything it creates, updates or deletes commits
together or not at all. Several comma-separated patterns in one CREATE share their variables, so a
node can take more than one edge in the same statement:
CREATE (d:Person {name: 'Denis Villeneuve'}), (m:Movie {title: 'Arrival'}), (a:Person {name: 'Amy Adams'}),
(d)-[:DIRECTED]->(m), (a)-[:ACTED_IN]->(m)
Separate statements are separate transactions; there is no BEGIN/COMMIT around several of them.
LOAD CSV (below) is the exception to "one statement, one transaction".
A graph query can chain stages: a WITH re-projects the row, and a later MATCH expands from a
variable the WITH carried forward - a correlated single hop, MATCH (a) WITH a MATCH (a)-[:R]→(b).
(A collection query runs only its leading MATCH; a second, correlated one is rejected, since
documents have no edges to expand along.) What a query still cannot do is bind two unconnected
patterns in one go, so joining two arbitrary existing nodes that share no traversal path is not
expressible; use the edge endpoint on the REST API or addEdge in the SDK for that.
Loading CSV
LOAD CSV bulk-imports without writing a client:
LOAD CSV WITH HEADERS FROM 'movies.csv' AS row
MERGE (m:Movie {title: row.title})
ON CREATE SET m.released = toInteger(row.released)
Each row runs the statement that follows. WITH HEADERS uses the first line for column names, so
row.title refers to a column rather than a position.
The filename is resolved relative to the server’s configured import directory, and cannot escape it -
absolute paths and .. are rejected. That is deliberate: it stops a query being used to read
arbitrary files from the host. See Configuration for the directory setting.
Schema
Collections and graphs can be created and changed in CyQL:
CREATE COLLECTION articles (
VECTOR vector DIMENSION 384 SIMILARITY COSINE,
METADATA title STRING CARDINALITY HIGH,
METADATA body STRING CARDINALITY HIGH FULLTEXT
)
SHOW COLLECTIONS
DESCRIBE COLLECTION articles
Those are three separate statements; send them one at a time. A collection does not need a VECTOR
field - declare only metadata and you get a document store without similarity search. CARDINALITY
picks the index: HIGH for values that are nearly unique per record, LOW for a small repeated set.
FULLTEXT is what makes a field usable with SEARCH.
A field name may be any identifier. To name a field after a reserved word - score, order, limit,
return and the like - backtick-quote it: METADATA when you declare it, and
score FLOAT n. when you read or filter it. The backticks satisfy the parser; the stored name must
still be made of letters, digits, score _, . and - (up to 64 characters), so a reserved word works but
arbitrary characters do not.
ALTER COLLECTION adds fields and indexes to something that already holds data.
CREATE, DROP, SHOW and DESCRIBE are project-scoped, so they go to the project statements endpoint on the platform
port rather than to a collection on the data port. ALTER GRAPH and ALTER COLLECTION are the
exception: they change one existing graph or collection, so they are executed against that graph or
collection on the data port, and the project endpoint refuses them. See REST API for
which port takes which credential.
Parameters
Pass values as named parameters rather than pasting them into the query text. It avoids quoting problems, and it lets the engine reuse a query plan:
MATCH (m:Movie)
SIMILAR TO $qv ON embedding TOP 10
WHERE m.released > $since
RETURN m.title, score(m)
Every interface accepts a parameter map alongside the statement, and vector parameters are passed
separately from scalar ones. TOP is the exception: it takes a literal.
The same goes for the filter of the search APIs (search, multiSearch, hybridSearch,
searchSimilar, listNodes) and the CDC watch predicate: write visibility = $v and bind v in the
request’s filter parameter map. A value concatenated into a filter string can rewrite the predicate
and widen the search to rows the caller should never see; a bound one is always compared as a
literal.
Read-only against read-write
Some entry points only accept reads, which is a safety feature rather than a limitation - it is how you give an agent or a reporting tool query access without also granting it the ability to delete. The MCP tool catalogue splits along the same line; see MCP.