1use serde_json::{Map, Value};
23
24#[derive(Clone, Copy, Debug, PartialEq, Eq)]
26pub enum NotificationSeverity {
27 Information,
29 Warning,
31}
32
33impl NotificationSeverity {
34 pub fn as_str(self) -> &'static str {
36 match self {
37 NotificationSeverity::Information => "INFORMATION",
38 NotificationSeverity::Warning => "WARNING",
39 }
40 }
41}
42
43impl std::fmt::Display for NotificationSeverity {
44 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
45 f.write_str(self.as_str())
46 }
47}
48
49#[derive(Clone, Copy, Debug, PartialEq, Eq)]
51pub enum NotificationCategory {
52 Performance,
54 Unrecognized,
56 Deprecation,
58 Schema,
60 Hint,
62}
63
64impl NotificationCategory {
65 pub fn as_str(self) -> &'static str {
67 match self {
68 NotificationCategory::Performance => "PERFORMANCE",
69 NotificationCategory::Unrecognized => "UNRECOGNIZED",
70 NotificationCategory::Deprecation => "DEPRECATION",
71 NotificationCategory::Schema => "SCHEMA",
72 NotificationCategory::Hint => "HINT",
73 }
74 }
75}
76
77impl std::fmt::Display for NotificationCategory {
78 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
79 f.write_str(self.as_str())
80 }
81}
82
83struct NotificationRow {
87 code: &'static str,
88 gql_status: &'static str,
89 severity: NotificationSeverity,
90 category: NotificationCategory,
91 title: &'static str,
92 remedy: &'static str,
93 plan_warning: bool,
97 occurrence_scoped: bool,
104}
105
106macro_rules! notification_vocabulary {
116 ($(
117 $(#[$doc:meta])*
118 $kind:ident {
119 code: $code:expr,
120 gql_status: $gql_status:expr,
121 severity: $severity:expr,
122 category: $category:expr,
123 title: $title:expr,
124 remedy: $remedy:expr,
125 plan_warning: $plan_warning:expr,
126 occurrence_scoped: $occurrence_scoped:expr $(,)?
127 }
128 )*) => {
129 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
132 pub enum NotificationKind {
133 $($(#[$doc])* $kind,)*
134 }
135
136 impl NotificationKind {
137 #[cfg(test)]
139 pub(crate) const ALL: &'static [NotificationKind] =
140 &[$(NotificationKind::$kind),*];
141
142 fn row(self) -> &'static NotificationRow {
146 match self {
147 $(NotificationKind::$kind => &NotificationRow {
148 code: $code,
149 gql_status: $gql_status,
150 severity: $severity,
151 category: $category,
152 title: $title,
153 remedy: $remedy,
154 plan_warning: $plan_warning,
155 occurrence_scoped: $occurrence_scoped,
156 },)*
157 }
158 }
159 }
160 };
161}
162
163notification_vocabulary! {
164 CartesianProduct {
166 code: "Neo.ClientNotification.Statement.CartesianProduct",
167 gql_status: "03N90",
168 severity: NotificationSeverity::Information,
169 category: NotificationCategory::Performance,
170 title: "Cartesian product",
171 remedy: "Give the patterns a join anchor: reuse a node variable across them, or add a \
172 pattern that relates their endpoints; otherwise run them as separate queries.",
173 plan_warning: true,
174 occurrence_scoped: true,
175 }
176 UnboundedVariableLengthPattern {
178 code: "Neo.ClientNotification.Statement.UnboundedVariableLengthPattern",
179 gql_status: "03N91",
180 severity: NotificationSeverity::Information,
181 category: NotificationCategory::Performance,
182 title: "Unbounded variable-length pattern",
183 remedy: "Bound the expansion (`[:R*1..5]`) where arbitrary length is not required, or add \
184 a selective endpoint/label predicate and a `LIMIT`.",
185 plan_warning: false,
186 occurrence_scoped: true,
187 }
188 AllNodesScan {
190 code: "Relate.Notification.Statement.AllNodesScan",
191 gql_status: "03C90",
192 severity: NotificationSeverity::Information,
193 category: NotificationCategory::Performance,
194 title: "All nodes scan",
195 remedy: "Name the label the scan intends (`MATCH (n:<Label>)`); on the index's label the \
196 scan becomes an index-backed lookup.",
197 plan_warning: true,
198 occurrence_scoped: false,
199 }
200 LabelDisjunctionScan {
203 code: "Relate.Notification.Statement.LabelDisjunctionScan",
204 gql_status: "03C94",
205 severity: NotificationSeverity::Information,
206 category: NotificationCategory::Performance,
207 title: "Label disjunction scan",
208 remedy: "Create a range index on each disjunct label's filtered property: the disjunction \
209 then serves as per-label keyed lookups instead of per-label scans.",
210 plan_warning: true,
211 occurrence_scoped: false,
212 }
213 MissingIndex {
215 code: "Relate.Notification.Statement.MissingIndex",
216 gql_status: "03C91",
217 severity: NotificationSeverity::Information,
218 category: NotificationCategory::Performance,
219 title: "Missing index",
220 remedy: "`CREATE INDEX relate_Person__email FOR (n:Person) ON (n.email)` — the exact \
221 runnable statement, with the name derived deterministically from label and \
222 property.",
223 plan_warning: false,
224 occurrence_scoped: false,
225 }
226 EagerAggregation {
228 code: "Relate.Notification.Statement.EagerAggregation",
229 gql_status: "03C92",
230 severity: NotificationSeverity::Information,
231 category: NotificationCategory::Performance,
232 title: "Eager aggregation",
233 remedy: "Reduce the rows reaching the aggregation with a selective label/property \
234 predicate or a `LIMIT` before it; profile again to confirm the buffered input \
235 shrank.",
236 plan_warning: false,
237 occurrence_scoped: false,
238 }
239 EstimationMiss {
241 code: "Relate.Notification.Statement.EstimationMiss",
242 gql_status: "03C93",
243 severity: NotificationSeverity::Information,
244 category: NotificationCategory::Performance,
245 title: "Estimation miss",
246 remedy: "Rework the operator's input so the estimate can see the filter (add the \
247 selective predicate at the scan, or reorder the join); the estimate is a planner \
248 assumption, not a runtime fact.",
249 plan_warning: true,
250 occurrence_scoped: false,
251 }
252 UnknownLabelWarning {
254 code: "Neo.ClientNotification.Statement.UnknownLabelWarning",
255 gql_status: "01N50",
256 severity: NotificationSeverity::Warning,
257 category: NotificationCategory::Unrecognized,
258 title: "Unknown label",
259 remedy: "Check the spelling; the label exists after the first write that creates it, and \
260 no index or constraint uses the unknown name.",
261 plan_warning: false,
262 occurrence_scoped: false,
263 }
264 UnknownRelationshipTypeWarning {
266 code: "Neo.ClientNotification.Statement.UnknownRelationshipTypeWarning",
267 gql_status: "01N51",
268 severity: NotificationSeverity::Warning,
269 category: NotificationCategory::Unrecognized,
270 title: "Unknown relationship type",
271 remedy: "Check the spelling; the type exists after the first write that creates it.",
272 plan_warning: false,
273 occurrence_scoped: false,
274 }
275 UnknownPropertyKeyWarning {
277 code: "Neo.ClientNotification.Statement.UnknownPropertyKeyWarning",
278 gql_status: "01N52",
279 severity: NotificationSeverity::Warning,
280 category: NotificationCategory::Unrecognized,
281 title: "Unknown property key",
282 remedy: "Check the spelling; the key exists after the first write that sets it.",
283 plan_warning: false,
284 occurrence_scoped: false,
285 }
286 DeprecatedFunction {
288 code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
289 gql_status: "01N01",
290 severity: NotificationSeverity::Warning,
291 category: NotificationCategory::Deprecation,
292 title: "Deprecated function",
293 remedy: "Replace the call with the catalog's `deprecated_by` (`id(n)` → `elementId(n)`).",
294 plan_warning: false,
295 occurrence_scoped: true,
296 }
297 DeprecatedProcedure {
299 code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
300 gql_status: "01N01",
301 severity: NotificationSeverity::Warning,
302 category: NotificationCategory::Deprecation,
303 title: "Deprecated procedure",
304 remedy: "Use the registry's `deprecated_by` replacement instead; the replacement is the \
305 remedy.",
306 plan_warning: false,
307 occurrence_scoped: true,
308 }
309 CallSubqueryWithoutScope {
311 code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
312 gql_status: "01N00",
313 severity: NotificationSeverity::Warning,
314 category: NotificationCategory::Deprecation,
315 title: "CALL subquery without scope",
316 remedy: "Add the scope clause the body imports: `CALL (n) { … }`, or `CALL () { … }` when \
317 it imports nothing.",
318 plan_warning: false,
319 occurrence_scoped: true,
320 }
321 MergeSelfReference {
323 code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
324 gql_status: "01N00",
325 severity: NotificationSeverity::Warning,
326 category: NotificationCategory::Deprecation,
327 title: "Merge self-reference",
328 remedy: "Compute the property into a separate variable before the MERGE, or set it \
329 with ON CREATE SET after the merge.",
330 plan_warning: false,
331 occurrence_scoped: true,
332 }
333 AmbiguousSubclauseReference {
336 code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
337 gql_status: "01N01",
338 severity: NotificationSeverity::Warning,
339 category: NotificationCategory::Deprecation,
340 title: "Deprecated ambiguous subclause reference",
341 remedy: "Reference the projection item by an alias, or use the `GROUP BY` clause.",
342 plan_warning: false,
343 occurrence_scoped: true,
344 }
345 ComplexSubclauseReference {
348 code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
349 gql_status: "01N01",
350 severity: NotificationSeverity::Warning,
351 category: NotificationCategory::Deprecation,
352 title: "Deprecated complex subclause reference",
353 remedy: "Reference the projection item expression by an alias.",
354 plan_warning: false,
355 occurrence_scoped: true,
356 }
357 CreateSelfReference {
360 code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
361 gql_status: "01N00",
362 severity: NotificationSeverity::Warning,
363 category: NotificationCategory::Deprecation,
364 title: "Create self-reference",
365 remedy: "Create the entity in a separate `CREATE` clause before referencing it, or set \
366 the property afterwards.",
367 plan_warning: false,
368 occurrence_scoped: true,
369 }
370 SubqueryVariableShadowing {
372 code: "Neo.ClientNotification.Statement.SubqueryVariableShadowing",
373 gql_status: "03N60",
374 severity: NotificationSeverity::Information,
375 category: NotificationCategory::Unrecognized,
376 title: "Subquery variable shadowing",
377 remedy: "Import the outer variable with `CALL (name) { … }`, or rename the inner one.",
378 plan_warning: false,
379 occurrence_scoped: true,
380 }
381 DynamicProperty {
384 code: "Neo.ClientNotification.Statement.DynamicProperty",
385 gql_status: "03N95",
386 severity: NotificationSeverity::Information,
387 category: NotificationCategory::Performance,
388 title: "Queries using dynamic properties will use neither index seeks nor \
389 index scans for those properties",
390 remedy: "Use a static property so index lookups stay possible.",
391 plan_warning: false,
392 occurrence_scoped: false,
393 }
394 UnsatisfiableRelationshipTypeExpression {
396 code: "Neo.ClientNotification.Statement.UnsatisfiableRelationshipTypeExpression",
397 gql_status: "01N61",
398 severity: NotificationSeverity::Warning,
399 category: NotificationCategory::Unrecognized,
400 title: "Unsatisfiable relationship type expression",
401 remedy: "Request one type or a disjunction of types; a relationship has exactly one type.",
402 plan_warning: false,
403 occurrence_scoped: true,
404 }
405 RepeatedRelationshipVariable {
407 code: "Neo.ClientNotification.Statement.RepeatedRelationshipVariable",
408 gql_status: "01N63",
409 severity: NotificationSeverity::Warning,
410 category: NotificationCategory::Unrecognized,
411 title: "Repeated relationship pattern variable",
412 remedy: "Use a distinct variable per relationship position; a relationship cannot be \
413 traversed twice in one pattern.",
414 plan_warning: false,
415 occurrence_scoped: true,
416 }
417 SearchIdentifierShadowingVariable {
419 code: "Neo.ClientNotification.Statement.IdentifierShadowingVariable",
420 gql_status: "03N63",
421 severity: NotificationSeverity::Information,
422 category: NotificationCategory::Unrecognized,
423 title: "Identifier shadowing variable",
424 remedy: "Rename the index or the variable; the index name is taken literally.",
425 plan_warning: false,
426 occurrence_scoped: true,
427 }
428 ExhaustiveShortestPath {
430 code: "Neo.ClientNotification.Statement.ExhaustiveShortestPath",
431 gql_status: "03N92",
432 severity: NotificationSeverity::Information,
433 category: NotificationCategory::Performance,
434 title: "Exhaustive shortest path",
435 remedy: "Separate the existential predicate from the `MATCH` with `WITH` where possible.",
436 plan_warning: false,
437 occurrence_scoped: true,
438 }
439 SchemaIndexOrConstraintAlreadyExists {
442 code: "Neo.ClientNotification.Schema.IndexOrConstraintAlreadyExists",
443 gql_status: "00NA0",
444 severity: NotificationSeverity::Information,
445 category: NotificationCategory::Schema,
446 title: "Index or constraint already exists",
447 remedy: "Drop the existing index or constraint first, or use a different name or schema.",
448 plan_warning: false,
449 occurrence_scoped: false,
450 }
451 SchemaIndexOrConstraintDoesNotExist {
454 code: "Neo.ClientNotification.Schema.IndexOrConstraintDoesNotExist",
455 gql_status: "00NA1",
456 severity: NotificationSeverity::Information,
457 category: NotificationCategory::Schema,
458 title: "Index or constraint does not exist",
459 remedy: "Check the name; `IF EXISTS` makes a missing index or constraint a no-op.",
460 plan_warning: false,
461 occurrence_scoped: false,
462 }
463 SchemaVectorIndexDimensionsNotSpecified {
465 code: "Neo.ClientNotification.Schema.VectorIndexDimensionsNotSpecified",
466 gql_status: "00NA2",
467 severity: NotificationSeverity::Information,
468 category: NotificationCategory::Schema,
469 title: "Vector index dimensions not specified",
470 remedy: "Set `vector.dimensions` in `OPTIONS { indexConfig: { … } }` when creating the index.",
471 plan_warning: false,
472 occurrence_scoped: false,
473 }
474 HintedIndexNotFound {
476 code: "Neo.ClientNotification.Schema.HintedIndexNotFound",
477 gql_status: "01N31",
478 severity: NotificationSeverity::Warning,
479 category: NotificationCategory::Hint,
480 title: "The request (directly or indirectly) referred to an index that \
481 does not exist.",
482 remedy: "Create the index, or drop the hint.",
483 plan_warning: false,
484 occurrence_scoped: true,
485 }
486 JoinHintUnfulfillable {
488 code: "Neo.ClientNotification.Statement.JoinHintUnfulfillableWarning",
489 gql_status: "01N30",
490 severity: NotificationSeverity::Warning,
491 category: NotificationCategory::Hint,
492 title: "The database was unable to plan a hinted join.",
493 remedy: "Try a different join key or restructure the query.",
494 plan_warning: false,
495 occurrence_scoped: true,
496 }
497 RedundantOptionalProcedure {
499 code: "Neo.ClientNotification.Statement.RedundantOptionalProcedure",
500 gql_status: "03N61",
501 severity: NotificationSeverity::Information,
502 category: NotificationCategory::Performance,
503 title: "Redundant optional procedure",
504 remedy: "Drop `OPTIONAL`: the procedure declares no return columns, so the call yields \
505 the same single row either way.",
506 plan_warning: false,
507 occurrence_scoped: true,
508 }
509 RedundantOptionalSubquery {
511 code: "Neo.ClientNotification.Statement.RedundantOptionalSubquery",
512 gql_status: "03N62",
513 severity: NotificationSeverity::Information,
514 category: NotificationCategory::Performance,
515 title: "Redundant optional subquery",
516 remedy: "Drop `OPTIONAL`: the subquery projects no columns, so the call yields the same \
517 single row either way.",
518 plan_warning: false,
519 occurrence_scoped: true,
520 }
521}
522
523impl NotificationKind {
524 pub fn dedups_identical(self) -> bool {
531 !self.row().occurrence_scoped
532 }
533
534 pub fn is_plan_warning(self) -> bool {
542 self.row().plan_warning
543 }
544
545 pub fn code(self) -> &'static str {
548 self.row().code
549 }
550
551 pub fn gql_status(self) -> &'static str {
553 self.row().gql_status
554 }
555
556 pub fn severity(self) -> NotificationSeverity {
558 self.row().severity
559 }
560
561 pub fn category(self) -> NotificationCategory {
563 self.row().category
564 }
565
566 pub fn title(self) -> &'static str {
569 self.row().title
570 }
571
572 pub fn remedy(self) -> &'static str {
575 self.row().remedy
576 }
577}
578
579#[derive(Clone, Debug, PartialEq, Eq)]
591pub struct Notification {
592 kind: NotificationKind,
593 description: String,
594 remedy: Option<String>,
595 operator_id: Option<usize>,
596}
597
598impl Notification {
599 pub fn new(kind: NotificationKind, description: impl Into<String>) -> Self {
603 Notification {
604 kind,
605 description: description.into(),
606 remedy: None,
607 operator_id: None,
608 }
609 }
610
611 pub fn with_operator_id(mut self, operator_id: usize) -> Self {
614 self.operator_id = Some(operator_id);
615 self
616 }
617
618 pub fn with_remedy(mut self, remedy: impl Into<String>) -> Self {
621 self.remedy = Some(remedy.into());
622 self
623 }
624
625 pub fn kind(&self) -> NotificationKind {
627 self.kind
628 }
629
630 pub fn description(&self) -> &str {
633 &self.description
634 }
635
636 pub fn code(&self) -> &'static str {
638 self.kind.code()
639 }
640
641 pub fn gql_status(&self) -> &'static str {
643 self.kind.gql_status()
644 }
645
646 pub fn title(&self) -> &'static str {
648 self.kind.title()
649 }
650
651 pub fn severity(&self) -> NotificationSeverity {
653 self.kind.severity()
654 }
655
656 pub fn category(&self) -> NotificationCategory {
658 self.kind.category()
659 }
660
661 pub fn remedy(&self) -> &str {
665 self.remedy.as_deref().unwrap_or_else(|| self.kind.remedy())
666 }
667
668 pub fn operator_id(&self) -> Option<usize> {
670 self.operator_id
671 }
672}
673
674pub mod notification_keys {
678 pub const CODE: &str = "code";
680 pub const GQL_STATUS: &str = "gql_status";
682 pub const SEVERITY: &str = "severity";
684 pub const CATEGORY: &str = "category";
686 pub const TITLE: &str = "title";
688 pub const DESCRIPTION: &str = "description";
690 pub const REMEDY: &str = "remedy";
692 pub const OPERATOR_ID: &str = "operator_id";
694 pub const NOTIFICATIONS: &str = "notifications";
696}
697
698pub(crate) fn notification_fields(notification: &Notification) -> Map<String, Value> {
707 let mut obj = Map::new();
708 obj.insert(
709 notification_keys::CODE.into(),
710 Value::String(notification.code().into()),
711 );
712 obj.insert(
713 notification_keys::GQL_STATUS.into(),
714 Value::String(notification.gql_status().into()),
715 );
716 obj.insert(
717 notification_keys::SEVERITY.into(),
718 Value::String(notification.severity().as_str().into()),
719 );
720 obj.insert(
721 notification_keys::CATEGORY.into(),
722 Value::String(notification.category().as_str().into()),
723 );
724 obj.insert(
725 notification_keys::TITLE.into(),
726 Value::String(notification.title().into()),
727 );
728 obj.insert(
729 notification_keys::DESCRIPTION.into(),
730 Value::String(notification.description().into()),
731 );
732 obj.insert(
733 notification_keys::REMEDY.into(),
734 Value::String(notification.remedy().into()),
735 );
736 obj
737}
738
739pub fn notification_to_wire_json(notification: &Notification) -> Value {
743 let mut obj = notification_fields(notification);
744 if let Some(operator_id) = notification.operator_id() {
745 obj.insert(
746 notification_keys::OPERATOR_ID.into(),
747 Value::from(operator_id),
748 );
749 }
750 Value::Object(obj)
751}
752
753pub fn notifications_to_wire_json(notifications: &[Notification]) -> Value {
756 Value::Array(
757 notifications
758 .iter()
759 .map(notification_to_wire_json)
760 .collect(),
761 )
762}
763
764pub fn notification_to_neo4j_entries(notification: &Notification) -> Vec<(&'static str, String)> {
772 vec![
773 (notification_keys::CODE, notification.code().to_string()),
774 (notification_keys::TITLE, notification.title().to_string()),
775 (
776 notification_keys::DESCRIPTION,
777 format!(
778 "{} (remedy: {})",
779 notification.description(),
780 notification.remedy()
781 ),
782 ),
783 (
784 notification_keys::SEVERITY,
785 notification.severity().as_str().to_string(),
786 ),
787 (
788 notification_keys::CATEGORY,
789 notification.category().as_str().to_string(),
790 ),
791 ]
792}
793
794pub fn notification_to_neo4j_json(notification: &Notification) -> Value {
804 let obj: Map<String, Value> = notification_to_neo4j_entries(notification)
805 .into_iter()
806 .map(|(key, value)| (key.to_owned(), Value::String(value)))
807 .collect();
808 Value::Object(obj)
809}
810
811#[cfg(test)]
812#[path = "notification_wire/tests.rs"]
813mod tests;