diff --git a/modules/guides/pages/defer-index.adoc b/modules/guides/pages/defer-index.adoc index d1fcb63e0..c564531c0 100644 --- a/modules/guides/pages/defer-index.adoc +++ b/modules/guides/pages/defer-index.adoc @@ -109,12 +109,12 @@ The following examples create a set of primary and secondary indexes in the spec [source,java] ---- -include::java-sdk:hello-world:example$IndexHelloWorld.java[tag=defer-create-primary,indent=0] +include::java-sdk:devguide:example$java/IndexHelloWorld.java[tag=defer-create-primary,indent=0] ---- [source,java] ---- -include::java-sdk:hello-world:example$IndexHelloWorld.java[tag=defer-create-secondary,indent=0] +include::java-sdk:devguide:example$java/IndexHelloWorld.java[tag=defer-create-secondary,indent=0] ---- {github} @@ -165,12 +165,12 @@ The following examples create a set of primary and secondary indexes in the spec [source,python] ---- -include::python-sdk:devguide:example$python/index_hello_world.py[tag=defer-create-primary,indent=0] +include::python-sdk:hello-world:example$index_hello_world.py[tag=defer-create-primary,indent=0] ---- [source,python] ---- -include::python-sdk:devguide:example$python/index_hello_world.py[tag=defer-create-secondary,indent=0] +include::python-sdk:hello-world:example$index_hello_world.py[tag=defer-create-secondary,indent=0] ---- {github} @@ -251,7 +251,7 @@ The following example builds all deferred indexes in the specified keyspace. [source,java] ---- -include::java-sdk:hello-world:example$IndexHelloWorld.java[tag=defer-build,indent=0] +include::java-sdk:devguide:example$java/IndexHelloWorld.java[tag=defer-build,indent=0] ---- {github} @@ -289,7 +289,7 @@ The following example builds all deferred indexes in the specified keyspace. [source,python] ---- -include::python-sdk:devguide:example$python/index_hello_world.py[tag=defer-build,indent=0] +include::python-sdk:hello-world:example$index_hello_world.py[tag=defer-build,indent=0] ---- {github} diff --git a/modules/guides/pages/select.adoc b/modules/guides/pages/select.adoc index 9f40b2dc1..1689492bf 100644 --- a/modules/guides/pages/select.adoc +++ b/modules/guides/pages/select.adoc @@ -56,7 +56,7 @@ The result includes each row found. [source,csharp] ---- -include::dotnet-sdk:hello-world:example$StartUsing.cs[tag=n1ql-query,indent=0] +include::dotnet-sdk:hello-world:example$StartUsing.csx[tag=n1ql-query,indent=0] ---- {github} @@ -70,7 +70,7 @@ The result object includes each row found. [source,java] ---- -include::java-sdk:hello-world:example$StartUsing.java[tag=n1ql-query,indent=0] +include::java-sdk:devguide:example$java/StartUsing.java[tag=n1ql-query,indent=0] ---- {github} @@ -305,7 +305,7 @@ Querying with SDKs: * xref:c-sdk:howtos:n1ql-queries-with-sdk.adoc[C] | xref:dotnet-sdk:howtos:n1ql-queries-with-sdk.adoc[.NET] | xref:go-sdk:howtos:n1ql-queries-with-sdk.adoc[Go] -| xref:java-sdk:howtos:n1ql-queries-with-sdk.adoc[Java] +| xref:java-sdk:howtos:sqlpp-queries-with-sdk.adoc[Java] | xref:nodejs-sdk:howtos:n1ql-queries-with-sdk.adoc[Node.js] | xref:php-sdk:howtos:n1ql-queries-with-sdk.adoc[PHP] | xref:python-sdk:howtos:n1ql-queries-with-sdk.adoc[Python] diff --git a/modules/n1ql/assets/images/n1ql-language-reference/exclude-clause.png b/modules/n1ql/assets/images/n1ql-language-reference/exclude-clause.png new file mode 100644 index 000000000..cb7a8b101 Binary files /dev/null and b/modules/n1ql/assets/images/n1ql-language-reference/exclude-clause.png differ diff --git a/modules/n1ql/assets/images/n1ql-language-reference/exclude-term.png b/modules/n1ql/assets/images/n1ql-language-reference/exclude-term.png new file mode 100644 index 000000000..526de6c4f Binary files /dev/null and b/modules/n1ql/assets/images/n1ql-language-reference/exclude-term.png differ diff --git a/modules/n1ql/assets/images/n1ql-language-reference/select-clause.png b/modules/n1ql/assets/images/n1ql-language-reference/select-clause.png index 187f34128..c0349054e 100644 Binary files a/modules/n1ql/assets/images/n1ql-language-reference/select-clause.png and b/modules/n1ql/assets/images/n1ql-language-reference/select-clause.png differ diff --git a/modules/n1ql/assets/images/n1ql-language-reference/slice-expr.png b/modules/n1ql/assets/images/n1ql-language-reference/slice-expr.png index a02b7242c..ad0efc41c 100644 Binary files a/modules/n1ql/assets/images/n1ql-language-reference/slice-expr.png and b/modules/n1ql/assets/images/n1ql-language-reference/slice-expr.png differ diff --git a/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc b/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc index 775589b7a..30423e54b 100644 --- a/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc @@ -1497,6 +1497,119 @@ SELECT array_star(children).age FROM contacts WHERE fname = "Dave" ---- ==== +=== Empty Array Subscripts + +You can use an empty array subscript (`[ ]`) to return an array that includes only defined elements. + +The rules governing its use are as follows: + +[cols="1a,2a"] +|==== +| Expression | Description + +| `field[]` +|* If `field` is not an array, it returns `NULL`. +* If `field` is an array, it returns the array as is. + + +| `field[][]` +|* If `field` is not an array, it returns `NULL`. +* If `field` contains only unnamed arrays, it returns `field` as is. +Otherwise, it returns `NULL`. + +| `field[].field2` +|* If `field` is not an array, it returns `MISSING`. +* If `field` is an array, it extracts `field2` from each element in `field` and returns a new array with those values. +* If `field` contains unnamed arrays, they are flattened by one level. +Then from the resulting array, it extracts `field2` from each object where it is present. + +| `field[][].field2` +|* If `field` is not an array, it returns `MISSING`. +* If every element in `field` is not an unnamed array, it returns `MISSING`. +* If `field` contains unnamed arrays, they are flattened by one level. +Then from the resulting array, it extracts `field2` from each object where it is present. + + +| `field[].field2[].field3` +|* Returns an array of `field3` values by traversing two levels of arrays. +First it extracts `field2` from each element of `field`, then extracts `field3` from each element of the resulting `field2` array. +* If `field` and `field2` contain unnamed arrays, they are flattened by one level. +Then from the resulting `field2` array, it extracts `field3` from each object where it is present. + +|==== + +NOTE: If you use more that two empty array subscripts (for example, `field[][][]`), the function considers only the first two subscripts and ignores the rest. + +==== Example + +==== +Given the following sample document: + +[source,json] +---- +{ + "a": { + "airline": "AF", + "airlineid": "airline_003", + "destinationairport": "SFO", + "distance": 2481.617376098415, + "equipment": "320", + "id": 3, + "schedule": [ + { + "day": 0, + "flight": "AF198", + "utc": "10:13:00" + }, + { + "flight": "AF250", + "utc": "12:59:00" + }, + { + "day": 2, + "flight": "AF223", + "special_flights": [ + { + "a": "SA" + }, + { + "b": [ + [ + { + "c": "SC1" + }, + { + "c": "SC2" + } + ], + [ + { + "c": "SC3" + } + ] + ] + } + ], + "utc": "19:41:00" + } + ], + "sourceairport": "DFW" + } +} +---- + +Here's how different array subscripts evaluate: + +* `a.airline[]`: Returns `NULL` (not an array). +* `a.schedule[]`: Equivalent to `a.schedule`, returns the array. +* `a.schedule[].day`: Returns `[0, 2]`. This is in contrast to `a.schedule[*].day`, which returns `[0, null, 2]`. +* `a.schedule[].special_flights[].a`: Returns `["SA"]`. +* `a.schedule[][].utc`: Returns `MISSING`. +* `a.schedule[].special_flights[].b[][].c`: Returns `["SC1", "SC2", "SC3"]`. +* `a.schedule[].special_flights[].b[].c`: Also returns `["SC1", "SC2", "SC3"]`, as the unnamed arrays are flattened. + +==== + [[fn-array-sum,ARRAY_SUM()]] == ARRAY_SUM([.var]`expr`) diff --git a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc index 7a0662641..63c197999 100644 --- a/modules/n1ql/pages/n1ql-language-reference/datefun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/datefun.adoc @@ -65,6 +65,8 @@ Below are a few examples of commonly used timezones and their offsets: | +05:30 |==== +For a complete list of supported timezones, see https://www.iana.org/time-zones[the Timezone Database] + === Local System Timezone Many functions default to using the local timezone of the system, which will be one of the IANA timezones. @@ -504,6 +506,72 @@ The elements are given in the table below. | Seconds since 1970-01-01 00:00:00 UTC | `1624904579` +| `x` +| Same as `%D` +| `2021-06-28` + +| `r` +| 12-hour time, hh:mm:ss AM/PM +| `07:22:59 AM` + +| `X` +| Same as `%T` +| `19:22:59` + +| `:z` +| UTC offset in the format, +HH:MM +| `+05:30` + +| `::z` +| UTC offset in the format, +HH:MM:SS +| `+05:30:00` + +| `:::z` +| UTC offset with minimum precision as required for the time zone +| `+05:30` or `+05:30:00` + +| `V` +| ISO week number +| `27` + +| `G` +| Year corresponding to the ISO week number +| `2025` + +| `j` +| Day of the year +| `179` + +| `q` +| Quarter of the year, 1-4 +| `2` + +| `w` +| Day of the week (Sunday=0) +| `1` + +| `u` +| Day of the week (Monday=1, Sunday=7) +| `2` + + +| `U` +| Week number of year (Sunday is first day of the week) +| `27` + +| `W` +| Week number of year (Monday is first day of the week) +| `27` + +| `#` +| Time since Epoch in the format, [total hours]:mm:ss +| `406464:27:15` + + +| `@` +| Time since Epoch in the format, [total hours]:mm:ss.fff +| `406464:27:15.123` + |==== To specify a date format, you can put the format specifiers together in any order, along with any other characters as required. @@ -522,13 +590,23 @@ If the date string does not explicitly declare the value of a component, then th * The month and day default to 1. * The century (when not specified by year) defaults to 19 if year is greater than or equal to 69, or 20 otherwise. * All other numeric components default to 0. -* The time zone defaults to the local local system time zone. +* The time zone defaults to the local system time zone. In cases where the timezone is not specified, the local system time is assumed. For example, `2016-02-07` is equivalent to `2016-02-07T00:00:00` and parsing just `16` as the year is equivalent to `2016-01-01T00:00:00` in the local system time zone. ==== +[NOTE#tzn-date-format] +.TZN Date Format +==== +In addition to the date formats listed <>, {sqlpp} also supports the `TZN` (Time Zone Name) format. +This format parses date strings in the same way as `TZD` but outputs the time zone name instead of the offset. +For example, the `TZN` representation of the "Australia/Darwin" time zone is `ACST`. + +For an example of its usage, refer to the <> function. +==== + [#manipulating-components] == Manipulating Date Components @@ -1236,7 +1314,7 @@ WHERE reviews[0].date BETWEEN "2013-01-01 %" AND "2014-01-01 %"; NOTE: When querying between two dates, you must specify the full date (with time and time zone) or use the wildcard character (%). [#fn-date-format-str] -== DATE_FORMAT_STR(date1, fmt) +== DATE_FORMAT_STR(date1, [input-fmt,] fmt) === Description @@ -1249,6 +1327,13 @@ A string, or any valid xref:n1ql-language-reference/index.adoc[expression] which + If this argument is not a valid date string then `null` is returned. +input-fmt:: +The format of the input string, `date1`. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string. ++ +*Optional argument*. +Only required if `date1` is not in a standard format or if the input and output formats are different. + fmt:: A string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string, representing a <> to output the result as. + @@ -1265,7 +1350,8 @@ A date string in the format specified. ---- SELECT DATE_FORMAT_STR('2016-05-15T00:00:23+00:00', '1111-11-11') as full_to_short, DATE_FORMAT_STR('2016-05-15', '1111-11-11T00:00:00+00:00') as short_to_full, - DATE_FORMAT_STR('01:10:05', '1111-11-11T01:01:01Z') as time_to_full; + DATE_FORMAT_STR('01:10:05', '1111-11-11T01:01:01Z') as time_to_full, + DATE_FORMAT_STR('15-MAY-2016', 'DD-MON-YYYY', 'YYYY-MM-DD') as month_to_numeric; ---- .Results @@ -1274,8 +1360,9 @@ SELECT DATE_FORMAT_STR('2016-05-15T00:00:23+00:00', '1111-11-11') as full_to_sho [ { "full_to_short": "2016-05-15", - "short_to_full": "2016-05-15T00:00:00-07:00", - "time_to_full": "0000-01-01T01:10:05-08:00" + "short_to_full": "2016-05-15T00:00:00Z", + "time_to_full": "0000-01-01T01:10:05Z", + "month_to_numeric": "2016-05-15" } ] ---- @@ -1735,15 +1822,15 @@ SELECT DATE_TRUNC_MILLIS(1463284740000, 'day') as day, [ { "day": 1463270400000, - "month": 1462147200000, - "year": 1451696400000 + "month": 1462060800000, + "year": 1451606400000 } ] ---- ==== [#fn-date-trunc-str] -== DATE_TRUNC_STR(date1, part) +== DATE_TRUNC_STR(date1, part [,fmt]) === Description @@ -1763,6 +1850,13 @@ This function accepts the components `millennium`, `century`, `decade`, `year`, + If an invalid part is specified, then `null` is returned. +fmt:: +The format of the input string, `date1`. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string. ++ +*Optional argument*. +Only required if `date1` is not in a standard format. + === Return Value A date string representing the truncated date. @@ -1774,7 +1868,8 @@ A date string representing the truncated date. ---- SELECT DATE_TRUNC_STR('2016-05-18T03:59:00Z', 'day') as day, DATE_TRUNC_STR('2016-05-18T03:59:00Z', 'month') as month, - DATE_TRUNC_STR('2016-05-18T03:59:00Z', 'year') as year; + DATE_TRUNC_STR('2016-05-18T03:59:00Z', 'year') as year, + DATE_TRUNC_STR('05/18/2016 03:59:00', 'month', 'MM/DD/YYYY HH24:MI:SS') as month_custom; ---- .Results @@ -1784,7 +1879,8 @@ SELECT DATE_TRUNC_STR('2016-05-18T03:59:00Z', 'day') as day, { "day": "2016-05-18T00:00:00Z", "month": "2016-05-01T00:00:00Z", - "year": "2016-01-01T00:00:00Z" + "year": "2016-01-01T00:00:00Z", + "month_custom": "05/01/2016 00:00:00" } ] ---- @@ -2530,12 +2626,13 @@ AS Milliseconds; ==== [#fn-date-str-to-utc] -== STR_TO_UTC(date1) +== STR_TO_UTC(date1 [, [input-fmt,] fmt]) === Description Converts a date string into the equivalent date in UTC. -The output date format follows the date format of the date passed as input. +By default, the output date format follows the date format of the date passed as input. +However, you can specify a different output format if needed. === Arguments @@ -2545,6 +2642,20 @@ This is the date to convert to UTC. + If this argument is not a valid date format, then `null` is returned. +input-fmt:: +The format of the input string, `date1`. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string. ++ +*Optional argument*. +Only required if `date1` is not in a standard format or if the input and output formats are different. + +fmt:: +The format of the resulting UTC date. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string, and must be a <>. ++ +*Optional argument*. +If not specified, the output date format follows the date format of the input string, `date1`. + === Return Value A single date string representing the date string converted to UTC. @@ -2555,7 +2666,8 @@ A single date string representing the date string converted to UTC. [source,sqlpp] ---- SELECT STR_TO_UTC('1111-11-11T00:00:00+08:00') as full_date, -STR_TO_UTC('1111-11-11') as short_date; + STR_TO_UTC('1111-11-11') as short_date, + STR_TO_UTC('1111-11-11', 'YYYY-MM-DD', 'YYYY-MM-DD HH:MI:SS') as utc_date; ---- .Results @@ -2564,19 +2676,21 @@ STR_TO_UTC('1111-11-11') as short_date; [ { "full_date": "1111-11-10T16:00:00Z", - "short_date": "1111-11-11" + "short_date": "1111-11-11", + "utc_date": "1111-11-11 12:00:00" } ] ---- ==== [#fn-date-str-to-tz] -== STR_TO_TZ(date1, tz) +== STR_TO_TZ(date1, tz [, [input-fmt,] fmt]) === Description Converts a date string to its equivalent in the specified timezone. -The output date format follows the date format of the date passed as input. +By default, the output date format follows the date format of the date passed as input. +However, you can specify a different output format if needed. === Arguments @@ -2591,10 +2705,25 @@ A string, or any valid xref:n1ql-language-reference/index.adoc[expression] which + If this argument is not a valid timezone, then `null` is returned. +input-fmt:: +The format of the input string, `date1`. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string. ++ +*Optional argument*. +Only required if `date1` is not in a standard format or if the input and output formats are different. + +fmt:: +The format of the output date. +This can be a string, or any valid xref:n1ql-language-reference/index.adoc[expression] which evaluates to a string, and must be a <>. ++ +*Optional argument*. +If not specified, the output date format follows the date format of the input string, `date1`. + === Return Value A single date string representing the date string converted to the specified timezone. +[[ex-str-to-tz]] === Examples ==== @@ -2602,7 +2731,10 @@ A single date string representing the date string converted to the specified tim ---- SELECT STR_TO_TZ('1111-11-11T00:00:00+08:00', 'America/New_York') as est, STR_TO_TZ('1111-11-11T00:00:00+08:00', 'UTC') as utc, - STR_TO_TZ('1111-11-11', 'UTC') as utc_short; + STR_TO_TZ('1111-11-11', 'UTC') as utc_short, + STR_TO_TZ('1111-11-11', 'UTC', 'YYYY-MM-DD', 'YYYY-MM-DD HH:MI:SS') as utc_datetime, + STR_TO_TZ('1111-11-11T00:00:00+07:00', 'Europe/Paris', + "YYYY-MM-DDThh:mm:ssTZD", "YYYY-MM-DDThh:mm:ssTZN") as tzn; ---- .Results @@ -2610,9 +2742,11 @@ SELECT STR_TO_TZ('1111-11-11T00:00:00+08:00', 'America/New_York') as est, ---- [ { - "est": "1111-11-10T11:00:00-05:00", + "est": "1111-11-10T11:03:58-04:56", "utc": "1111-11-10T16:00:00Z", - "utc_short": "1111-11-11" + "utc_short": "1111-11-11", + "utc_datetime": "1111-11-11 12:00:00", + "tzn": "1111-11-10T17:09:21LMT" } ] ---- diff --git a/modules/n1ql/pages/n1ql-language-reference/nestedops.adoc b/modules/n1ql/pages/n1ql-language-reference/nestedops.adoc index d9540795f..a07fdca28 100644 --- a/modules/n1ql/pages/n1ql-language-reference/nestedops.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/nestedops.adoc @@ -132,7 +132,7 @@ expr:: An expression resolving to an array. start-expr:: -A numeric expression specifying a start position in the array, counting from 0. +[Optional] A numeric expression specifying a start position in the array, counting from 0. Negative positions are counted backwards from the end of the array. end-expr:: @@ -144,6 +144,8 @@ Negative positions are counted backwards from the end of the array. A new subset of the source array, containing the elements from the start position to the end position minus 1. The element at the start position is included, while the element at the end position is not. +If the start position is omitted, the subset starts from the beginning of the source array. + If the end position is omitted, all elements from the start position to the end of the source array are included. === Example @@ -164,4 +166,6 @@ Given the following data: The expression `revisions[1:3]` evaluates to the array value `[2012, 2011]`. The expression `revisions[1:]` evaluates to the array value `[2012, 2011, 2010]`. + +The expression `revisions[:2]` evaluates to the array value `[2013, 2012]`. ==== diff --git a/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc b/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc index df694f6d8..108f90822 100644 --- a/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/objectfun.adoc @@ -281,6 +281,169 @@ LIMIT 1; ---- ==== + +[[fn-obj-filter,OBJECT_FILTER()]] +== OBJECT_FILTER(`expression` [, `options`]) + +=== Description +This function extracts and returns nested fields from an input object that match a specified pattern, while retaining their original hierarchical path structure in the output. +This is particularly useful when working with complex objects, as it allows you to filter fields based on patterns using either regular expressions or exact matches. + +=== Arguments +expression:: An expression representing an object. + +options:: [Optional] A JSON object specifying options for the function. + +=== Options + +[options="header", cols="1a,3a,1a"] +|=== +| Name | Description | Schema + +| **pattern** + +__optional__ + +| The pattern to match. +This can be a regular expression or a simple string, depending on the `regex` parameter. +| String + +| **regex** + +__optional__ +| If `TRUE`, the pattern is treated as a regular expression. + +If `FALSE`, the pattern is treated as a simple string. + +*Default:* `TRUE` +| Boolean + +| **arraysubscript** + +__optional__ +| Specifies whether array subscripts are included in field names before applying the filter. + +If `TRUE`, array subscripts are included. + +If `FALSE`, array subscripts are replaced by `*`. + +*Default:* `TRUE` + +| Boolean + +| **composites** + +__optional__ +| Specifies whether the pattern should match field names that contain values requiring further processing, such as nested objects or arrays. + +If `TRUE`, the pattern is matched against every level of nested fields. + +If `FALSE`, the pattern is matched only against the deepest level of nested fields. + +*Default:* `TRUE` +| Boolean + +| **patternspace** + +__optional__ +| A string literal with two possible values. + +`"field"`: The pattern is matched against individual field names. + +`"path"`: The pattern is matched against composite path names. + +*Default:* `"path"` +| String + +| **exact** + +__optional__ +| Specifies whether the provided pattern must be an exact match for the field or path (as determined by the `patternspace` parameter). + +This is a short-cut for the regular expression start (^) and end ($) anchors, and can be used even when `regex` is set to `false`. + +If `TRUE`, the pattern must be an exact match. + +If `FALSE`, the pattern does not need to be an exact match. + +*Default:* `FALSE` +| Boolean + +| **ignorecase** + +__optional__ +| If `TRUE`, the pattern matching is case-sensitive. + +If `FALSE`, the pattern matching ignores case. + +*Default:* `FALSE` +| Boolean +|=== + +=== Return Value +An object containing only the fields that match the specified pattern. +Non-matching fields are excluded from the output. + +=== Examples + +[[obj-filter-ex1,OBJECT_FILTER() Example 1]] +.Filtering by field name +==== +.Query +[source,sqlpp] +---- +SELECT OBJECT_FILTER(t, {"pattern":"Business service"}) +FROM `travel-sample`.`inventory`.`hotel` t +WHERE type = 'hotel' +LIMIT 2; +---- +.Results +[source,json] +---- +[ + { + "$1": { + "reviews": [ + { + "ratings": { + "Business service (e.g., internet access)": 4 + } + } + ] + } + }, + { + "$1": null + } +] +---- +==== + +[[obj-filter-ex2,OBJECT_FILTER() Example 2]] +.Filtering by full path +You can use <> to generate the full path to a field, and then use that path in the `pattern` parameter. +==== +.Query +[source,sqlpp] +---- +SELECT OBJECT_FILTER(t, { "pattern": "reviews[1].ratings.Service", "regex": false }) +FROM `travel-sample`.`inventory`.`hotel` t +WHERE type = 'hotel' +LIMIT 1; +---- +.Results +[source,json] +---- +[ + { + "$1": { + "reviews": [ + { + "ratings": { + "Service": 3 + } + } + ] + } + } +] +---- +==== + + [[fn-obj-inner-pairs,OBJECT_INNER_PAIRS()]] == OBJECT_INNER_PAIRS(`expression`) @@ -825,23 +988,81 @@ If FALSE, only the deepest possible nested fields are returned. *Default:* `FALSE` | Boolean +| **types** + +__optional__ +| Determines whether to return field types or values. + +If TRUE, the function returns the name and type of each field. + +If FALSE, the function returns the name and value of each field. + +*Default:* `FALSE` +| Boolean + | **pattern** + __optional__ -| A regular expression used to filter the returned paths. -The pattern is matched against the composite path names, not the individual field names. +| The pattern used to filter the returned paths. + +It can be a regular expression or a simple string, depending on the `regex` parameter. | String -| **types** + +| **regex** + __optional__ -| Determines whether to return field types or values. +| If `TRUE`, the pattern is treated as a regular expression. -If TRUE, the function returns the name and type of each field. +If `FALSE`, the pattern is treated as a simple string. -If FALSE, the function returns the name and value of each field. +*Default:* `TRUE` +| Boolean + +| **patternspace** + +__optional__ +| A string literal with two possible values. + +`"field"`: The pattern is matched against individual field names. + +`"path"`: The pattern is matched against composite path names. + +*Default:* `"path"` +| String + +| **exact** + +__optional__ +| Determines whether the provided pattern must be an exact match for the field or path (as determined by the `patternspace` parameter). + +This is a short-cut for the regular expression start (^) and end ($) anchors, and can be used even when `regex` is set to `false`. + +If `TRUE`, the pattern must be an exact match. + +If `FALSE`, the pattern does not need to be an exact match. *Default:* `FALSE` | Boolean + +| **ignorecase** + +__optional__ +| If `TRUE`, the pattern matching is case-sensitive. + +If `FALSE`, the pattern matching ignores case. + +*Default:* `FALSE` +| Boolean + +| **report** + +__optional__ + +| Controls the output of the `name` field, allowing selection between the full path or the final field name. + +Possible values are: + +`"field"`: Outputs only the final field name. + +`"path"`: Outputs the full path to the field. + +*Default:* `"path"` + +| String |=== === Return Value @@ -886,7 +1107,10 @@ WITH input AS ({ SELECT OBJECT_PAIRS_NESTED(input) AS nested_pairs, OBJECT_PAIRS_NESTED(input, {"composites": true}) AS nested_pairs_comp, OBJECT_PAIRS_NESTED(input, {"pattern": "name"}) AS nested_pairs_pattern, - OBJECT_PAIRS_NESTED(input, {"types": true}) AS nested_pairs_types; + OBJECT_PAIRS_NESTED(input, {"types": true}) AS nested_pairs_types, + OBJECT_PAIRS_NESTED(input, {"pattern": "number", "patternspace":"field"}) AS filtered_fields, + OBJECT_PAIRS_NESTED(input, {"pattern": "-name$", "patternspace":"field", "regex":true}) + AS filtered_fields_regex; ---- .Results @@ -936,6 +1160,18 @@ SELECT OBJECT_PAIRS_NESTED(input) AS nested_pairs, "name": "attribute.flight-number", "type": "number" } + ], + "filtered_fields": [ + { + "name": "attribute.flight-number", + "val": 737 + } + ], + "filtered_fields_regex": [ + { + "name": "attribute.flight-name", + "val": "AI444" + } ] } ] @@ -1063,31 +1299,86 @@ A field in this context may be any attribute or element, nested at any level wit object:: An expression representing an object. -options:: [Optional] An object containing the following possible parameters: +options:: [Optional] An object containing the following possible parameters. + +=== Options + +[options="header", cols="1a,3a,1a"] +|=== +| Name | Description | Schema + +| **composites** + +__optional__ +| If `TRUE`, every level of every nested field is displayed. + +If `FALSE`, only the deepest possible nested fields are returned. + +*Default:* `TRUE` +| Boolean + +| **arraysubscript** + +__optional__ +| If `TRUE`, array subscripts are returned. + +If `FALSE`, array subscripts are replaced by `*`. -composites;; A boolean. -If `true`, every level of every nested field is displayed; if `false`, only the deepest possible nested fields are returned. -Default `true`. +*Default:* `TRUE` +| Boolean + +| **unique** + +__optional__ +| If `TRUE`, duplicate field names are collapsed to single unique field name. -arraysubscript;; A boolean. -If `true`, array subscripts are returned; if `false`, array subscripts are replaced by `*`. -Default `true`. +If `FALSE`, all duplicate field names are returned. -unique;; A boolean. -If `true`, duplicate field names are collapsed to single unique field name; if `false`, all duplicate field names are returned. Typically used when arrays are expanded and array subscripts are not returned. -Default `true`. -pattern;; A regular expression used to filter the returned paths. -Used in conjunction with the following setting. +*Default:* `TRUE` +| Boolean -patternspace;; A string literal with two possible values. -Default `"path"`. -+ -[horizontal] -`"field"`::: The pattern is matched against individual field names. +| **pattern** + +__optional__ +| A regular expression used to filter the returned paths. +Used in conjunction with the `patternspace` setting. -`"path"`::: The pattern is matched against composite path names. +| String + +| **patternspace** + +__optional__ + +| A string literal with two possible values. + +`"field"`: The pattern is matched against individual field names. + +`"path"`: The pattern is matched against composite path names. + +*Default:* `"path"` + +| String + +| **exact** + +__optional__ +| Determines whether the provided pattern must be an exact match for the field or path (as determined by the `patternspace` parameter). + +This is a short-cut for the regular expression start (^) and end ($) anchors, and can be used even when `regex` is set to `false`. + +If `TRUE`, the pattern must be an exact match. + +If `FALSE`, the pattern does not need to be an exact match. + +*Default:* `FALSE` +| Boolean + +| **ignorecase** + +__optional__ +| If `TRUE`, the pattern matching is case-sensitive. + +If `FALSE`, the pattern matching ignores case. + +*Default:* `FALSE` +| Boolean + +|=== === Return Value @@ -1179,7 +1470,7 @@ SELECT [[obj-paths-ex3,OBJECT_PATHS() Example 3]] .Pattern matching and pattern space ==== -This example searches for strings beginning with "n" in the given object paths. +This example searches for strings beginning with "n" and also fields that exactly match "name". .Query [source,sqlpp] @@ -1193,7 +1484,9 @@ SELECT OBJECT_PATHS(input, {"pattern": "^n", "patternspace": "field"}) AS field_starts_with_n, OBJECT_PATHS(input, {"pattern": "^n", "patternspace": "path"}) - AS path_starts_with_n; + AS path_starts_with_n, + OBJECT_PATHS(input, {"pattern": "name", "patternspace": "field", "exact": true}) + AS exact_field_name; ---- .Results @@ -1208,7 +1501,10 @@ SELECT "field_starts_with_n": [ "attribute.name" ], - "path_starts_with_n": [] + "path_starts_with_n": [], + "exact_field_name": [ + "attribute.name" + ] } ] ---- diff --git a/modules/n1ql/pages/n1ql-language-reference/select-syntax.adoc b/modules/n1ql/pages/n1ql-language-reference/select-syntax.adoc index d4e426eec..38e219f73 100644 --- a/modules/n1ql/pages/n1ql-language-reference/select-syntax.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/select-syntax.adoc @@ -5,6 +5,7 @@ :page-topic-type: reference :expression: xref:n1ql-language-reference/index.adoc#N1QL_Expressions +:string-expression: xref:n1ql-language-reference/literals.adoc#strings :hints: xref:n1ql-language-reference/optimizer-hints.adoc :conventions: xref:n1ql-language-reference/conventions.adoc :number: xref:n1ql-language-reference/literals.adoc#numbers @@ -81,7 +82,7 @@ image::n1ql-language-reference/alias.png["Syntax diagram", align=left] [subs="normal"] ---- -select-clause ::= 'SELECT' {hints}[hint-comment]? <> +select-clause ::= 'SELECT' {hints}[hint-comment]? <> <>? ---- image::n1ql-language-reference/select-clause.png["Syntax diagram", align=left] @@ -109,6 +110,21 @@ path ::= {identifier}[identifier] ( '[' {expression}[expr] ']' )* ( '.' {identif image::n1ql-language-reference/path.png["Syntax diagram", align=left] +[#exclude-clause,reftext="exclude-clause",subs="normal"] +---- +exclude-clause ::= 'EXCLUDE' <> ( ',' <> )* +---- + +image::n1ql-language-reference/exclude-clause.png["Syntax diagram", align=left] + +[#exclude-term,reftext="exclude-term",subs="normal"] +---- +exclude-term ::= {identifier}[identifier] | {string-expression}[string-expr] +---- +image::n1ql-language-reference/exclude-term.png["Syntax diagram", align=left] + +[#hints,reftext="hints",subs="normal"] + [[from-clause,from-clause]] == FROM Clause diff --git a/modules/n1ql/pages/n1ql-language-reference/selectclause.adoc b/modules/n1ql/pages/n1ql-language-reference/selectclause.adoc index 0080da7d4..dff382d14 100644 --- a/modules/n1ql/pages/n1ql-language-reference/selectclause.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/selectclause.adoc @@ -34,6 +34,7 @@ image::n1ql-language-reference/select-clause.png["Syntax diagram", align=left] [horizontal.compact] hint-comment:: <> icon:caret-down[] projection:: <> icon:caret-down[] +exclude-clause:: <> icon:caret-down[] [#hint-comment] === Optimizer Hints @@ -155,6 +156,47 @@ If you do not explicitly give a field an alias, it is given an _implicit alias_. An implicit or explicit alias is returned in the result set, unless you suppress it using the <>. +[#sec_ExcludeClause] +=== EXCLUDE Clause + +[source,ebnf] +---- +include::partial$grammar/dql.ebnf[tag=exclude-clause] +---- +image::n1ql-language-reference/exclude-clause.png["Syntax diagram", align=left] + +The EXCLUDE clause removes specific fields from your query's result set. + +Instead of listing every field you want to include in the SELECT statement, use EXCLUDE to specify only the ones you want to omit. +This is particularly useful when you use the star expression (`{asterisk}`) to select all fields, but want to exclude a few. + +The clause consists of one or more <>, separated by commas. + +[[exclude-term]] +==== EXCLUDE Term +[source,ebnf] +---- +include::partial$grammar/dql.ebnf[tag=exclude-term] +---- +image::n1ql-language-reference/exclude-term.png["Syntax diagram", align=left] + +An EXCLUDE term is a field that you want to exclude from the final projection. +It must exactly match the field name or alias as it appears in the projection. +Refer to <>. + +An EXCLUDE term can be: + +* An identifier, such as `hotel.name`. +* A string expression with one or more fields separated by commas, such as `"hotel.name, address"`. + +[NOTE] +==== +* If the field has an alias, you must use the alias as the term. +* When your query includes only one FROM term, fields are automatically qualified with it. +You can use the field name without the full identifier. +For example, `name` instead of `hotel.name`. +==== + [#sec_BestPractices] == Best Practices @@ -632,6 +674,52 @@ FROM hotel LIMIT 5; <.> With a select expression, you may optionally include the keyspace name; in either case, the keyspace name is not added to the results. ==== +[[ex-exclude-clause]] +.SELECT with an EXCLUDE clause +==== +.Query +[source,sqlpp] +---- +SELECT * EXCLUDE reviews,h.public_likes,"geo,description" +FROM `travel-sample`.inventory.hotel h +ORDER BY meta().id LIMIT 1; +---- + +.Results +[source,json] +---- +[ + { + "h": { + "address": "Capstone Road, ME7 3JE", + "alias": null, + "checkin": null, + "checkout": null, + "city": "Medway", + "country": "United Kingdom", + "directions": null, + "email": null, + "fax": null, + "free_breakfast": true, + "free_internet": false, + "free_parking": true, + "id": 10025, + "name": "Medway Youth Hostel", + "pets_ok": true, + "phone": "+44 870 770 5964", + "price": null, + "state": null, + "title": "Gillingham (Kent)", + "tollfree": null, + "type": "hotel", + "url": "http://www.yha.org.uk", + "vacancy": true + } + } +] +---- +==== + [#sec_RelatedLinks] == Related Links diff --git a/modules/n1ql/pages/n1ql-manage/monitoring-n1ql-query.adoc b/modules/n1ql/pages/n1ql-manage/monitoring-n1ql-query.adoc index e2ff97e69..5f14013e7 100644 --- a/modules/n1ql/pages/n1ql-manage/monitoring-n1ql-query.adoc +++ b/modules/n1ql/pages/n1ql-manage/monitoring-n1ql-query.adoc @@ -731,6 +731,7 @@ A completed request is logged if _any_ of the qualifiers are met (logical OR). `context`:: Log requests with this client context ID. `statement`:: Log requests that match the specified LIKE search pattern in the query text. `plan`:: Log requests where the specified plan field values appear in the query plan. +`errors`:: Log requests with at least this many errors. For full details, see xref:n1ql-rest-admin:index.adoc#Logging_Parameters[Logging Parameters]. diff --git a/modules/n1ql/partials/grammar/dql.ebnf b/modules/n1ql/partials/grammar/dql.ebnf index ff47759c9..0b3612d97 100644 --- a/modules/n1ql/partials/grammar/dql.ebnf +++ b/modules/n1ql/partials/grammar/dql.ebnf @@ -71,10 +71,11 @@ anchor-select ::= select /* tag::recursive-select-term[] */ recursive-select-term ::= select-term /* end::recursive-select-term[] */ + /* SELECT Clause */ /* tag::select-clause[] */ -select-clause ::= 'SELECT' hint-comment? projection +select-clause ::= 'SELECT' hint-comment? projection exclude-clause? /* end::select-clause[] */ hint-comment ::= [https://github.com/couchbaselabs/docs-devex/blob/release/8.0/modules/n1ql/partials/grammar/hints.ebnf] @@ -92,6 +93,13 @@ result-expr ::= ( path '.' )? '*' | expr ( 'AS'? alias )? path ::= identifier ( '[' expr ']' )* ( '.' identifier ( '[' expr ']' )* )* /* end::path[] */ +/* tag::exclude-clause[] */ +exclude-clause ::= 'EXCLUDE' exclude-term ( ',' exclude-term )* +/* end::exclude-clause[] */ + +/* tag::exclude-term[] */ +exclude-term ::= identifier | string-expression +/* end::exclude-term[] */ /* FROM Clause */ diff --git a/modules/n1ql/partials/grammar/n1ql.ebnf b/modules/n1ql/partials/grammar/n1ql.ebnf index 357a1a45e..938b868e9 100644 --- a/modules/n1ql/partials/grammar/n1ql.ebnf +++ b/modules/n1ql/partials/grammar/n1ql.ebnf @@ -260,7 +260,7 @@ element-expr ::= expr '[' position ']' /* end::element-expr[] */ /* tag::slice-expr[] */ -slice-expr ::= expr '[' start-expr ':' end-expr? ']' +slice-expr ::= expr '[' start-expr? ':' end-expr? ']' /* end::slice-expr[] */ start-expr ::= expr diff --git a/modules/search/examples/create-search-alias-header-global.sh b/modules/search/examples/create-search-alias-header-global.sh new file mode 100644 index 000000000..c4675aa84 --- /dev/null +++ b/modules/search/examples/create-search-alias-header-global.sh @@ -0,0 +1,3 @@ +curl -s -XPUT -H "Content-Type: application/json" \ + -u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/index/${INDEX_NAME} + -d \ \ No newline at end of file diff --git a/modules/search/examples/create-search-alias-header-scoped.sh b/modules/search/examples/create-search-alias-header-scoped.sh new file mode 100644 index 000000000..6e617764e --- /dev/null +++ b/modules/search/examples/create-search-alias-header-scoped.sh @@ -0,0 +1,3 @@ +curl -s -XPUT -H "Content-Type: application/json" \ + -u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME} + -d \ \ No newline at end of file diff --git a/modules/search/examples/create-search-alias-payload-global.sh b/modules/search/examples/create-search-alias-payload-global.sh new file mode 100644 index 000000000..7d9006fb3 --- /dev/null +++ b/modules/search/examples/create-search-alias-payload-global.sh @@ -0,0 +1,19 @@ +curl -s -XPUT -H "Content-Type: application/json" \ + -u ${CB_USERNAME}:${CB_PASSWORD} http://localhost:8094/api/index/travel-color-alias + -d \ + '{ + "name": "travel-sample-alias", + "type": "fulltext-alias", + "params": { + "targets": { + "travel-sample.inventory.landmark-content": {}, + "vector-sample.color.color-index": {} + } + }, + "sourceType": "nil", + "sourceName": "", + "sourceUUID": "", + "sourceParams": null, + "planParams": {}, + "uuid": "" + }' \ No newline at end of file diff --git a/modules/search/examples/create-search-alias-payload-scoped.sh b/modules/search/examples/create-search-alias-payload-scoped.sh new file mode 100644 index 000000000..a0ec8ee20 --- /dev/null +++ b/modules/search/examples/create-search-alias-payload-scoped.sh @@ -0,0 +1,20 @@ +curl -s -XPUT -H "Content-Type: application/json" \ + -u ${CB_USERNAME}:${CB_PASSWORD} http://localhost:8094/api/bucket/travel-sample/scope/inventory/index/travel-sample-alias + -d \ + '{ + "name": "travel-sample-alias", + "type": "fulltext-alias", + "params": { + "targets": { + "travel-sample.inventory.landmark-content": {}, + "travel-sample.inventory.hotel-reviews": {}, + "travel-sample.inventory.routes": {} + } + }, + "sourceType": "nil", + "sourceName": "", + "sourceUUID": "", + "sourceParams": null, + "planParams": {}, + "uuid": "" + }' \ No newline at end of file diff --git a/modules/search/examples/create-search-alias-response-global.json b/modules/search/examples/create-search-alias-response-global.json new file mode 100644 index 000000000..c0a7f9ce1 --- /dev/null +++ b/modules/search/examples/create-search-alias-response-global.json @@ -0,0 +1,5 @@ +{ + "status": "ok", + "name": "travel-color-alias", + "uuid": "d630f5570437ff92" +} \ No newline at end of file diff --git a/modules/search/examples/create-search-alias-response-scoped.json b/modules/search/examples/create-search-alias-response-scoped.json new file mode 100644 index 000000000..05530a2c6 --- /dev/null +++ b/modules/search/examples/create-search-alias-response-scoped.json @@ -0,0 +1,5 @@ +{ + "status": "ok", + "name": "travel-sample.inventory.travel-sample-alias", + "uuid": "7e569bdb5d3a2a83" +} \ No newline at end of file diff --git a/modules/search/examples/create-search-alias-targets-example.json b/modules/search/examples/create-search-alias-targets-example.json new file mode 100644 index 000000000..580601b0f --- /dev/null +++ b/modules/search/examples/create-search-alias-targets-example.json @@ -0,0 +1,7 @@ +"params": { + "targets": { + "travel-sample.inventory.landmark-content": {}, + "travel-sample.inventory.hotel-reviews": {}, + "travel-sample.inventory.routes": {} + } + }, \ No newline at end of file diff --git a/modules/search/pages/create-search-index-alias-rest-api.adoc b/modules/search/pages/create-search-index-alias-rest-api.adoc new file mode 100644 index 000000000..1fdacbdb3 --- /dev/null +++ b/modules/search/pages/create-search-index-alias-rest-api.adoc @@ -0,0 +1,114 @@ += Create a Search Index Alias with the REST API +:page-topic-type: guide +:page-ui-name: {ui-name} +:page-product-name: {product-name} +:description: Use the REST API to create a Search index alias. Use a Search index alias to run a Search query across multiple buckets, scopes, or Search indexes. + +[abstract] +{description} + +== Prerequisites + +* You have the Search Service enabled on a node in your cluster. +For more information about how to deploy a new node and Services on your cluster, see xref:server:manage:manage-nodes/node-management-overview.adoc[]. + +* You have created at least one Search index. +For more information, see xref:create-search-index-ui.adoc[] or xref:create-search-index-rest-api.adoc[]. + +* Your user account has the *Search Admin* role for the bucket where you want to create the alias. + +* You have installed the Couchbase command-line tool (CLI). + +* You have the hostname or IP address for the node in your cluster where you're running the Search Service. +For more information about where to find the IP address for your node, see xref:server:manage:manage-nodes/list-cluster-nodes.adoc[]. + +== Procedure + +To create a Search index alias with the REST API: + +. In your command-line tool, enter a `curl` command with the `XPUT` verb. +. Set your header content to include `"Content-Type: application/json"`. +. Enter your username, password, and the Search Service endpoint on port `8094` with the name of the index you want to create. ++ +If your alias's target Search indexes are all in the same bucket and scope, use the scoped index creation endpoint: ++ +.Scoped Index Creation Endpoint +[source,console] +---- +include::example$create-search-alias-header-scoped.sh[] +---- ++ +If your target Search indexes are in different buckets or scopes, use the global index creation endpoint: ++ +.Global Index Creation Endpoint +[source,console] +---- +include::example$create-search-alias-header-global.sh[] +---- ++ +To use SSL, use the `https` protocol in the Search Service endpoint URL and port `18094`. ++ +[NOTE] +==== +Your alias name must start with an alphabetic character (a-z or A-Z). It can only contain alphanumeric characters (a-z, A-Z, or 0-9), hyphens (-), or underscores (_). + +For Couchbase Server version 7.6 and later, if you're using the scoped endpoint, your alias name must be unique inside your selected bucket and scope. +You cannot have 2 aliases with the same name globally or inside the same bucket and scope. +==== + +. Enter the JSON payload for your Search index alias. +Your Search index alias only requires the properties from xref:search-index-params.adoc#initial[the start of a Search index JSON payload], except where otherwise noted. + +== Example: Create an Alias With Targets in the Same Bucket and Scope + +In the following example, the JSON payload creates an index alias named `travel-sample-alias`, which contains the `landmark-content`, `hotel-reviews`, and `routes` Search indexes: + +[source,console] +---- +include::example$create-search-alias-payload-scoped.sh[] +---- + +All the Search indexes in the `targets` object are in the same bucket and scope, so the REST API call uses the scoped endpoint to create a scoped alias. + +If the REST API call is successful, the Search Service returns a `200 OK` and the following JSON response: + +[source,json] +---- +include::example$create-search-alias-response-scoped.json[] +---- + +The `"uuid"` is randomly generated for each Search index alias you create. +Your own UUID might not match the value shown in the example. + +== Example: Create an Alias With Targets in Different Buckets + +In the following example, the JSON payload creates an index alias named `travel-color-alias`, which contains the `landmark-content` and `color-index` Search indexes, which are in different buckets on the cluster: + +[source,console] +---- +include::example$create-search-alias-payload-global.sh[] +---- + +The REST API call uses the global endpoint to create a global alias. + +If the REST API call is successful, the Search Service returns a `200 OK` and the following JSON response: + +[source,json] +---- +include::example$create-search-alias-response-global.json[] +---- + +The `"uuid"` is randomly generated for each Search index alias you create. +Your own UUID might not match the value shown in the example. + +== Next Steps + +After you create a Search index alias, you can xref:simple-search-rest-api.adoc[] to test your alias and Search indexes. + +If you want to edit your alias with another REST API call, include the xref:search-index-params.adoc#uuid[uuid] parameter with your alias UUID. + +You can get the UUID from the response to your first call. +You can also view the UUID from the Couchbase {page-ui-name} by selecting the alias, and clicking btn:[Edit Index]. +The UUID displays in the Index Definition Preview on the Edit Index page. + +You can also use the xref:rest-api:rest-fts-indexing.adoc[Index Definition] endpoints provided by the Search REST API. \ No newline at end of file diff --git a/modules/search/pages/index-aliases.adoc b/modules/search/pages/index-aliases.adoc index fc079a6c9..b6eb744d6 100644 --- a/modules/search/pages/index-aliases.adoc +++ b/modules/search/pages/index-aliases.adoc @@ -20,10 +20,11 @@ If you created a clone of `old-index`, then made your updates, you could replace Using a Search index alias lets you edit `old-index` without any downtime. -For more information about how to create a Search index alias, see xref:create-search-index-alias.adoc[]. +For more information about how to create a Search index alias, see xref:create-search-index-alias.adoc[] or xref:create-search-index-alias-rest-api.adoc[]. == See Also * xref:create-search-index-alias.adoc[] +* xref:create-search-index-alias-rest-api.adoc[] * xref:import-search-index.adoc[] diff --git a/modules/search/pages/search-index-params.adoc b/modules/search/pages/search-index-params.adoc index dd0635632..1bb7a1e2a 100644 --- a/modules/search/pages/search-index-params.adoc +++ b/modules/search/pages/search-index-params.adoc @@ -27,13 +27,24 @@ include::example$simple-search-index-payload.jsonc[tag=json-snippet] TIP: To view the entire JSON payload, click btn:[View]. +When you xref:create-search-index-alias-rest-api.adoc[], the properties in this section are the only properties you need to include in your alias definition. + All Search index payloads have the following properties: [cols="1,1,1,2"] |==== |Property |Type |Required? |Description -|name |String |Yes |The name of the Search index. A Search index name must be unique for each cluster. +|name |String |Yes a| + +The name of the Search index or index alias. + +For Couchbase Server version 7.6 and later, your index name must be unique inside your selected bucket and scope. +You cannot have 2 indexes with the same name inside the same bucket and scope. + +For index aliases, names must be unique within the same bucket and scope if you're using the scoped endpoint. +Global index aliases must not share a name with another alias. +For more information about Search index aliases, see xref:index-aliases.adoc[]. |type |String |Yes a| @@ -41,25 +52,33 @@ The type of index you want to create: * `fulltext-index`: Create a Search index. * `fulltext-alias`: Create an alias for a Search index. -For more information about Search index aliases, see xref:index-aliases.adoc[]. +For more information about creating Search index aliases, see xref:create-search-index-alias-rest-api.adoc[]. |[[uuid]]uuid |String |No a| -The UUID for the Search index. +The UUID for the Search index or index alias. -The Search Service automatically generates a UUID for a Search index. +The Search Service automatically generates a UUID for a Search index or index alias. -If you use an existing UUID, the Search Service updates the existing Search index. -Do not include the `uuid` property when you want to copy an index to a different cluster or create a new index. +If you use an existing UUID, the Search Service updates the existing Search index or index alias. +Do not include the `uuid` property when you want to copy an index to a different cluster or create a new index or alias. View the UUID for an existing index from the Couchbase {page-ui-name} by selecting an existing index, and clicking btn:[Edit Index]. The UUID displays in the Index Definition Preview on the Edit Index page. You can also use the xref:rest-api:rest-fts-indexing.adoc[Index Definition] endpoints provided by the Search REST API. -|sourceType |String |Yes |The `sourceType` is always `"gocbcore"`. +|sourceType |String |Yes a| + +When you create a Search index, the `sourceType` is always `"gocbcore"`. -|sourceName |String |Yes |The name of the bucket where you want to create the Search index. +When you create an index alias, the `sourceType` is always `"nil"`. + +|sourceName |String |Yes a| + +The name of the bucket where you want to create the Search index. + +You do not need to include a value for this parameter when creating an index alias. |[[sourceuuid]]sourceUUID |String |No a| @@ -69,16 +88,27 @@ The Search Service automatically finds the UUID for the bucket. Do not include the `sourceUUID` property when you want to copy an index to a different cluster, or create a new index. +You do not need to include a value for this parameter when creating an index alias. + |sourceParams |Object |No a| This object contains advanced settings for index behavior. Do not add content into this object unless instructed by Couchbase Support. -|planParams |Object |Yes |An object that sets the Search index's partitions and replications. +|planParams |Object |Yes a| + +An object that sets the Search index's partitions and replications. For more information, see <>. -|params |Object |Yes |An object that sets the Search index's type identifier, type mappings, and analyzers. +For an index alias, set this to an empty object. + +|params |Object |Yes a| + +An object that sets the Search index's type identifier, type mappings, and analyzers. + +For an index alias, this sets the target Search indexes to include in the alias. + For more information, see <>. |store |Object |No a| @@ -144,6 +174,22 @@ For more information, see <>. |mapping |Object |Yes |An object that sets the analyzers and type mappings for a Search index. For more information, see <>. +|targets |Object |Index Alias Only a| + +When creating an index alias, an object that lists each Search index you want to include in the alias. + +The `targets` object should include a named object for each Search index you want to include in the alias. +Make sure to use the scoped index name for each Search index. + +For example: + +[source,json] +---- +include::example$create-search-alias-targets-example.json[] +---- + +For more information about creating aliases, see xref:create-search-index-alias.adoc[] or xref:create-search-index-alias-rest-api.adoc[]. + |==== [#doc-config] diff --git a/modules/search/pages/simple-search-rest-api.adoc b/modules/search/pages/simple-search-rest-api.adoc index cff23762c..fa89cc964 100644 --- a/modules/search/pages/simple-search-rest-api.adoc +++ b/modules/search/pages/simple-search-rest-api.adoc @@ -15,7 +15,7 @@ For more information about how the Search Service scores documents in search res * You have the Search Service enabled on a node in your cluster. For more information about how to deploy a new node and Services on your cluster, see xref:server:manage:manage-nodes/node-management-overview.adoc[]. -* Your user account has the xref:learn:security/roles.adoc#search-admin[`Search Admin`] or xref:learn:security/roles.adoc#search-reader[`Search Reader`] role. +* Your user account has the xref:learn:security/roles.adoc#search-admin[`Search Admin`] or xref:learn:security/roles.adoc#search-reader[`Search Reader`] role for the bucket or buckets that contain the Search indexes you want to search. * You installed the Couchbase command-line tool (CLI). diff --git a/modules/search/pages/simple-search-ui.adoc b/modules/search/pages/simple-search-ui.adoc index f7263e075..d7cc93333 100644 --- a/modules/search/pages/simple-search-ui.adoc +++ b/modules/search/pages/simple-search-ui.adoc @@ -22,7 +22,7 @@ For more information about how to create a bucket, see xref:server:manage:manage + For more information about how to create a Search index, see xref:create-search-indexes.adoc[]. -* Your user account has the xref:learn:security/roles.adoc#search-admin[`Search Admin`] or xref:learn:security/roles.adoc#search-reader[`Search Reader`] role. +* Your user account has the xref:learn:security/roles.adoc#search-admin[`Search Admin`] or xref:learn:security/roles.adoc#search-reader[`Search Reader`] role for the bucket or buckets that contain the Search indexes you want to search. * You have logged in to the Couchbase {page-ui-name}. diff --git a/modules/search/partials/nav.adoc b/modules/search/partials/nav.adoc index d3ca2a51c..5573ffeab 100644 --- a/modules/search/partials/nav.adoc +++ b/modules/search/partials/nav.adoc @@ -24,6 +24,7 @@ *** xref:8.0@server:search:search-query-auto-complete-code.adoc[] ** xref:8.0@server:search:index-aliases.adoc[] *** xref:8.0@server:search:create-search-index-alias.adoc[] + *** xref:8.0@server:search:create-search-index-alias-rest-api.adoc[] ** xref:8.0@server:search:customize-index.adoc[] *** xref:8.0@server:search:set-type-identifier.adoc[] *** xref:8.0@server:search:create-type-mapping.adoc[] diff --git a/modules/vector-search/pages/run-vector-search-ui.adoc b/modules/vector-search/pages/run-vector-search-ui.adoc index 2cf5996f0..8f6cbd648 100644 --- a/modules/vector-search/pages/run-vector-search-ui.adoc +++ b/modules/vector-search/pages/run-vector-search-ui.adoc @@ -103,7 +103,7 @@ include::example$run-vector-search-long-payload-ui.jsonc[tag=partial] ==== Due to the size of the embedding vector, only part of the full query is being displayed in the documentation. -Click btn:[View on GitHub] to view and copy the entire Vector Search query payload. +Click btn:[View] to view and copy the entire Vector Search query payload. Make sure you remove the lines for `// tag::partial[]` and `// end::partial[]`. ====