Skip to content

Commit 6c334ef

Browse files
simon-dewsimon-dew
committed
DOC-12321: Add docs for finderr tool and builtin function (#268)
* Add FINDERR() function * Add link to SQL++ Error Codes
1 parent 480dfba commit 6c334ef

File tree

1 file changed

+256
-0
lines changed

1 file changed

+256
-0
lines changed

‎modules/n1ql/pages/n1ql-language-reference/metafun.adoc‎

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -331,6 +331,262 @@ SELECT DS_VERSION() as server_version;
331331
----
332332
====
333333

334+
[[finderr,FINDERR()]]
335+
== FINDERR(`expression`)
336+
337+
[.status]#Couchbase Server 7.6.5#
338+
339+
=== Description
340+
341+
Returns the full details of any Query service or cbq shell error.
342+
343+
=== Arguments
344+
345+
expression:: One of the following:
346+
+
347+
--
348+
* A number representing an error code.
349+
In this case, the function returns the full details of the error matching the error code.
350+
351+
* A string.
352+
In this case, the function searches for the target string in all of the error message fields except for `user_error`, and returns the full details of any errors that match the string.
353+
354+
* A regular expression.
355+
In this case, the function searches for the regular expression in all of the error message fields except for `user_error`, and returns the full details of any errors that match the pattern.
356+
--
357+
358+
=== Return Value
359+
360+
The return value is an array of one or more objects, each of which contains the details of an error that matches the find expression.
361+
362+
For each error, the function returns the following fields.
363+
364+
[options="header", cols="~a,~a,~a"]
365+
|===
366+
|Name|Description|Schema
367+
368+
|**applies_to** +
369+
__required__
370+
|One of the following:
371+
372+
* `cbq-shell`: The error applies to the cbq shell.
373+
* `Server`: The error applies to the server.
374+
|enum (cbq-shell, Server)
375+
376+
|**code** +
377+
__required__
378+
|A number representing the error.
379+
|Integer
380+
381+
|**description** +
382+
__required__
383+
|Message describing why the error occurred.
384+
|String
385+
386+
|**reason** +
387+
__optional__
388+
|List of possible causes of the error.
389+
|String array
390+
391+
|**user_action** +
392+
__optional__
393+
|List of possible steps a user can take to mitigate the error.
394+
|String array
395+
396+
|**user_error** +
397+
__optional__
398+
|One of the following:
399+
400+
* `Yes`: The error was caused by the user.
401+
* `No`: The error was caused by other services, or was internal to the server.
402+
* `Maybe`: A combination of both.
403+
|enum (Yes, No, Maybe)
404+
|===
405+
406+
NOTE: The error details also include a `symbol` field, which contains a representation string for the error.
407+
This field is for internal use only, and is not shown in the results.
408+
However, the FINDERR function does search this field when the find expression is a string or a regular expression.
409+
410+
=== Examples
411+
412+
[[finderr-ex1,FINDERR() Example 1]]
413+
.Find error details by code number
414+
====
415+
.Query
416+
[source,sqlpp]
417+
----
418+
SELECT FINDERR(5011);
419+
----
420+
421+
.Results
422+
[source,json]
423+
----
424+
[
425+
{
426+
"$1": [
427+
{
428+
"applies_to": "Server",
429+
"code": 5011,
430+
"description": "Abort: «reason»",
431+
"reason": [
432+
[
433+
"The SQL++ abort() function was called in the statement.",
434+
"e.g. SELECT abort('An example cause')"
435+
]
436+
],
437+
"user_error": "Yes"
438+
}
439+
]
440+
}
441+
]
442+
----
443+
====
444+
445+
[[finderr-ex2,FINDERR() Example 2]]
446+
.Find error details by matching a string
447+
====
448+
.Query
449+
[source,sqlpp]
450+
----
451+
SELECT FINDERR("A semantic error is present in the statement.");
452+
----
453+
454+
.Results
455+
[source,json]
456+
----
457+
[
458+
{
459+
"$1": [
460+
{
461+
"applies_to": "Server",
462+
"code": 3100,
463+
"description": "A semantic error is present in the statement.",
464+
"reason": [
465+
"The statement includes portions that violate semantic constraints."
466+
],
467+
"user_action": [
468+
"The cause will contain more detail on the violation; revise the statement and re-submit."
469+
],
470+
"user_error": "Yes"
471+
}
472+
]
473+
}
474+
]
475+
----
476+
====
477+
478+
[[finderr-ex3,FINDERR() Example 3]]
479+
.Find multiple error details by matching a string
480+
====
481+
.Query
482+
[source,sqlpp]
483+
----
484+
SELECT FINDERR("semantic");
485+
----
486+
487+
.Results
488+
[source,json]
489+
----
490+
[
491+
{
492+
"$1": [
493+
{
494+
"applies_to": "Server",
495+
"code": 3100,
496+
"description": "A semantic error is present in the statement.",
497+
"reason": [
498+
"The statement includes portions that violate semantic constraints."
499+
],
500+
"user_action": [
501+
"The cause will contain more detail on the violation; revise the statement and re-submit."
502+
],
503+
"user_error": "Yes"
504+
},
505+
{
506+
"applies_to": "Server",
507+
"code": 3220,
508+
"description": "«name» window function «clause» «reason»",
509+
"reason": [
510+
"A violation of the window function semantic restrictions was present in the statement."
511+
],
512+
"user_action": [
513+
"Revise the statement to remove the violation."
514+
],
515+
"user_error": "Yes"
516+
},
517+
{
518+
"applies_to": "Server",
519+
"code": 3300,
520+
"description": "recursive_with semantics: «cause»",
521+
"reason": [
522+
"The statement specifies restricted syntax in a recursive common table expression definition."
523+
],
524+
"user_action": [
525+
"Revise the statement removing the restricted syntax."
526+
],
527+
"user_error": "Yes"
528+
}
529+
]
530+
}
531+
]
532+
----
533+
====
534+
535+
[[finderr-ex4,FINDERR() Example 4]]
536+
.Find multiple error details by matching a regular expression
537+
====
538+
.Query
539+
[source,sqlpp]
540+
----
541+
SELECT FINDERR("[IU][NP]SERT");
542+
----
543+
544+
.Results
545+
[source,json]
546+
----
547+
[
548+
{
549+
"$1": [
550+
{
551+
"applies_to": "Server",
552+
"code": 3150,
553+
"description": "MERGE with ON KEY clause cannot have document key specification in INSERT action.",
554+
"reason": [
555+
[
556+
"A lookup merge statement specified a document key.",
557+
"e.g. MERGE INTO default USING [{},{}] AS source ON KEY 'aaa' WHEN NOT MATCHED THEN INSERT ('key',{})"
558+
]
559+
],
560+
"user_action": [
561+
"Refer to the documentation for lookup merge statements."
562+
],
563+
"user_error": "Yes"
564+
},
565+
// ...
566+
{
567+
"applies_to": "Server",
568+
"code": 5072,
569+
"description": "No UPSERT key for «value»",
570+
"user_action": [
571+
"Contact support."
572+
]
573+
},
574+
// ...
575+
{
576+
"applies_to": "Server",
577+
"code": 15005,
578+
"description": "No keys to insert «details»"
579+
}
580+
]
581+
}
582+
]
583+
----
584+
====
585+
586+
=== See Also
587+
588+
* xref:n1ql:n1ql-language-reference/n1ql-error-codes.adoc[]
589+
334590
[[flatten_keys,FLATTEN_KEYS()]]
335591
== FLATTEN_KEYS(`expr1` [ `modifiers` ], `expr2` [ `modifiers` ], ...)
336592

0 commit comments

Comments
 (0)