Skip to content

Commit 038f4db

Browse files
simon-dewsarahlwelton
simon-dew
authored and
sarahlwelton
committed
DOC-12321: Add docs for finderr tool and builtin function (#268)
* Add FINDERR() function * Add link to finderr command-line tool * Add link to SQL++ Error Codes
1 parent 982ed9a commit 038f4db

File tree

1 file changed

+259
-0
lines changed

1 file changed

+259
-0
lines changed

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

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

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

0 commit comments

Comments
 (0)