Skip to content

Commit 5f79778

Browse files
renetapopovarenetapopova
committed
Swamp the lagacy and the GQL code tab examples
1 parent b6f4902 commit 5f79778

File tree

8 files changed

+993
-917
lines changed

8 files changed

+993
-917
lines changed

‎modules/ROOT/content-nav.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
* xref:index.adoc[]
22
* xref:errors/index.adoc[]
3-
** xref:errors/all-errors.adoc[]
43
** xref:errors/gql-errors.adoc[]
4+
** xref:errors/all-errors.adoc[]
55
* xref:notifications/index.adoc[]
66
** xref:notifications/all-notifications.adoc[]
77
* xref:changelogs.adoc[]

‎modules/ROOT/pages/draft.adoc‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
In GQL, when the execution of a GQL-request fails, the execution outcome (in this case failed outcome) has no results but only a primary GQL-status object describing the exception condition (i.e., the error) that caused the failure and possibly a list of other additional GQL-status objects describing other conditions related to the same GQL-request.
2+
3+
A GQL-status object comprises:
4+
A mandatory GQLSTATUS code, which is a 5 character string identifying a condition (the first 2 characters identify the GQLSTATUS class code and the 3 other characters identify the GQLSTATUS subclass code)
5+
A mandatory status description, which is a user-facing message describing the GQLSTATUS
6+
An optional record with diagnostic information (such as the code of the operation executed, the current working directory, etc.)
7+
An optional nested GQL-status object for providing additional diagnostic information, such as a cause.
8+
In GQL, it is up to implementations to make several conditions available when a GQL-request is executed. However, if multiple conditions are made available they should be returned in separate GQL-status objects. In this case, there should be a primary GQL-status object and a list of additional GQL-status objects. GQL prescribes the below precedence rules to determine the primary GQL-status object:
9+
Every exception condition for transaction rollback has precedence over every other exception condition.
10+
Every exception condition has precedence over every completion condition.
11+
Note that GQL exception conditions are equivalent to Neo4j errors, and GQL completion conditions include Cypher notifications whose severity level is either warning or information (except those related to performance or variable shadowing, which are equivalent to GQL additional informational messages that can theoretically accompany both completion and exception condition). GQL completion conditions go beyond Cypher notifications. They include no data and successful completion.
12+
13+
14+
15+
in Cypher, if the execution of a request fails, a single GQL-status object describing a specific error is returned, i.e., the primary GQL-status object, which is also GQL-compliant. This is different from the success case, where multiple Cypher notifications can be returned, hence multiple GQL-status objects describing completion conditions and informational conditions.
16+
17+
Currently, a Neo4j error code can span several Neo4j exceptions and each exception can have several error messages. Each exception can be also linked to several Neo4j error codes. Some codes have no linked exceptions at all (See examples depicted in the table below). Hence, there is a many-to-many relationship between current error codes and exceptions. This is why many of the clients rely on the error message to identify a specific error.
18+
19+
The ultimate goal is to have a 1-1 mapping between a GQLSTATUS code and a specific error message so as to let the client rely on one unique and standardized code. The next section describes how to assign a single and unique GQLSTATUS code for each error to achieve this goal.
20+
21+
If a Neo4j error matches a standard-defined condition and subcondition, then the standard-defined GQLSTATUS code should be used for that error. For instance, (Neo.ClientError.Statement.ArithmeticError, ArithmeticException, “/by zero”) matches the “data exception” condition and “division by zero” subcondition in GQL (i.e., 22012 GQLSTATUS code).
22+
23+
error: data exception - string data, right truncation

‎modules/ROOT/pages/errors/all-errors.adoc‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,25 @@
1-
:description: The Neo4j error codes for Neo4j version {neo4j-version}.
1+
:description: The legacy error codes for Neo4j 5.
22

33

44
[[neo4j-errors]]
5-
= List of all server error codes
5+
= List of legacy server error codes
6+
7+
Error codes are Neo4j status codes returned by the server when the execution of a query fails.
8+
They always have the severity level `ERROR`.
9+
Errors are grouped based on the type of the error code:
10+
11+
Client errors::
12+
These errors are caused by the client and are usually related to the request itself.
13+
Client errors have the prefix `Neo.ClientError`.
14+
15+
Transient errors::
16+
These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc.
17+
The error can be temporary and could therefore succeed if retrying the request.
18+
Transient errors have the prefix Neo.`TransientError`.
19+
20+
Database errors::
21+
These errors are caused by the database and are usually related to the database state.
22+
Database errors have the prefix `Neo.DatabaseError`.
623

724
This page contains lists of all Neo4j errors, grouped by type.
825

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
:description: This section describes the GQLSTATUS errors that Neo4j can return, grouped by category, and an example of when they can occur.
22

33
[[neo4j-gqlstatus-errors]]
4-
= List of all GQLSTATUS server error codes
4+
= List of GQLSTATUS server error codes
55

66
//The following page provides an overview of all server errors in Neo4j, along with some scenarios and their possible solutions.
77
The following page provides an overview of all GQLSTATUS server error codes in Neo4j.

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

Lines changed: 176 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,180 @@
1-
:description: The Neo4j error codes for Neo4j version.
1+
:description: This page describes the structure of the error objects, the error codes, and how to interpret them.
22
[[neo4j-errors]]
33
= Server errors
44

5-
// [role=label--version-5.25]
6-
// [[gqlstatus-error-object]]
7-
// == GQL-status error object
8-
9-
// [[gqlstatus-standard-defined-codes]]
10-
// === Standard-defined GQLSTATUS codes
11-
12-
// .Standard-defined GQLSTATUS error codes
13-
// [options="header", cols="<1s,<4"]
14-
// [%collapsible]
15-
// |===
16-
// |GQLSTATUS code | StatusDescription
17-
// | 08000 | error: connection exception
18-
// | 08007 | error: connection exception - transaction resolution unknown
19-
// | 22000 | error: data exception
20-
// | 22001 | error: data exception - string data, right truncation
21-
// | 22003 | error: data exception - numeric value out of range. The numeric value `$value` is outside the required range.
22-
// | 22004 | error: data exception - null value not allowed
23-
// | 22007 | error: data exception - invalid date, time, or datetime format
24-
// | 22008 | error: data exception - datetime field overflow
25-
// | 22011 | error: data exception - substring error
26-
// | 22012 | error: data exception - division by zero
27-
// | 22015 | error: data exception - interval field overflow
28-
// | 22018 | error: data exception - invalid character value for cast. The character value `$value` is an invalid argument for the specified cast.
29-
// | 2201E | error: data exception - invalid argument for natural logarithm. The value `$value` is an invalid argument for the specified natural logarithm.
30-
// | 2201F | error: data exception - invalid argument for power function. The value `$value` is an invalid argument for the specified power function.
31-
// | 22027 | error: data exception - trim error
32-
// | 2202F | error: data exception - array data, right truncation
33-
// | 22G02 | error: data exception - negative limit value
34-
// | 22G03 | error: data exception - invalid value type
35-
// | 22G04 | error: data exception - values not comparable
36-
// | 22G05 | error: data exception - invalid date, time, or datetime function field name
37-
// | 22G06 | error: data exception - invalid datetime function value
38-
// | 22G07 | error: data exception - invalid duration function field name
39-
// | 22G0B | error: data exception - list data, right truncation
40-
// | 22G0C | error: data exception - list element error
41-
// | 22G0F | error: data exception - invalid number of paths or groups
42-
// | 22G0H | error: data exception - invalid duration format. The duration format `$format` is invalid.
43-
// | 22G0M | error: data exception - multiple assignments to a graph element property
44-
// | 22G0N | error: data exception - number of node labels below supported minimum
45-
// | 22G0P | error: data exception - number of node labels exceeds supported maximum
46-
// | 22G0Q | error: data exception - number of edge labels below supported minimum
47-
// | 22G0R | error: data exception - number of edge labels exceeds supported maximum
48-
// | 22G0S | error: data exception - number of node properties exceeds supported maximum
49-
// | 22G0T | error: data exception - number of edge properties exceeds supported maximum
50-
// | 22G0U | error: data exception - record fields do not match
51-
// | 22G0V | error: data exception - reference value, invalid base type
52-
// | 22G0W | error: data exception - reference value, invalid constrained type
53-
// | 22G0X | error: data exception - record data, field unassignable
54-
// | 22G0Y | error: data exception - record data, field missing
55-
// | 22G0Z | error: data exception - malformed path
56-
// | 22G10 | error: data exception - path data, right truncation
57-
// | 22G11 | error: data exception - reference value, referent deleted
58-
// | 22G13 | error: data exception - invalid group variable value
59-
// | 22G14 | error: data exception - incompatible temporal instant unit groups
60-
// | 25000 | error: invalid transaction state
61-
// | 25G01 | error: invalid transaction state - active GQL-transaction
62-
// | 25G02 | error: invalid transaction state - catalog and data statement mixing not supported
63-
// | 25G03 | error: invalid transaction state - read-only GQL-transaction
64-
// | 25G04 | error: invalid transaction state - accessing multiple graphs not supported
65-
// | 2D000 | error: invalid transaction termination
66-
// | 40000 | error: transaction rollback
67-
// | 40003 | error: transaction rollback - statement completion unknown
68-
// | 42000 | error: syntax error or access rule violation
69-
// | 42001 | error: syntax error or access rule violation - invalid syntax
70-
// | 42002 | error: syntax error or access rule violation - invalid reference
71-
// | 42004 | error: syntax error or access rule violation - use of visually confusable identifiers
72-
// | 42006 | error: syntax error or access rule violation - number of edge labels below supported minimum
73-
// | 42007 | error: syntax error or access rule violation - number of edge labels exceeds supported maximum
74-
// | 42008 | error: syntax error or access rule violation - number of edge properties exceeds supported maximum
75-
// | 42009 | error: syntax error or access rule violation - number of node labels below supported minimum
76-
// | 42010 | error: syntax error or access rule violation - number of node labels exceeds supported maximum
77-
// | 42011 | error: syntax error or access rule violation - number of node properties exceeds supported maximum
78-
// | 42012 | error: syntax error or access rule violation - number of node type key labels below supported minimum
79-
// | 42013 | error: syntax error or access rule violation - number of node type key labels exceeds supported maximum
80-
// | 42014 | error: syntax error or access rule violation - number of edge type key labels below supported minimum
81-
// | 42015 | error: syntax error or access rule violation - number of edge type key labels exceeds supported maximum
82-
// | G1000 | error: dependent object error
83-
// | G1001 | error: dependent object error - edges still exist
84-
// | G1002 | error: dependent object error - endpoint node is deleted
85-
// | G1003 | error: dependent object error - endpoint node not in current working graph
86-
// | G2000 | error: graph type violation
87-
// |===
88-
89-
// [[gqlstatus-neo4j-defined-codes]]
90-
// === Neo4j-defined GQLSTATUS error codes
5+
A server error is returned by the Neo4j DBMS to indicate that the outcome of a Cypher query or command execution is not successful.
6+
The driver receives these errors and sends them to the client, which displays them to the user.
917

8+
Starting from version 5.25, Neo4j has a new GqlStatusObject API in addition to the existing HasStatus API.
9+
The GqlStatusObject API provides information about the status of a Cypher query or command execution in compliance with the GQL standard.
10+
11+
This page describes both the Neo4j error and the GQL-status object frameworks, how they are structured, the objects they provide for errors, and how to interpret them.
12+
//It also explains the server error grouping and filtering, the error internals, and the server-driver compatibility for both the HasStatus and GqlStatusObject APIs.
13+
14+
15+
[role=label--version-5.23]
16+
[[gqlstatus-error-object]]
17+
== GQL-status error object
18+
19+
In the GQL-status object framework, errors are an implementation-defined subset of the GQL-status objects that cover exceptions.
20+
21+
In GQL, the execution of a query from user to server always has an outcome, called the _execution outcome_.
22+
The execution outcome is a list of GQL-status objects, ordered by the following precedence, where the first object in the list is the primary GQL-status object:
23+
24+
. Every exception condition for transaction rollback has precedence over every other exception condition.
25+
. Every exception condition has precedence over every completion condition.
26+
27+
The GQL-status object also includes the Neo4j-specific information, such as the severity level and the classification of the error.
28+
29+
Each GQL-status object consists of the following fields:
30+
31+
.GQLSTATUS error object
32+
[cols="<1s,<4"]
33+
|===
34+
|GQLSTATUS code
35+
a| A 5-character string that is the concatenation of a 2-character class code followed by a 3-character subclass code.
36+
|StatusDescription
37+
a| A human-readable description of the GQLSTATUS, which consists of a condition, a subcondition, and a description.
38+
The condition and subcondition are textual representations of the class and subclass codes, respectively.
39+
| DiagnosticRecord
40+
a| Extra information about the status, given as key-value pairs, both on the server and driver side.
41+
To retrieve the full diagnostic record, you can use the `diagnosticRecord()` method on both the server and driver sides.
42+
Additional helper methods are exposed for some useful fields.
43+
[cols="<1s,<4"]
44+
!===
45+
! Field ! Description
46+
! `OPERATION` ! The operation that the error is related to. Always defaults to empty.
47+
! `OPERATION_CODE` ! The operation code that the error is related to. Always defaults to `0`.
48+
! `CURRENT_SCHEMA` ! The current schema that the error is related to. Always defaults to `/`.
49+
! `_severity` a! The Neo4j severity level of the error, which is always `ERROR`.
50+
!`_classification` ! The Neo4j category of the error, which can be `CLIENT_ERROR`, `TRANSIENT_ERROR`, or `DATABASE_ERROR`.
51+
! `_position` ! The position, given by row and column, where the error is relevant in the query text.
52+
//! `_status_parameters`! A map that contains all variable parts of the status description.
53+
!===
54+
|===
55+
56+
A GQL-status error object can also contain an optional nested GQL-status object for providing additional diagnostic information, such as a cause, which is a GQL-status object wrapped in another GQL-status object.
57+
58+
[[gqlstatus-neo4j-defined-codes]]
59+
== Classes of GQLSTATUS error codes
60+
61+
The Neo4j-defined GQLSTATUS codes are divided into classes and subclasses, where the class code is a 2-character string (one of `00`, `01`, or `03`) and the subclass code is a 3-character string.
62+
The class code indicates the general condition of the status (such as successful completion, warning, or information), and the subclass code provides more detailed information about the condition, such as classification and messages.
63+
64+
The following table lists the Neo4j-defined groups of GQLSTATUS codes and their meanings:
65+
66+
.GQLSTATUS groups of codes as defined by Neo4j
67+
[frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"]
68+
|===
69+
|GQLSTATUS code
70+
|*Description*
71+
72+
| 01N0[y]
73+
| Deprecation warnings
74+
75+
| 01N3[y]
76+
| Hint warnings
77+
78+
| 01N4[y]
79+
| Unsupported warnings
80+
81+
| 01N5[y]
82+
| Unrecognized warnings
83+
84+
| 01N6[y]
85+
| Generic warnings
86+
87+
| 01N7[y]
88+
| Security warnings
89+
90+
| 03N9[y]
91+
| Performance information
92+
93+
| 03N6[y]
94+
| Generic information
95+
96+
| 00N5[y]
97+
| Unrecognized information under successful completion
98+
99+
| 00N6[y]
100+
| Generic information under successful completion
101+
102+
| 00N7[y]
103+
| Security information under successful completion
104+
105+
| 00N8[y]
106+
| Topology information under successful completion
107+
108+
|===
109+
110+
[[neo4j-error-object]]
111+
== Neo4j error object
112+
113+
The Neo4j error object contains diagnostic information representing the *unsuccessful* outcome of a Cypher query or command execution, including severity, status code, category, description, message, and position in the query text where the error is relevant.
114+
Depending on the application, some of the fields from the error object might not be visible.
115+
116+
The error object consists of the following fields:
117+
118+
.Neo4j error object
119+
[cols="<1s,<4"]
120+
|===
121+
|Neo4j code
122+
a|The Neo4j status code in the form of `Neo.[Type].[SubType].[Name]`.
123+
|Description
124+
a|The description of the specific error.
125+
|Message
126+
a|The error message.
127+
|Severity level
128+
a|`ERROR`
129+
|Category
130+
a|The category of the error.
131+
Available categories are `CLIENT_ERROR`, `TRANSIENT_ERROR`, and `DATABASE_ERROR`.
132+
|Position
133+
a|The position, given by row and column, where the error is relevant in the query text.
134+
|===
135+
136+
[[error-grouping-and-filtering]]
137+
== Server error classification
138+
139+
The fact that a Neo4j status code is returned by the server does not always mean there is a fatal error.
140+
Neo4j status codes can also indicate transient problems that may go away if you retry the request.
141+
The status code classification determines the effect on the transaction.
142+
143+
.Neo4j status code types
144+
[options="header", cols="<1m,<2,<1"]
145+
|===
146+
147+
| Type
148+
| Description
149+
| Effect on the transaction
150+
151+
| xref:errors/all-errors.adoc#_client_errors[ClientError]
152+
| The client sent a bad request - changing the request might yield a successful outcome.
153+
| Rollback
154+
155+
| xref:errors/all-errors#_transient_errors[TransientError]
156+
| The database cannot service the request right now, retrying later might yield a successful outcome.
157+
| Rollback
158+
159+
| xref:errors/all-errors#_database_error[DatabaseError]
160+
| The database failed to service the request.
161+
| Rollback
162+
163+
|===
164+
165+
[[error-internals]]
166+
== Error internals
167+
168+
The server and driver communicate with each other through the Bolt protocol.
169+
During the handshake process, they agree on using the newest possible Bolt protocol version that both the server and the driver support.
170+
For more information on the Bolt versions supported by different server versions, see the link:https://neo4j.com/docs/bolt/current/bolt-compatibility[Bolt Protocol documentation].
171+
172+
Neo4j supports server errors in the form of Java exceptions.
173+
Most of these implement the `HasStatus` interface, which means they have a Neo4j status code in addition to the exception message.
174+
175+
On the server side, an exception contains normal Java constructors and methods like `getMessage()`, `getCause()`, etc., and additionally the `status()` method from the `HasStatus` API, which returns the Neo4j status code.
176+
These exceptions are then sent to the driver as failure Bolt message metadata.
177+
178+
179+
[[server-driver-compatibility]]
180+
== Server-driver version compatibility

0 commit comments

Comments
 (0)