Skip to content

Commit a6ec0b6

Browse files
simon-dewsimon-dew
authored
DOC-12829: Publish Couchbase Server 7.6.4 Docs
Merge pull request #306 from couchbaselabs/prerelease/7.6.4 Rebase and merge not available due to merge conflicts.
2 parents 4f8b5f8 + 65db615 commit a6ec0b6

33 files changed

+2219
-55
lines changed

‎modules/n1ql/pages/n1ql-intro/sysinfo.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,31 @@
33
:description: {sqlpp} has a system namespace that stores metadata about data containers, the Query service, and the system as a whole. \
44
You can query the system namespace to get this information.
55

6+
// Pass through HTML table styles for this page
7+
8+
ifdef::basebackend-html[]
9+
++++
10+
<style type="text/css">
11+
/* No maximum width for table cells */
12+
.doc table.spread > tbody > tr > *,
13+
.doc table.stretch > tbody > tr > * {
14+
max-width: none !important;
15+
}
16+
17+
/* Ignore fixed column widths */
18+
table:not(.fixed-width) col{
19+
width: auto !important;
20+
}
21+
22+
/* Do not hyphenate words in the table */
23+
td.tableblock p,
24+
p.tableblock{
25+
hyphens: manual !important;
26+
}
27+
</style>
28+
++++
29+
endif::[]
30+
631
[abstract]
732
{description}
833

@@ -29,6 +54,7 @@ xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#vitals[system:vitals]
2954
xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-active-req[system:active_requests]
3055
xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-prepared[system:prepareds]
3156
xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-completed-req[system:completed_requests]
57+
xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-history[system:completed_requests_history]
3258

3359
a| [%hardbreaks]
3460
<<sys_my-user-info,system:my_user_info>>

‎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

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

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -188,7 +188,7 @@ INSERT INTO bookings
188188
====
189189

190190
[[ex-nextval-key]]
191-
.Insert a sequential value in a document key
191+
.Insert a sequential value in a document key and body
192192
====
193193
The following statement uses the `ordNum` sequence to generate the document key and a booking number within the body of the document.
194194
@@ -201,6 +201,12 @@ INSERT INTO bookings
201201
RETURNING META().id, *;
202202
----
203203
204+
This query gives different results, depending on the version of Couchbase Server.
205+
206+
'''
207+
208+
[.status]##Couchbase Server 7.6&ndash;7.6.3##
209+
204210
.Results
205211
[source,json]
206212
----
@@ -215,12 +221,33 @@ INSERT INTO bookings
215221
]
216222
----
217223
218-
Since the key is not part of the document, the query has incremented the sequence twice.
219-
This gives a different sequence number for the document key and the document value, which may not be what you want.
224+
In versions of Couchbase Server prior to 7.6.4, the key is not regarded as part of the document, so this query increments the sequence twice.
225+
This gives a different sequence number for the document key and the document value.
226+
227+
'''
228+
229+
[.status]#Couchbase Server 7.6.4#
230+
231+
.Results
232+
[source,json]
233+
----
234+
[
235+
{
236+
"id": "1001",
237+
"bookings": {
238+
"num": 1001,
239+
"user": 1
240+
}
241+
}
242+
]
243+
----
244+
245+
In Couchbase Server 7.6.4 and later, the entire VALUES clause (key, value, and options) is regarded as a single document, so the query only increments the sequence once.
246+
This gives the same sequence number in the document key and the document value.
220247
====
221248

222249
[[ex-nextval-same]]
223-
.Insert the same sequential value in a document key and body
250+
.Insert a sequential value with INSERT SELECT
224251
====
225252
The following statement uses an INSERT SELECT statement.
226253
With this query, the document key and document value are both generated within the same document.

0 commit comments

Comments
 (0)