Search

relate searches two kinds of indexindex A structure the planner uses to find nodes or relationships by a property without scanning a label: range, text, point, vector or full-text. Read more in the glossary. A vector indexvector index An index over a property holding embeddings that answers nearest-neighbor searches exactly, by cosine or Euclidean similarity. Read more in the glossary answers "which entities are nearest to this vector" with an exact nearest-neighbor search: every search scores each indexed vector and keeps the top LIMIT, ties going to the lower element id; a full-text indexfull-text index An index over one or more string properties that finds entities containing given words, ranked by a BM25 relevance score. Read more in the glossary answers "which entities contain these words". The SEARCH clause restricts a MATCH to an index's top results and names their score. The cells on this page run on relate's WebAssembly (WASM) build, the weighted fusion included; the COMBINE example runs on the CLI, because it needs a preview opt-in.

Synopsis

CREATE VECTOR INDEX <name> [IF NOT EXISTS]
  FOR (<var>:<Label>) ON (<var>.<property>)
  [WITH [<var>.<property>, …]]
  [OPTIONS {indexConfig: {<key>: <value>, …}}]

CREATE VECTOR INDEX <name> [IF NOT EXISTS]
  FOR ()-[<var>:<TYPE>]-() ON (<var>.<property>)
  [WITH [<var>.<property>, …]]
  [OPTIONS {indexConfig: {<key>: <value>, …}}]

CREATE FULLTEXT INDEX <name> [IF NOT EXISTS]
  FOR (<var>:<Label>) ON EACH [<var>.<property>, …]

CREATE FULLTEXT INDEX <name> [IF NOT EXISTS]
  FOR ()-[<var>:<TYPE>]-() ON EACH [<var>.<property>, …]

DROP INDEX <name> [IF EXISTS]

MATCH <pattern that binds var>
SEARCH <var> IN (
  VECTOR INDEX <name> FOR <query vector> [WHERE <filter>] LIMIT <k>
) [SCORE AS <score var>]

MATCH <pattern that binds var>
SEARCH <var> IN (
  FULLTEXT INDEX <name> FOR <query string> [WITH ANALYZER <expr>] [SKIP <n> | OFFSET <n>] LIMIT <k>
) [SCORE AS <score var>]

Index statements

A second vector index on the same label and property with the same WITH [...] list, the same properties in the same order, fails with semantic error: EquivalentSchemaRuleAlreadyExists, whatever its OPTIONS. One with a different WITH [...] list, or none where the first has one, is created beside it. A second full-text index on the same label and properties fails with the same error.

Vector index options

The keys go in OPTIONS {indexConfig: {…}}. They contain dots, so each key is quoted in backticks or single quotes; an unquoted key is a parse error. The defaults are the values SHOW INDEXES reports for an index created without options.

An unknown key fails with semantic error: InvalidInputValue. A property whose vector length differs from vector.dimensions is stored without an error and is never returned by a search. A typed vector, vector(<list>, <dimensions>, FLOAT32), fails the write when the list has another length.

Rules of the search clause

RELATE_PREVIEW=complex-search-patterns lifts the MATCH shape rule. A WHERE after the SEARCH clause, or a property map in the MATCH pattern, filters only the rows the search returned, so the result can hold fewer than LIMIT rows.

Full-text matching

Procedures

Each procedure is deprecated: EXPLAIN reports notification 01N01, The procedure `<name>` is deprecated., with the remedy Use the `SEARCH` clause instead.

Functions

Hybrid search

Three ways combine a vector search and a full-text search in one statement:

COMBINE takes two or more sources, each a complete index specification with its own LIMIT, and the same entity kind as the variable after SEARCH. An entity's fused score is the sum over the sources of weight / (constant + rank + 1), where rank counts from 0 within that source and a source that did not return the entity adds nothing. WEIGHT defaults to 1 and WITH CONSTANT to 60. Equal fused scores order by entity id. Without the opt-in, COMBINE fails with semantic error: SemanticError: preview feature 'hybrid-search' is not enabled: set RELATE_PREVIEW=hybrid-search.

The CALL form computes the same scores without the opt-in: the weighted-fusion cell in Examples returns, digit for digit, the scores the COMBINE run there prints for the same weights and constant.

Examples

The shared example graph, with a focus vector and a short bio on each person:

CREATE (ada:Person {name: 'Ada', role: 'engineer'}),
       (grace:Person {name: 'Grace', role: 'engineer'}),
       (noor:Person {name: 'Noor', role: 'maintainer'}),
       (relate:Project {name: 'relate', language: 'Rust'}),
       (tck:Project {name: 'opencypher-tck', language: 'Gherkin'}),
       (ada)-[:WORKS_ON {since: 2024}]->(relate),
       (grace)-[:WORKS_ON {since: 2023}]->(relate),
       (grace)-[:WORKS_ON {since: 2022}]->(tck),
       (noor)-[:MAINTAINS]->(relate),
       (ada)-[:KNOWS]->(grace);
MATCH (p:Person)
SET p.focus = CASE p.name
      WHEN 'Ada' THEN vector([0.9, 0.1, 0.2], 3, FLOAT32)
      WHEN 'Grace' THEN vector([0.3, 0.9, 0.1], 3, FLOAT32)
      ELSE vector([0.2, 0.3, 0.9], 3, FLOAT32) END,
    p.bio = CASE p.name
      WHEN 'Ada' THEN 'Writes the storage engine in Rust'
      WHEN 'Grace' THEN 'Keeps the conformance tests green'
      ELSE 'Reviews the docs and the tests' END

(no rows) · nodes created: 5, relationships created: 5, properties set: 19, labels added: 5

One index of each kind:

CREATE VECTOR INDEX person_focus IF NOT EXISTS
  FOR (p:Person) ON (p.focus) WITH [p.role]
  OPTIONS {indexConfig: {`vector.dimensions`: 3, `vector.similarity_function`: 'cosine'}};
CREATE FULLTEXT INDEX person_bio IF NOT EXISTS FOR (p:Person) ON EACH [p.bio]

(no rows) · indexes added: 2

A vector search, filtered inside the search:

MATCH (p:Person)
SEARCH p IN (VECTOR INDEX person_focus FOR [0.1, 0.9, 0.1] WHERE p.role = 'engineer' LIMIT 2) SCORE AS score
RETURN p.name AS name, round(score, 4) AS score
ORDER BY score DESC

| name    | score  |
|---------|--------|
| "Grace" | 0.989  |
| "Ada"   | 0.6184 |
2 rows

A full-text search for two words; Noor's bio holds both:

MATCH (p:Person)
SEARCH p IN (FULLTEXT INDEX person_bio FOR 'docs tests' LIMIT 3) SCORE AS score
RETURN p.name AS name, score
ORDER BY score DESC, name

| name    | score               |
|---------|---------------------|
| "Noor"  | 0.6439728198009622  |
| "Grace" | 0.22443993531397488 |
2 rows

The intersection form of hybrid search: the nearest two by vector, kept only if their bio mentions the docs:

MATCH (p:Person)
SEARCH p IN (VECTOR INDEX person_focus FOR [0.1, 0.9, 0.1] LIMIT 2) SCORE AS vs
WITH p, vs
MATCH (p)
SEARCH p IN (FULLTEXT INDEX person_bio FOR 'docs' LIMIT 3) SCORE AS fs
RETURN p.name AS name, round(vs, 4) AS vector, fs AS fulltext
ORDER BY name

| name   | vector | fulltext            |
|--------|--------|---------------------|
| "Noor" | 0.7151 | 0.43535502091904305 |
1 row

Weighted reciprocal rank fusion, the CALL form. The question, its vector and the number of results per list are parameters:

Each search on its own returns a ranked list of at most $k people, with the name as id:

MATCH (p:Person)
SEARCH p IN (VECTOR INDEX person_focus FOR $v LIMIT $k) SCORE AS score
RETURN p.name AS id, score
ORDER BY score DESC, id

| id      | score              |
|---------|--------------------|
| "Grace" | 0.9890228509902954 |
| "Noor"  | 0.7151050567626953 |
| "Ada"   | 0.6183618307113647 |
3 rows

MATCH (p:Person)
SEARCH p IN (FULLTEXT INDEX person_bio FOR $q LIMIT $k) SCORE AS score
RETURN p.name AS id, score
ORDER BY score DESC, id

| id      | score               |
|---------|---------------------|
| "Noor"  | 0.6439728198009622  |
| "Grace" | 0.22443993531397488 |
2 rows

The fused statement runs both searches, numbers each list's rows from 0, and adds weight / (60 + rank + 1) per person, with weight 0.7 for the vector list and 0.3 for the full-text list:

CALL () {
  MATCH (p:Person)
  SEARCH p IN (VECTOR INDEX person_focus FOR $v LIMIT $k) SCORE AS score
  WITH p ORDER BY score DESC, p.name
  WITH collect(p) AS ps
  UNWIND range(0, size(ps) - 1) AS rank
  RETURN ps[rank] AS p, 0.7 AS weight, rank
  UNION ALL
  MATCH (p:Person)
  SEARCH p IN (FULLTEXT INDEX person_bio FOR $q LIMIT $k) SCORE AS score
  WITH p ORDER BY score DESC, p.name
  WITH collect(p) AS ps
  UNWIND range(0, size(ps) - 1) AS rank
  RETURN ps[rank] AS p, 0.3 AS weight, rank
}
WITH p, sum(weight / (60 + rank + 1)) AS rrf
RETURN p.name AS id, rrf
ORDER BY rrf DESC, id
LIMIT $k

| id      | rrf                  |
|---------|----------------------|
| "Grace" | 0.01631411951348493  |
| "Noor"  | 0.016208355367530406 |
| "Ada"   | 0.01111111111111111  |
3 rows

The view runs the two lists and the fused statement with the chosen k, up to the three people the graph holds, and writes out each fused score's arithmetic beside the statement's own:

The full-text list holds two people at most: Ada's bio holds neither docs nor tests. A person missing from a list gets no share from it, so Ada's score is her vector share alone.

COMBINE on the CLI. This setup step writes the same graph, vectors and indexes to a new store, search.rl:

relate --database ./search.rl "CREATE (ada:Person {name: 'Ada', role: 'engineer', focus: vector([0.9, 0.1, 0.2], 3, FLOAT32), bio: 'Writes the storage engine in Rust'}),
       (grace:Person {name: 'Grace', role: 'engineer', focus: vector([0.3, 0.9, 0.1], 3, FLOAT32), bio: 'Keeps the conformance tests green'}),
       (noor:Person {name: 'Noor', role: 'maintainer', focus: vector([0.2, 0.3, 0.9], 3, FLOAT32), bio: 'Reviews the docs and the tests'}),
       (relate:Project {name: 'relate', language: 'Rust'}),
       (tck:Project {name: 'opencypher-tck', language: 'Gherkin'}),
       (ada)-[:WORKS_ON {since: 2024}]->(relate),
       (grace)-[:WORKS_ON {since: 2023}]->(relate),
       (grace)-[:WORKS_ON {since: 2022}]->(tck),
       (noor)-[:MAINTAINS]->(relate),
       (ada)-[:KNOWS]->(grace);
CREATE VECTOR INDEX person_focus FOR (p:Person) ON (p.focus) WITH [p.role]
  OPTIONS {indexConfig: {'vector.dimensions': 3, 'vector.similarity_function': 'cosine'}};
CREATE FULLTEXT INDEX person_bio FOR (p:Person) ON EACH [p.bio]"

The fused ranking, read-only, with the preview opt-in in the command's environment:

RELATE_PREVIEW=hybrid-search relate --database ./search.rl --read-only --mode table "MATCH (p:Person) SEARCH p IN (COMBINE (VECTOR INDEX person_focus FOR [0.1, 0.9, 0.1] LIMIT 3 WEIGHT 0.7, FULLTEXT INDEX person_bio FOR 'docs tests' LIMIT 3 WEIGHT 0.3) USING WRRF WITH CONSTANT 60 LIMIT 3) SCORE AS score RETURN p.name AS name, score"

+---------+----------------------+
| name    | score                |
+---------+----------------------+
| "Grace" | 0.01631411951348493  |
| "Noor"  | 0.016208355367530406 |
| "Ada"   | 0.01111111111111111  |
+---------+----------------------+

Grace is first by vector and second by full-text: 0.7 / 61 + 0.3 / 62. Noor is second by vector and first by full-text: 0.7 / 62 + 0.3 / 61. Ada appears only in the vector list: 0.7 / 63. The scores are the weighted-fusion cell's, digit for digit.

See also

• Search by vector similarity: the task, step by step.
• Hybrid recall: reciprocal rank fusion written in plain Cypher, over 40 notes.
• Differences from Neo4j: the procedure forms an agent may reach for, and the clause to write instead.