Documentation for Cypher SEARCH clause #1459

Lojjs · 2026-01-26T12:58:55Z

Documentation for the new SEARCH clause which will be in preview in 2026.01.

This PR builds on top of #1454 and #1458

The new runtime operators for SEARCH will be documented in a separate PR.

Lojjs · 2026-01-26T13:00:43Z

modules/ROOT/pages/clauses/search.adoc

+.Error message
+[source, error]
+----
+Vector search embeddings referencing the search variable


While we still are in beta, we should align this error message and the docs terminology so we do not use
"query vector" and "binding variable" in one place and "embeddings" and "search variable" in the other to refer to the same concepts.

We already use "query vector" in the documentation of the old procedures, so I would like to stick with that, but I'm open for feedback on if "binding variable" or "search variable" is better.

I will leave this as is for now because this is the error you get in 2026.01. Then I will update it in both the error manual, code base and Cypher manual for 2026.02 with a separate PR

modules/ROOT/pages/clauses/search.adoc

Lojjs · 2026-01-27T12:37:36Z

modules/ROOT/pages/clauses/search.adoc

+
+The following graph is used for the examples below:
+
+// TODO insert an example svg graph


I would like to have an svg image here for the example data, similar to the ones we have on other clause pages. Not sure how I go about creating one though

@lidiazuin i think that's something for our image library - can you help?
@Lojjs do you have a draft maybe? (bloom image or anything)

thanks @lidiazuin

here's the svg, with embeddings as the last property and in italics

The preview of the svg looks good, thanks for the help. I get some permission error when I click on it though, so I am not able to download it. So could you upload it to the code base and link it where I have the TODO?

added it via dev (it won't show up in this PR because of that)
couldn't access your fork, but i think that is fine

I think you have some copy-pasted text in that line you want to update, not sure if it will be visible for users or not

…2828) The links will start working when neo4j/docs-cypher#1459 is merged. --------- Co-authored-by: Reneta Popova <[email protected]>

modules/ROOT/pages/clauses/search.adoc

gem-neo4j

Looks good! All my comments are nitpicky, so I will go ahead and approve :)

modules/ROOT/pages/clauses/search.adoc

modules/ROOT/pages/indexes/semantic-indexes/vector-indexes.adoc

mauvo · 2026-01-30T14:54:02Z

modules/ROOT/pages/clauses/index.adoc

 | Adds constraints to the patterns in a `MATCH` or `OPTIONAL MATCH` clause or filters the results of a `WITH` clause.

+m| xref::clauses/search.adoc[SEARCH]
+| A sub-clause following `MATCH` or `OPTIONAL MATCH`, filtering the results based on vector similarity.


Should we be more explicit that it's an ANN vector search? Filtering based on vector similarity is also something that can be done in a normal WHERE, or ORDER BY + LIMIT.

Good question, I have not really mentioned ANN in the rest of the docs but more explained in other words how it is working. I would like to get the docs out today or tomorrow so people can use them for the preview, so maybe we can revisit this for 2026.02 once we have a chance to see how it all looks together and when we get some feedback from users

rsill-neo4j

review part 1

modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc

rsill-neo4j · 2026-02-02T08:11:20Z

modules/ROOT/pages/clauses/search.adoc

+
+[[query-search]]
+= SEARCH
+


Suggested change

.Preview Feature

[IMPORTANT]

====

The *vector search feature is offered AS-IS* as described in your agreement with Neo4j and should only be used for internal development purposes.

When this feature becomes generally available, you will need to upgrade to the latest Neo4j version (which may require downtime) to use the feature for non-development purposes.

Vector search is *enabled by default*, both in Aura and self-managed Neo4j.

Use the internal setting `internal.dbms.vector_search=false` if you wish to disable it for self-managed Neo4j.

During the Preview period, if you have any feedback, comments, or encounter any issues, we welcome them in our link:https://github.com/neo4j/neo4j/issues[public GitHub repository].

We will address them to the best of our ability.

Please include the term *Vector search* in the title of your issue so we can identify it more easily. +

Customers with active contracts may contact Neo4j Support through the standard support channels.

Please note that any cases related to the Preview feature will be classified as Severity 4 by default, in accordance with the link:https://neo4j.com/terms/support-terms/[Support Terms].

====

i copied this from graph types and edited it. a few things:

is the "enabled by default" thing correct? (both aura/self-managed?)

is the setting correct?

is "vector search" as the title of issues the one we expect?

Enabled by default is correct in 2026.01, with the caveat that it is a Cypher 25 feature so if you are on Cypher 5, it is not available. Do you think we need to clarify this or is it implied because this is the Cypher 25 docs?

The setting is called internal.dbms.vector_single_stage_filtering_enabled but I would like to ask our PM @mauvo whether we want to mention it in the docs or not

We haven't discussed this but I think "Vector search" as a title issue makes sense yes

i think that's fine (@cypher 25)
small update to the suggestion
i'll leave this open until we know whether or not to include the setting

modules/ROOT/pages/clauses/search.adoc

rsill-neo4j

review part 2

👏 thanks @Lojjs for this high-quality draft :)

modules/ROOT/pages/clauses/search.adoc

modules/ROOT/pages/indexes/semantic-indexes/vector-indexes.adoc

…eo4j#2828) The links will start working when neo4j/docs-cypher#1459 is merged. --------- Co-authored-by: Reneta Popova <[email protected]>

…o4j PR.

Co-authored-by: Richard Sill <[email protected]>

…ring

modules/ROOT/pages/clauses/search.adoc

neo4j-docops-agent · 2026-02-04T14:53:38Z

This PR includes documentation updates
View the updated docs at https://neo4j-docs-cypher-1459.surge.sh

New pages:

SEARCH

Updated pages:

Lojjs · 2026-02-04T14:59:23Z

modules/ROOT/pages/clauses/search.adoc

 The following graph is used for the examples below:

-// TODO insert an example svg graph
+image::graph-search-clause.svg[Example graph with Person nodes connecting via knows relationships,width=700,role=popup]


@rsill-neo4j I think you want to update the text in the square brackets to something more descriptive of this specific graph

Lojjs commented Jan 26, 2026

View reviewed changes

Lojjs force-pushed the surf-114-documentation-for-single-stage-filtering branch from 186d89a to 143ecbf Compare January 27, 2026 12:30

Lojjs commented Jan 27, 2026

View reviewed changes

modules/ROOT/pages/clauses/search.adoc Outdated Show resolved Hide resolved

Lojjs force-pushed the surf-114-documentation-for-single-stage-filtering branch from 143ecbf to 8e188a8 Compare January 27, 2026 12:36

Lojjs commented Jan 27, 2026

View reviewed changes

Lojjs force-pushed the surf-114-documentation-for-single-stage-filtering branch from 8e188a8 to 9ae8c96 Compare January 27, 2026 12:43

Lojjs added 2026.01 team-cypher-surface Cypher 25 labels Jan 27, 2026

Lojjs marked this pull request as ready for review January 27, 2026 12:50

Lojjs mentioned this pull request Jan 27, 2026

Add note about SEARCH being preferred alternative to old procedures. neo4j/docs-operations#2828

Merged

JoelBergstrand assigned gem-neo4j Jan 29, 2026

Lojjs commented Jan 29, 2026

View reviewed changes

modules/ROOT/pages/clauses/search.adoc Outdated Show resolved Hide resolved

gem-neo4j approved these changes Jan 29, 2026

View reviewed changes

mauvo reviewed Jan 30, 2026

View reviewed changes

rsill-neo4j reviewed Feb 2, 2026

View reviewed changes

Lojjs added 3 commits February 4, 2026 12:58

Document new SEARCH clause.

8c45f3b

Fix smaller review comments and update error message to align with Ne…

5c74398

…o4j PR.

Change releaseYear property to releaseDate

0bcc723

Lojjs force-pushed the surf-114-documentation-for-single-stage-filtering branch from 92b3bf7 to 0bcc723 Compare February 4, 2026 11:58

Apply suggestions from code review

e791eeb

Co-authored-by: Richard Sill <[email protected]>

Lojjs force-pushed the surf-114-documentation-for-single-stage-filtering branch from fb304ed to e791eeb Compare February 4, 2026 13:03

Merge branch 'dev' into surf-114-documentation-for-single-stage-filte…

d9cb06c

…ring

rsill-neo4j reviewed Feb 4, 2026

View reviewed changes

modules/ROOT/pages/clauses/search.adoc Outdated Show resolved Hide resolved

Update modules/ROOT/pages/clauses/search.adoc

8445283

Lojjs commented Feb 4, 2026

View reviewed changes


		The following graph is used for the examples below:

		// TODO insert an example svg graph

+.Preview Feature
+[IMPORTANT]
+====
+The *vector search feature is offered AS-IS* as described in your agreement with Neo4j and should only be used for internal development purposes.
+When this feature becomes generally available, you will need to upgrade to the latest Neo4j version (which may require downtime) to use the feature for non-development purposes.
+Vector search is *enabled by default*, both in Aura and self-managed Neo4j.
+Use the internal setting `internal.dbms.vector_search=false` if you wish to disable it for self-managed Neo4j.
+During the Preview period, if you have any feedback, comments, or encounter any issues, we welcome them in our link:https://github.com/neo4j/neo4j/issues[public GitHub repository].
+We will address them to the best of our ability.
+Please include the term *Vector search* in the title of your issue so we can identify it more easily. +
+Customers with active contracts may contact Neo4j Support through the standard support channels.
+Please note that any cases related to the Preview feature will be classified as Severity 4 by default, in accordance with the link:https://neo4j.com/terms/support-terms/[Support Terms].
+====


		[[query-search]]
		= SEARCH

Documentation for Cypher SEARCH clause #1459

Are you sure you want to change the base?

Documentation for Cypher SEARCH clause #1459

Conversation

Lojjs commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Lojjs Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gem-neo4j left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rsill-neo4j left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rsill-neo4j Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rsill-neo4j left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Lojjs commented Jan 26, 2026 •

edited

Loading

Lojjs Jan 26, 2026 •

edited

Loading

rsill-neo4j Feb 2, 2026 •

edited

Loading

Lojjs Feb 4, 2026 •

edited

Loading