Skip to content

Commit cd6ab77

Browse files
Lojjsrenetapopovaarnefischereit
authored
Document new error codes for vector search filtering. (#434)
Co-authored-by: Reneta Popova <reneta.popova@neo4j.com> Co-authored-by: Arne Fischereit <79841228+arnefischereit@users.noreply.github.com>
1 parent 6eacd9b commit cd6ab77

File tree

7 files changed

+319
-0
lines changed

7 files changed

+319
-0
lines changed

‎modules/ROOT/content-nav.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,8 +178,10 @@
178178
**** xref:errors/gql-errors/22NCD.adoc[]
179179
**** xref:errors/gql-errors/22NCE.adoc[]
180180
**** xref:errors/gql-errors/22NCF.adoc[]
181+
**** xref:errors/gql-errors/22NCG.adoc[]
181182
**** xref:errors/gql-errors/22ND1.adoc[]
182183
**** xref:errors/gql-errors/22ND2.adoc[]
184+
**** xref:errors/gql-errors/22ND3.adoc[]
183185
*** xref:errors/gql-errors/index.adoc#invalid-transaction-state[Invalid transaction state]
184186
**** xref:errors/gql-errors/25G02.adoc[]
185187
**** xref:errors/gql-errors/25N01.adoc[]
@@ -293,6 +295,9 @@
293295
**** xref:errors/gql-errors/42I71.adoc[]
294296
**** xref:errors/gql-errors/42I72.adoc[]
295297
**** xref:errors/gql-errors/42I76.adoc[]
298+
**** xref:errors/gql-errors/42I73.adoc[]
299+
**** xref:errors/gql-errors/42I74.adoc[]
300+
**** xref:errors/gql-errors/42I75.adoc[]
296301
**** xref:errors/gql-errors/42N00.adoc[]
297302
**** xref:errors/gql-errors/42N01.adoc[]
298303
**** xref:errors/gql-errors/42N02.adoc[]

‎modules/ROOT/pages/errors/gql-errors/22NCG.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
= 22NCG
2+
3+
== Status description
4+
error: data exception - wrong index type. Expected the index `{ <<idx>> }` to be a `{ <<idxType>>1 }` index but was a `{ <<idxType>>2 }` index.
5+
6+
== Example scenario
7+
For example, assuming that you have a range index called `rangeIdx`, when trying to use it in a `SEARCH` clause:
8+
9+
[source,cypher]
10+
----
11+
CYPHER 25
12+
MATCH (movie:Movie)
13+
SEARCH movie IN (
14+
VECTOR INDEX rangeIdx
15+
FOR [1, 2, 3]
16+
LIMIT 5
17+
)
18+
RETURN movie.title AS title
19+
----
20+
21+
You will receive an error with GQLSTATUS 22NCG and status description:
22+
23+
[source]
24+
----
25+
error: data exception - wrong index type. Expected the index `rangeIdx` to be a vector index but was a range index.
26+
----
27+
28+
ifndef::backend-pdf[]
29+
[discrete.glossary]
30+
== Glossary
31+
32+
include::partial$glossary.adoc[]
33+
endif::[]

‎modules/ROOT/pages/errors/gql-errors/22ND3.adoc‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
= 22ND3
2+
3+
== Status description
4+
error: data exception - wrong property for vector search with filters. The property `{ <<propKey>> }` is not an additional property for vector search with filters on the vector index `{ <<idx>> }` .
5+
6+
== Example scenario
7+
For example, assuming that you have a vector index created by the following command:
8+
9+
[source,cypher]
10+
----
11+
CYPHER 25
12+
CREATE VECTOR INDEX moviePlots
13+
FOR (m:Movie) ON m.embedding
14+
WITH [m.rating]
15+
----
16+
17+
When using a property key other than `rating` in the `WHERE` clause property predicate in a `SEARCH` clause:
18+
19+
[source,cypher]
20+
----
21+
CYPHER 25
22+
MATCH (movie:Movie)
23+
SEARCH movie IN (
24+
VECTOR INDEX moviePlots
25+
FOR [1, 2, 3]
26+
WHERE movie.votes > 1000
27+
LIMIT 5
28+
)
29+
RETURN movie.title AS title
30+
----
31+
32+
You will receive an error with GQLSTATUS 22ND3 and status description:
33+
34+
[source]
35+
----
36+
error: data exception - wrong property for vector search with filters. The property `votes` is not an additional property for vector search with filters on the vector index 'moviePlots'.
37+
----
38+
39+
== Possible solution
40+
41+
If you want to use the property `votes` for vector search with filters, it must be added as an additional property to the vector index.
42+
For example:
43+
44+
. Drop the index you want to add the property to:
45+
+
46+
[source,cypher]
47+
----
48+
DROP INDEX moviePlots
49+
----
50+
51+
. Recreate the index by adding the new property to the index:
52+
+
53+
[source,cypher]
54+
----
55+
CYPHER 25
56+
CREATE VECTOR INDEX moviePlots
57+
FOR (m:Movie) ON m.embedding
58+
WITH [m.rating, m.votes]
59+
----
60+
61+
ifndef::backend-pdf[]
62+
[discrete.glossary]
63+
== Glossary
64+
65+
include::partial$glossary.adoc[]
66+
endif::[]

‎modules/ROOT/pages/errors/gql-errors/42I73.adoc‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
= 42I73
2+
3+
== Status description
4+
error: syntax error or access rule violation - invalid predicate for vector search with filters. The vector search filter predicate `{ <<expr>> }` must consist of one or more property predicates joined by `AND`, and the combined property predicates for each property must specify either an exact value (e.g. `x.prop = 1`), a half-bounded range (e.g. `x.prop >= 1`), or a bounded range (e.g. `x.prop > 1 AND x.prop < 100`).
5+
6+
== Example scenarios
7+
For example, assuming that you have a vector index created by the following command:
8+
9+
[source,cypher]
10+
----
11+
CYPHER 25
12+
CREATE VECTOR INDEX moviePlots
13+
FOR (m:Movie) ON m.embedding
14+
WITH [m.rating]
15+
----
16+
17+
18+
.Using `NOT` inside the `WHERE` subclause predicate in a `SEARCH` clause
19+
=====
20+
When trying to use `NOT` inside the `WHERE` subclause predicate in a `SEARCH` clause:
21+
22+
[source,cypher]
23+
----
24+
CYPHER 25
25+
MATCH (movie:Movie)
26+
SEARCH movie IN (
27+
VECTOR INDEX moviePlots
28+
FOR [1, 2, 3]
29+
WHERE NOT movie.rating = 8
30+
LIMIT 5
31+
)
32+
RETURN movie.title AS title, movie.rating AS rating
33+
----
34+
35+
You will receive an error with GQLSTATUS xref:errors/gql-errors/42001.adoc[42001] with a cause with GQLSTATUS 42I73 and status description:
36+
37+
[source]
38+
----
39+
error: syntax error or access rule violation - invalid predicate for vector search with filters. The vector search filter predicate `NOT movie.rating = 8` must consist of one or more property predicates joined by AND, and the combined property predicates for each property must specify either an exact value (e.g. `x.prop = 1`), a half-bounded range (e.g. `x.prop >= 1`), or a bounded range (e.g. `x.prop > 1 AND x.prop < 100`).
40+
----
41+
=====
42+
43+
.Using multiple half-bounded ranges on the same property inside the `WHERE` subclause predicate in a `SEARCH` clause
44+
=====
45+
When trying to use multiple half-bounded ranges on the same property inside the `WHERE` subclause predicate in a `SEARCH` clause:
46+
47+
[source,cypher]
48+
----
49+
CYPHER 25
50+
MATCH (movie:Movie)
51+
SEARCH movie IN (
52+
VECTOR INDEX moviePlots
53+
FOR [1, 2, 3]
54+
WHERE movie.rating > 6 AND movie.rating > 8
55+
LIMIT 5
56+
)
57+
RETURN movie.title AS title, movie.rating AS rating
58+
----
59+
60+
You will receive an error with GQLSTATUS xref:errors/gql-errors/42001.adoc[42001] with a cause with GQLSTATUS 42I73 and status description:
61+
62+
[source]
63+
----
64+
error: syntax error or access rule violation - invalid predicate for vector search with filters. The vector search filter predicate `movie.rating > 6 AND movie.rating > 8` must consist of one or more property predicates joined by AND, and the combined property predicates for each property must specify either an exact value (e.g. `x.prop = 1`), a half-bounded range (e.g. `x.prop >= 1`), or a bounded range (e.g. `x.prop > 1 AND x.prop < 100`).
65+
----
66+
=====
67+
68+
== Possible solution
69+
You can rewrite the predicates to comply with the vector search filter rules.
70+
For example, the predicate `NOT movie.rating < 7` can be rewritten to `movie.rating >= 7`, while the predicate `movie.rating > 6 AND movie.rating > 8` can be rewritten to `movie.rating > 8`.
71+
However, it is not always possible to rewrite the predicates.
72+
For the complete list of limitations, see link:https://neo4j.com/docs/cypher-manual/current/clauses/search/#limitations[Cypher Manual -> Limitations of the SEARCH clause].
73+
ifndef::backend-pdf[]
74+
[discrete.glossary]
75+
== Glossary
76+
77+
include::partial$glossary.adoc[]
78+
endif::[]

‎modules/ROOT/pages/errors/gql-errors/42I74.adoc‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
= 42I74
2+
3+
== Status description
4+
error: syntax error or access rule violation - wrong variable for vector search with filters. The variable `{ <<variable>>1 }` in a vector search filter property predicate must be the same as the search clause binding variable `{ <<variable>>2 }`.
5+
6+
== Example scenario
7+
For example, assuming that you have a vector index created by the following command:
8+
9+
[source,cypher]
10+
----
11+
CYPHER 25
12+
CREATE VECTOR INDEX moviePlots
13+
FOR (m:Movie) ON m.embedding
14+
WITH [m.rating]
15+
----
16+
17+
When trying to use a variable other than `movie` inside the `WHERE` subclause predicate in a `SEARCH` clause in the following query:
18+
19+
[source,cypher]
20+
----
21+
CYPHER 25
22+
MATCH (m:Movie {title:'Matrix, The'})
23+
MATCH (movie:Movie)
24+
SEARCH movie IN (
25+
VECTOR INDEX moviePlots
26+
FOR m.embedding
27+
WHERE m.rating >= 8
28+
LIMIT 5
29+
)
30+
RETURN movie.title AS title, movie.rating AS rating
31+
----
32+
33+
You will receive an error with GQLSTATUS xref:errors/gql-errors/42001.adoc[42001] with a cause with GQLSTATUS 42I74 and status description:
34+
35+
[source]
36+
----
37+
error: syntax error or access rule violation - wrong variable for vector search with filters. The variable `m` in a vector search filter property predicate must be the same as the search clause binding variable `movie`.
38+
----
39+
40+
ifndef::backend-pdf[]
41+
[discrete.glossary]
42+
== Glossary
43+
44+
include::partial$glossary.adoc[]
45+
endif::[]

‎modules/ROOT/pages/errors/gql-errors/42I75.adoc‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
= 42I75
2+
3+
== Status description
4+
error: syntax error or access rule violation - self-referencing in vector search. The expression `{ <<expr>> }` in the search clause may not depend on the search clause binding variable `{ <<variable>> }`.
5+
6+
== Example scenarios
7+
For example, assuming that you have a vector index created by the following command:
8+
9+
[source,cypher]
10+
----
11+
CYPHER 25
12+
CREATE VECTOR INDEX moviePlots
13+
FOR (m:Movie) ON m.embedding
14+
WITH [m.rating]
15+
----
16+
17+
.Using the search binding variable in the `FOR` subclause of a vector search
18+
=====
19+
When trying to use the search binding variable `movie` in the `FOR` subclause in the following query:
20+
21+
[source,cypher]
22+
----
23+
CYPHER 25
24+
MATCH (movie:Movie)
25+
SEARCH movie IN (
26+
VECTOR INDEX moviePlots
27+
FOR movie.embedding
28+
LIMIT 5
29+
)
30+
RETURN movie.title AS title, movie.rating AS rating
31+
----
32+
33+
You will receive an error with GQLSTATUS xref:errors/gql-errors/42001.adoc[42001] with a cause with GQLSTATUS 42I75 and status description:
34+
35+
[source]
36+
----
37+
error: syntax error or access rule violation - self-referencing in vector search. The expression `movie.embedding` in the search clause may not depend on the search clause binding variable `movie`.
38+
----
39+
=====
40+
41+
.Using the search binding variable in the `WHERE` subclause of a `SEARCH` clause
42+
=====
43+
When trying to use the search binding variable `movie` in both the left-hand and right-hand side of the predicate in the `WHERE` subclause in the following query:
44+
45+
[source,cypher]
46+
----
47+
CYPHER 25
48+
MATCH (m:Movie {title:'Matrix, The'})
49+
MATCH (movie:Movie)
50+
SEARCH movie IN (
51+
VECTOR INDEX moviePlots
52+
FOR m.embedding
53+
WHERE movie.rating = movie.year
54+
LIMIT 5
55+
)
56+
RETURN movie.title AS title, movie.rating AS rating
57+
----
58+
59+
You will receive an error with GQLSTATUS xref:errors/gql-errors/42001.adoc[42001] with a cause with GQLSTATUS 42I75 and status description:
60+
61+
[source]
62+
----
63+
error: syntax error or access rule violation - self-referencing in vector search. The expression `movie.year` in the search clause may not depend on the search clause binding variable `movie`.
64+
----
65+
=====
66+
67+
ifndef::backend-pdf[]
68+
[discrete.glossary]
69+
== Glossary
70+
71+
include::partial$glossary.adoc[]
72+
endif::[]

‎modules/ROOT/pages/errors/gql-errors/index.adoc‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -718,6 +718,10 @@ Status description:: error: data exception - node element type in use. The node
718718

719719
Status description:: error: data exception - graph type constraint not supported. Graph type constraint definitions are not supported in the `{ <<graphTypeOperation>> }` operation.
720720

721+
=== xref:errors/gql-errors/22NCG.adoc[22NCG]
722+
723+
Status description:: error: data exception - wrong index type. Expected the index `{ <<idx>> }` to be a `{ <<idxType>>1 }` index but was a `{ <<idxType>>2 }` index.
724+
721725
=== xref:errors/gql-errors/22ND1.adoc[22ND1]
722726

723727
Status description:: error: data exception - operation not allowed for roles that are granted to an `AUTH RULE`. Invalid input: `'{ <<query>> }'` is not allowed for roles that are granted to an `AUTH RULE`.
@@ -726,6 +730,10 @@ Status description:: error: data exception - operation not allowed for roles tha
726730

727731
Status description:: error: data exception - operation not allowed for roles with `DENY` privileges. Invalid input: `'{ <<query>> }'` is not allowed for roles with `DENY` privileges.
728732

733+
=== xref:errors/gql-errors/22ND3.adoc[22ND3]
734+
735+
Status description:: error: data exception - wrong property for vector search with filters. The property `{ <<propKey>> }` is not an additional property for vector search with filters on the vector index `{ <<idx>> }` .
736+
729737

730738
[[invalid-transaction-state]]
731739
== Invalid transaction state
@@ -1183,6 +1191,18 @@ Status description:: error: syntax error or access rule violation - search claus
11831191

11841192
Status description:: error: syntax error or access rule violation - search clause with too complex pattern. In order to have a search clause, a `MATCH` statement can only have a single node or relationship pattern and no selectors.
11851193

1194+
=== xref:errors/gql-errors/42I73.adoc[42I73]
1195+
1196+
Status description:: error: syntax error or access rule violation - invalid predicate for vector search with filters. The vector search filter predicate `{ <<expr>> }` must consist of one or more property predicates joined by `AND`, and the combined property predicates for each property must specify either an exact value (e.g. `x.prop = 1`), a half-bounded range (e.g. `x.prop >= 1`), or a bounded range (e.g. `x.prop > 1 AND x.prop < 100`).
1197+
1198+
=== xref:errors/gql-errors/42I74.adoc[42I74]
1199+
1200+
Status description:: error: syntax error or access rule violation - wrong variable for vector search with filters. The variable `{ <<variable>>1 }` in a vector search filter property predicate must be the same as the search clause binding variable `{ <<variable>>2 }`.
1201+
1202+
=== xref:errors/gql-errors/42I75.adoc[42I75]
1203+
1204+
Status description:: error: syntax error or access rule violation - self-referencing in vector search. The expression `{ <<expr>> }` in the search clause may not depend on the search clause binding variable `{ <<variable>> }`.
1205+
11861206
=== xref:errors/gql-errors/42I76.adoc[42I76]
11871207

11881208
Status description:: error: syntax error or access rule violation - index or constraint value too long. The provided index or constraint `{ <<item>> }` `{ <<input>> }` (`{ <<bytes>>1 }` bytes) exceeded limit of `{ <<bytes>>2 }` bytes.

0 commit comments

Comments
 (0)