You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository contains the AsciiDoc and other sources to build the link:{docs-uri}/status-codes[Neo4j Status Codes].
6
6
7
-
7
+
[[local-build]]
8
8
== Installation
9
9
10
10
To build these docs locally you will need link:https://nodejs.org/en/download/package-manager/[Node & NPM^] installed.
@@ -16,7 +16,7 @@ To install the dependencies run:
16
16
npm install
17
17
----
18
18
19
-
19
+
[[live-preview]]
20
20
== Live Preview
21
21
22
22
To preview the docs, run:
@@ -30,42 +30,31 @@ This will build a set of HTML files in `build/site` and then serve them through
30
30
The start script will also listen for changes and automatically rebuild the files automatically.
31
31
You will still need to refresh the page to view the changes.
32
32
33
-
33
+
[[contributing]]
34
34
== Contributing
35
35
36
36
To make changes to this repository, please create a fork of this repo and a new branch to stage your changes.
37
-
Your branch should be prefixed with the version number, for example `4.3-new-examples`.
37
+
Your branch should be prefixed with the version number, for example, `dev-new-examples`.
38
38
39
39
When you are finished with your changes push the branch to your fork and create a Pull Request.
40
40
Please add at least one approver.
41
41
42
-
== Guidelines for writing Neo4j notifications
43
-
44
-
When you want to add a new Notification code, you update the `neo4j` repo and this repo `docs-status-codes` by adding the notification details and examples.
45
-
Each notification comprises the following components, some of which are documented only here in this repo.
42
+
[[guidelines]]
43
+
== Guidelines for writing errors and notifications
| Title|This query builds a cartesian product between disconnected patterns.
50
-
| SeverityLevel| INFORMATION
51
-
| Category| PERFORMANCE
52
-
(For all categories and severity levels, see https://github.com/neo4j/docs-status-codes/blob/dev/modules/ROOT/pages/notifications/index.adoc)
53
-
| Description |(Causes, consequences, a simple solution, or a reference to the Status Codes documentation)
54
-
| Example| (Status Codes documentation only)
55
-
| Suggestions for improvement| (Status Codes documentation only)
56
-
|===
57
-
58
-
The following are guidelines on how to write each of the notification components.
45
+
The new errors and notifications are written in the `neo4j` repo and then added to this repo `docs-status-codes` by adding the notification or error details and examples.
59
46
47
+
[[general-guidelines]]
60
48
=== General guidelines
61
49
62
-
* Regardless of the notification category, each notification should include all the components.
63
-
* Always use Present Simple tense (it refers to an action or event that happens regularly or to facts, general realities, and unchanging situations) and active voice (when the subject of the sentence is the one doing the action, see https://www.merriam-webster.com/words-at-play/active-vs-passive-voice-difference) if possible.
50
+
* Use sentence case (you capitalize the first letter, proper nouns, and names, just like you would in a normal sentence) and punctuation.
51
+
* Always use present tense and active voice (when the subject of the sentence is the one doing the action, see https://www.merriam-webster.com/words-at-play/active-vs-passive-voice-difference) if possible.
64
52
* Be specific and try to use only words that count.
65
-
* Avoid repeating content from other notification parts, such as title, description, code, etc.
66
-
* Avoid using verbs or verb derivatives, for example, “Using”, “Running”, “The use of”, “Adding”..
53
+
* Avoid repeating content from other parts, such as title, description, code, etc.
54
+
* Avoid using verbs or verb derivatives, for example, “Using”, “Running”, “The use of”, “Adding”.
55
+
* Do not use exclamation marks.
67
56
* Avoid blaming the user.
68
-
Focus the notification on the problem that could be fixed.
57
+
Focus the message on the problem that could be fixed.
69
58
+
70
59
For example, “Did not supply query with enough parameters.“ could be rewritten to “The query does not have enough parameters”.
71
60
+
@@ -75,88 +64,194 @@ It could be omitted as the title already says that it is an experimental feature
75
64
* Avoid the phrase “It is recommended to” when proposing a solution.
76
65
* Capitalize all Cypher keywords, i.e., `MATCH` rather than `match` or `Match`.
77
66
78
-
=== Code
67
+
[[error-notification-components]]
68
+
=== Error and notification components
79
69
80
-
All Neo4j codes follow the syntax `Neo.[Class].[Subclass].[Name]`.
81
-
The notification codes’ [Class] is `ClientNotification`.
82
-
Therefore, they all start with `Neo.ClientNotification`.
83
-
The [Subclass] is one of `Statement`, `Procedure`, `Schema`, `Database`, `Security`, or `Request`.
84
-
Code’s [Name] should be specific and explain what this code refers to.
70
+
Each error and notification comprises the following components, some of which are documented only here in this repo.
The following are guidelines on how to write each of the notification and error components.
91
120
92
-
=== Title
121
+
[[statuscode-syntax]]
122
+
==== StatusCode syntax
93
123
94
-
The title should be brief (one short sentence), scannable, and inform on the current situation and what code of the query triggered the notification (add it within backticks to show that it’s a code snippet).
124
+
All Neo4j status codes follow the syntax `Neo.[Class].[Subclass].[Name]`.
95
125
96
-
* Do not use exclamation marks.
97
-
* Use sentence case (you capitalize the first letter, proper nouns, and names, just like you would in a normal sentence) and punctuation.
98
-
* Avoid explaining:
99
-
** the consequences of the returned code.
100
-
** what causes the code to be returned.
101
-
** possible solutions.
126
+
[options="header",cols="h,1,2,3,3,2",]
127
+
|===
128
+
| StatusCode
129
+
| `Neo`
130
+
| `[Class]`
131
+
| `[Subclass]`
132
+
| `[Name]`
133
+
| Example
134
+
135
+
| Notification
136
+
| `Neo`
137
+
| `ClientNotification`
138
+
| One of `Statement`, `Procedure`, `Schema`, `Database`, `Security`, `Cluster`, or `Request`.
139
+
| Should be specific and explains what this code refers to, e.g., `ExhaustiveShortestPath`.
The provided pattern is unbounded, consider adding an upper limit to the number of node hops.
150
+
[[notification-titleerror-description]]
151
+
==== Notification title/error description
105
152
106
-
✅Example:
107
-
The pattern `<pattern>` is unbounded.
153
+
The notification title and the error description contain similar information.
154
+
Therefore, they follow the same guidelines.
155
+
Both should be brief (one short sentence), specific, and inform on the current situation and what code of the query triggered the notification/error (add it within backticks to show that it’s a code snippet).
156
+
Avoid explaining the cause, consequences, or solution.
157
+
The notification title and description will be replaced by a single field `message` in 6.0.
158
+
The error description in 5.x is used just as a fallback error message in some specific cases, and in 6.0, it will no longer be used.
159
+
See <<message, Message>>.
108
160
109
-
⛔Example:
110
-
This feature is deprecated and will be removed in future versions.
161
+
.Examples for notification title and error description
162
+
[options="header",cols="h,2,2",]
163
+
|===
164
+
| Example
165
+
| ⛔ Don't
166
+
| ✅ Do
111
167
112
-
✅Example:
113
-
(Deprecated) The repeated variable length relationship r is bound more than once.
168
+
| Notification title 1
169
+
| The provided pattern is unbounded, consider adding an upper limit to the number of node hops.
170
+
| The pattern `<pattern>` is unbounded.
114
171
115
-
⛔Example (contains a possible solution):
116
-
The provided label is not in the database.
172
+
| Notification title 2
173
+
| The provided label is not in the database.
174
+
| The label `Perso` does not exist.
175
+
|===
117
176
118
-
✅Example:
119
-
The label `Perso` does not exist.
177
+
[[notification-description]]
178
+
==== Notification description
120
179
180
+
The Notification description should contain the most important information for the user.
181
+
They should be brief, scannable, specific, and contain the following details (if applicable):
121
182
183
+
* Cause -- what triggered the code to be returned.
184
+
* Consequences -- why it might be a problem.
185
+
* A simple solution if possible.
122
186
123
-
=== Description
187
+
.Examples of notification descriptions
188
+
[options="header",cols="h,2,2",]
189
+
|===
190
+
| Example
191
+
| ⛔ Don't
192
+
| ✅ Do
124
193
125
-
This is the description of the returned code.
194
+
| Notification description 1
195
+
| Using shortest path with an unbounded pattern will likely result in long execution times.
196
+
It is recommended to use an upper limit to the number of node hops in your pattern.
197
+
| Shortest path with an unbounded pattern may result in long execution times.
198
+
Use an upper limit to the number of node hops in your pattern.
126
199
127
-
The description should contain the following:
200
+
| Notification description 2
201
+
| Using an already bound variable for a variable length relationship is deprecated and will be removed in a future version. (the repeated variable is: r)
202
+
| A variable length relationship that is bound more than once does not return any result.
128
203
129
-
* What caused the notification to be returned
130
-
* Why it might be a problem - what the consequences are
131
-
* If possible, a simple solution, otherwise, a reference to the docs using the sentence:
132
-
_See Status Codes documentation for suggestions for improvement._
204
+
| Notification description 3
205
+
| One of the labels in your query is not available in the database, make sure you didn’t misspell it or that the label is available when you run this statement in your application (the missing label name is: Perso)
206
+
| Non-existing labels yield no result. Verify that the label is spelled correctly.
207
+
|===
133
208
209
+
[[message]]
210
+
==== Message
134
211
135
-
⛔Example:
136
-
Using shortest path with an unbounded pattern will likely result in long execution times.
137
-
It is recommended to use an upper limit to the number of node hops in your pattern.
212
+
In 6.0, the notifications and errors will have only a message, which will be used instead of the notification title and description, and the error description and message.
138
213
139
-
✅Rewrite:
140
-
Shortest path with an unbounded pattern may result in long execution times.
141
-
Use an upper limit to the number of node hops in your pattern.
214
+
The message should follow the same guidelines as the notification description, namely:
215
+
216
+
The message should contain the most important information for the user.
217
+
It should be brief, scannable, specific, and contain the following details (if applicable):
142
218
143
-
⛔Example:
144
-
Using an already bound variable for a variable length relationship is deprecated and will be removed in a future version. (the repeated variable is: r)
219
+
* Problem -- what happened and what code of the query triggered the notification/error (add it within backticks to show that it’s a code snippet).
220
+
* Cause -- what triggered the code to be returned.
221
+
* A simple solution if possible.
145
222
146
-
✅Rewrite:
147
-
A variable length relationship that is bound more than once does not return any result. See Status Codes documentation for suggestions for improvement.
223
+
.Examples of error messages
224
+
[options="header",cols="h,2,2",]
225
+
|===
226
+
| Example
227
+
| ⛔ Don't
228
+
| ✅ Do
148
229
149
-
⛔Example:
150
-
One of the labels in your query is not available in the database, make sure you didn’t misspell it or that the label is available when you run this statement in your application (the missing label name is: Perso)
230
+
| Error message 1
231
+
| Failed to create the specified database '%s': The total limit of databases is already reached. To create more you need to either drop databases or change the limit via the config setting 'dbms.max_databases'
232
+
| Failed to create the database `$param1`. The limit of databases is reached. Either increase the limit using the config setting `$param2` or drop a database.
151
233
152
-
✅Rewrite:
153
-
Non-existing labels yield no result. Verify that the label is spelled correctly.
234
+
| Error message 2
235
+
| Database does not exist. Database name: '%s'
236
+
| `$param` database not found. Verify that the spelling is correct.
154
237
155
-
=== Example
238
+
| Error message 3
239
+
| The allocation of an extra %s would use more than the limit %s. Currently using %s. %s threshold reached
240
+
| Failed to allocate `$param1`. Currently using $param2`. Increase the memory pool limit using `$param3`.
241
+
|===
242
+
243
+
[[example]]
244
+
==== Example
245
+
246
+
[NOTE]
247
+
====
248
+
This component is currently documented only for notifications.
249
+
If you are updating an error, you can skip this section.
250
+
====
156
251
157
-
The examples and suggestions for improvement are written only in the Status Codes doc.
252
+
The examples and possible solutions are written only here in this repo, for the Status Codes doc.
158
253
159
-
Add one or more example queries to illustrate the possible scenarios when this notification code would be returned.
254
+
Add one or more example queries to illustrate the possible scenarios when this notification would be returned.
160
255
They should look similar to the following:
161
256
162
257
.<Add a caption that explains the example>
@@ -169,29 +264,64 @@ Here write the query.
169
264
----
170
265
171
266
Description of the returned code::
172
-
Same as in the `ne4j` repo.
267
+
Same as in the `neo4j` repo.
173
268
174
269
Suggestions for improvement::
175
270
176
271
Give a possible solution for the provided example query.
272
+
====
177
273
178
-
⛔Example:
274
+
For example:
275
+
276
+
[options="header",cols="2,2",]
277
+
|===
278
+
| ⛔ Don't
279
+
| ✅ Do
179
280
281
+
a| .Cartesian product
282
+
====
283
+
Query::
284
+
+
285
+
[source, cypher, role="noplay"]
286
+
----
287
+
MATCH (c:Child), (p:Parent) RETURN c, p
288
+
----
289
+
290
+
Description of the returned code::
291
+
If a part of a query contains multiple disconnected patterns,
292
+
this will build a cartesian product between all those parts.
293
+
This may produce a large amount of data and slow down query processing.
294
+
While occasionally intended, it may often be possible to reformulate the query that avoids the use of this cross product,
295
+
perhaps by adding a relationship between the different parts or by using `OPTIONAL MATCH` (identifier is: (`p`))
296
+
297
+
Suggestions for improvement::
180
298
In case a cartesian product is needed, nothing can be done to improve this query.
181
299
In many cases, however, you might not need a combination of all children and parents, and that is when this query could be improved.
182
300
If for example, you need the children and the children's parents, you can improve this query by rewriting it to the following:
183
-
301
+
+
184
302
[source, cypher, role="noplay"]
185
303
----
186
304
MATCH (c:Child)-[:ChildOf]->(p:Parent) RETURN c, p
187
305
----
306
+
====
307
+
a| .Cartesian product
308
+
====
309
+
Query::
310
+
+
311
+
[source, cypher, role="noplay"]
312
+
----
313
+
MATCH (c:Child), (p:Parent) RETURN c, p
314
+
----
188
315
316
+
Description of the returned code::
317
+
The disconnected patterns `$param` build a cartesian product. A cartesian product may produce a large amount of data and slow down query processing.
189
318
190
-
✅Rewrite:
191
-
319
+
Suggestions for improvement::
192
320
If you only need the children and the children's parents, and not all combinations between them, add `[:ChildOf]` between the `Child` and the `Parent` nodes:
193
321
194
322
[source, cypher, role="noplay"]
195
323
----
196
324
MATCH (c:Child)-[:ChildOf]->(p:Parent) RETURN c, p
0 commit comments