From e1183ecb9532d359d9c6ceb46195d09aa27dc71e Mon Sep 17 00:00:00 2001 From: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> Date: Tue, 19 Nov 2024 10:55:31 -0500 Subject: [PATCH 1/7] [DOC-12001] Moving some links around to try and resolve the original complaint. (#294) * [DOC-12001] Moving some links around to try and resolve the original complaint. * [DOC-12001] Removing the extra link out after some thought. --- .../pages/create-vector-search-index-ui.adoc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/modules/vector-search/pages/create-vector-search-index-ui.adoc b/modules/vector-search/pages/create-vector-search-index-ui.adoc index 712433130..d2235a95b 100644 --- a/modules/vector-search/pages/create-vector-search-index-ui.adoc +++ b/modules/vector-search/pages/create-vector-search-index-ui.adoc @@ -53,12 +53,15 @@ You cannot have 2 indexes with the same name inside the same bucket and scope. . Expand *Customize Index*. . Select *Use non-default scope/collection(s)*. .. In the *Scope* list, select the scope that contains the documents you want to include in your index. -. Expand *Mappings* and xref:search:create-type-mapping.adoc[create a new type mapping on a collection]: +. Expand *Mappings* and create a new type mapping on a collection: .. Click btn:[Add Type Mapping]. .. In the *Collection* list, select the collection that contains the documents you want to include in your index. .. Select *Only index specified fields*. .. Click btn:[OK]. -. xref:search:create-child-field.adoc[] on the new collection type mapping with the following settings: + ++ +For more information about how to create type mappings, see xref:search:create-type-mapping.adoc[]. +. Create a child field mapping on the new collection type mapping: .. In the *Field* field, enter the name of the field in your documents that contains your vector embeddings. + Vectors must be represented as an array of floating point numbers. @@ -77,9 +80,10 @@ For more information, see xref:search:child-field-options-reference.adoc[]. For more information, see xref:search:child-field-options-reference.adoc[]. .. Select *Index*. .. Click btn:[OK]. -. (Optional) xref:search:create-child-field.adoc[Create another child field] on the new collection type mapping for any additional fields you want to return in your search results. +. (Optional) Create another child field on the new collection type mapping for any additional fields you want to return in your search results. + For example, you could add the text field that you used to generate your vector embeddings. +For more information about how to create child fields, see xref:search:create-child-field.adoc[]. . Next to the `default` dynamic type mapping, clear the checkbox. . Click btn:[Create Index]. From 1385772ae2bed10a523f1d70c55733cae5d25864 Mon Sep 17 00:00:00 2001 From: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> Date: Wed, 20 Nov 2024 11:36:34 -0500 Subject: [PATCH 2/7] [DOC-10997] Fold in information from fts-pagination to prepare for deleting the page from builds. (#298) --- .../search/pages/search-request-params.adoc | 39 +++++++++++++------ 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/modules/search/pages/search-request-params.adoc b/modules/search/pages/search-request-params.adoc index a14951e99..25ced5b3e 100644 --- a/modules/search/pages/search-request-params.adoc +++ b/modules/search/pages/search-request-params.adoc @@ -2,7 +2,7 @@ :page-topic-type: reference :page-ui-name: {ui-name} :page-product-name: {product-name} -:page-aliases: fts:fts-creating-with-curl-http-requests-json-structure.adoc, fts:fts-creating-with-curl-http-requests.adoc, fts:fts-search-request.adoc, fts:fts-supported-queries.adoc, fts:fts-supported-queries-query-string-query.adoc, fts:fts-query-string-syntax.adoc, fts:fts-query-string-syntax-boosting.adoc, fts:fts-query-string-syntax-date-ranges.adoc, fts:fts-query-string-syntax-escaping.adoc, fts:fts-query-string-syntax-field-scoping.adoc, fts:fts-query-string-syntax-match-phrase.adoc, fts:fts-query-string-syntax-match.adoc, fts:fts-query-string-syntax-numeric-ranges.adoc, fts:fts-supported-queries-analytic-query.adoc, fts:fts-supported-queries-match.adoc, fts:fts-supported-queries-match-phrase.adoc, fts:fts-supported-queries-non-analytic-query.adoc, fts:fts-supported-queries-term.adoc, fts:fts-supported-queries-phrase.adoc, fts:fts-supported-queries-prefix-query.adoc, fts:fts-supported-queries-regexp.adoc, fts:fts-supported-queries-fuzzy.adoc, fts:fts-supported-queries-wildcard.adoc, fts:fts-supported-queries-compound-query.adoc, fts:fts-supported-queries-conjuncts-disjuncts.adoc, fts:fts-supported-queries-boolean-field-query.adoc, fts:fts-supported-queries-range-query.adoc, fts:fts-supported-queries-numeric-range.adoc, fts:fts-supported-queries-date-range.adoc, fts:fts-supported-queries-term-range.adoc, fts:fts-supported-queries-geospatial.adoc, fts:fts-supported-queries-geopoint-spatial.adoc, fts:fts-supported-queries-geo-point-distance.adoc, fts:fts-supported-queries-geo-bounded-rectangle.adoc, fts:fts-supported-queries-geo-bounded-polygon.adoc, fts:fts-supported-queries-geojson-spatial.adoc, fts:fts-queryshape-point.adoc, fts:fts-queryshape-linestring.adoc, fts:fts-queryshape-polygon.adoc, fts:fts-queryshape-multipoint.adoc, fts:fts-queryshape-multilinestring.adoc, fts:fts-queryshape-multipolygon.adoc, fts:fts-queryshape-geometrycollection.adoc, fts:fts-queryshape-circle.adoc, fts:fts-queryshape-envelope.adoc, fts:fts-supported-queries-special-query.adoc, fts:fts-supported-queries-match-all.adoc, fts:fts-supported-queries-match-none.adoc +:page-aliases: fts:fts-creating-with-curl-http-requests-json-structure.adoc, fts:fts-creating-with-curl-http-requests.adoc, fts:fts-pagination.adoc, fts:fts-search-request.adoc, fts:fts-supported-queries.adoc, fts:fts-supported-queries-query-string-query.adoc, fts:fts-query-string-syntax.adoc, fts:fts-query-string-syntax-boosting.adoc, fts:fts-query-string-syntax-date-ranges.adoc, fts:fts-query-string-syntax-escaping.adoc, fts:fts-query-string-syntax-field-scoping.adoc, fts:fts-query-string-syntax-match-phrase.adoc, fts:fts-query-string-syntax-match.adoc, fts:fts-query-string-syntax-numeric-ranges.adoc, fts:fts-supported-queries-analytic-query.adoc, fts:fts-supported-queries-match.adoc, fts:fts-supported-queries-match-phrase.adoc, fts:fts-supported-queries-non-analytic-query.adoc, fts:fts-supported-queries-term.adoc, fts:fts-supported-queries-phrase.adoc, fts:fts-supported-queries-prefix-query.adoc, fts:fts-supported-queries-regexp.adoc, fts:fts-supported-queries-fuzzy.adoc, fts:fts-supported-queries-wildcard.adoc, fts:fts-supported-queries-compound-query.adoc, fts:fts-supported-queries-conjuncts-disjuncts.adoc, fts:fts-supported-queries-boolean-field-query.adoc, fts:fts-supported-queries-range-query.adoc, fts:fts-supported-queries-numeric-range.adoc, fts:fts-supported-queries-date-range.adoc, fts:fts-supported-queries-term-range.adoc, fts:fts-supported-queries-geospatial.adoc, fts:fts-supported-queries-geopoint-spatial.adoc, fts:fts-supported-queries-geo-point-distance.adoc, fts:fts-supported-queries-geo-bounded-rectangle.adoc, fts:fts-supported-queries-geo-bounded-polygon.adoc, fts:fts-supported-queries-geojson-spatial.adoc, fts:fts-queryshape-point.adoc, fts:fts-queryshape-linestring.adoc, fts:fts-queryshape-polygon.adoc, fts:fts-queryshape-multipoint.adoc, fts:fts-queryshape-multilinestring.adoc, fts:fts-queryshape-multipolygon.adoc, fts:fts-queryshape-geometrycollection.adoc, fts:fts-queryshape-circle.adoc, fts:fts-queryshape-envelope.adoc, fts:fts-supported-queries-special-query.adoc, fts:fts-supported-queries-match-all.adoc, fts:fts-supported-queries-match-none.adoc :description: You can add additional properties to a Search request to control how the Search Service returns results. :page-toclevels: 3 @@ -49,6 +49,9 @@ Set the total number of results to return for a single page of search results. If you provide both the `size` and `limit` properties, the Search Service uses the `size` value. +If you do not provide a `from`, `size`, or other pagination settings in your query, the Search Service defaults to a `size` value of `10` and a `from` value of `0`. +This means the Search Service does not offset results, and returns the first `10` matches to your query. + |from/offset |Integer |No a| Set an offset value to change where pagination starts for search results, based on the Search query's <>. @@ -57,6 +60,9 @@ For example, if you set a `size` value of `5` and a `from` value of `10`, the Se If you provide both the `from` and `offset` properties, the Search Service uses the `from` value. +If you do not provide a `from`, `size`, or other pagination settings in your query, the Search Service defaults to a `size` value of `10` and a `from` value of `0`. +This means the Search Service does not offset results, and returns the first `10` matches to your query. + |highlight |Object |No a| Contains properties to control search result highlighting. @@ -87,9 +93,10 @@ To create an explanation for a search result's score in search results, set `exp To turn off explanations for search result scoring, set `explain` to `false`. -|sort |Array |No a| +|[[sort-array]]sort |Array |No a| -Contains an array of strings or JSON objects to set how to sort search results. +Contains an array of strings or JSON objects to set how to sort search results. +By default, the Search Service sorts results based on score values, from highest to lowest. The strings can be: @@ -116,29 +123,37 @@ To turn on document relevancy scoring in search results, remove the `score` prop |search_after |Array |No a| -NOTE: If you use `search_after` in a search request, you can't use `search_before`. Both properties are included in the example code to show the correct syntax. +NOTE: If you use `search_after` in a search request, you cannot use `search_before`. Both properties are included in the example code to show the correct syntax. Use `search_after` with `from/offset` and `sort` to control pagination in search results. -Give a value for each string or JSON object in the `sort` array to the `search_after` array. +For example, if you had a set of 10 documents to sort based on `_id` values of 1-10, with `from` set to `2` and `search_after` set to `8`, documents 9-10 appear on the same page. + +You must give a value for each string or JSON object in the `sort` array to the `search_after` array. The Search Service starts search result pagination after the document with those values. -You must provide the values in the same order that they appear in the `sort` array. +You must provide the values in the same order that they appear in the `sort` array. +Your `sort` array must force a total order on your search results. -For example, if you had a set of 10 documents to sort based on `_id` values of 1-10, with `from` set to `2` and `search_after` set to `8`, documents 9-10 appear on the same page. +Use `search_after` to make the memory requirements of deeper page searches more manageable, when compared to using only `from/offset`. +`search_after` lets you start your search results from a specific result, rather than needing to process a number of search results to skip. |search_before |Array |No a| -NOTE: If you use `search_before` in a search request, you can't use `search_after`. Both properties are included in the example code to show the correct syntax. +NOTE: If you use `search_before` in a search request, you cannot use `search_after`. Both properties are included in the example code to show the correct syntax. Use `search_before` with `from/offset` and `sort` to control pagination in search results. -Give a value for each string or JSON object in the `sort` array to the `search_before` array. +For example, if you had a set of 10 documents to sort based on `_id` values of 1-10, with `from` set to `2` and `search_before` set to `8`, documents 2-6 appear on the same page. + +You must give a value for each string or JSON object in the `sort` array to the `search_before` array. The Search Service starts search result pagination before the document with those values. -You must provide the values in the same order that they appear in the `sort` array. +You must provide the values in the same order that they appear in the `sort` array. +Your `sort` array must force a total order on your search results. -For example, if you had a set of 10 documents to sort based on `_id` values of 1-10, with `from` set to `2` and `search_before` set to `8`, documents 2-6 appear on the same page. +Use `search_before` to make the memory requirements of deeper page searches more manageable, when compared to using only `from/offset`. +`search_before` lets you start your search results back from a specific result, rather than needing to process a number of search results to skip. |[[collections]]collections |Array |No |Contains an array of strings that specify the collections where you want to run the query. @@ -2126,6 +2141,8 @@ The following `sort` object orders search results by the values in `field1`, the include::example$run-search-full-request.jsonc[tag=sort] ---- +TIP: For the best results with sorting and page navigation in search results, always include your document ID values (`_id` or `-_id`) as the final sort criteria in your `sort` object. + The `sort` object can contain the following string values: [cols="1,2"] From 769559ea2fa29718f8cfc19675df7978fd276735 Mon Sep 17 00:00:00 2001 From: Ray Offiah <77050471+RayOffiah@users.noreply.github.com> Date: Mon, 25 Nov 2024 10:23:33 +0000 Subject: [PATCH 3/7] [DOC-12618]: Feedback on Language Constructs | Couchbase Docs (#292) Corrected grammar. Added `crc_go_iso` function. --- .../pages/eventing-language-constructs.adoc | 61 ++++++++++++++----- 1 file changed, 46 insertions(+), 15 deletions(-) diff --git a/modules/eventing/pages/eventing-language-constructs.adoc b/modules/eventing/pages/eventing-language-constructs.adoc index fd0ad878e..b20d16b30 100644 --- a/modules/eventing/pages/eventing-language-constructs.adoc +++ b/modules/eventing/pages/eventing-language-constructs.adoc @@ -52,7 +52,7 @@ Replaces any existing value with the specified key. This operation throws an exception if the underlying bucket SET operation fails with an unexpected error. |DELETE -|`operator[]` appears afer the JavaScript delete keyword. +|`operator[]` appears after the JavaScript delete keyword. Deletes the provided key from the KV bucket that the variable is bound to. Returns a no-op if the object does not exist. @@ -109,7 +109,7 @@ These operations are accessible through the returned iterable handle. {sqlpp} Query results, through the SELECT operation, are streamed in batches to the iterable handle as the iteration progresses through the result set. NOTE: To avoid recursion, an Eventing Function can listen for mutations in a bucket. -{sqlpp} DML statements canot manipulate documents in that same bucket. +{sqlpp} DML statements cannot manipulate documents in that same bucket. To work around this, you can use the exposed data service KV map in your Eventing Function. The following Function has a feed boundary of *Everything*, which means the same {sqlpp} statement is executed 7,303 times. @@ -196,7 +196,7 @@ To include comments in multiline statements, use `/* this format */` instead. The following features are not supported by Eventing Functions: -* <> +* <> * <> * <> * <> @@ -227,7 +227,7 @@ For example, a Constant alias of `debug` with a value of `true` or `false` behav Eventing Functions do not support asynchronous flows. Asynchrony creates a node-specific, long-running state that prevents persistence providers from capturing the entire state. -This limits Eventing Functions to execute short-running, straight-line code without sleep and wakeups. +This limits Eventing Functions to executing short-running, straight-line code without sleep and wake-ups. You can use Timers to add limited asynchrony back into your Function. Timers are designed specifically to prevent a state from being node-specific. @@ -267,6 +267,7 @@ Eventing Functions support the following built-in functions: * <> * <> * <> +* <> * <> * <> * <> @@ -290,7 +291,7 @@ The `N1QL()` function contains the following parameters: |The identified {sqlpp} statement. This is passed to {sqlpp} through SDK to run as a prepared statement. -All of the JavaScript variables referenced in the statement using the `$` notation are treated as named parameters. +All the JavaScript variables referenced in the statement using the `$` notation are treated as named parameters. |`params` a|Can be a JavaScript array or a JavaScript map object. @@ -378,7 +379,8 @@ The `close()` method on the iterable handle can throw an exception if the underl === `ANALYTICS()` ifeval::['{page-component-version}' == '7.6'] -_(Introduced in Couchbase Server 7.6)_ + +[.status]#Introduced in Couchbase Server 7.6# endif::[] The `ANALYTICS()` function provides integration with {sqlpp} Analytics directly from the Eventing Service. @@ -434,7 +436,7 @@ The `crc64()` function takes the object to checksum as its only parameter. The parameter can be any JavaScript object that can be encoded to JSON. The function returns the hash as a string. -The hash is sensitive to the order of the parameters in case of map objects. +The hash is sensitive to the order of the parameters in the case of map objects. If multiple Eventing Functions share the same `crc64` checksum documents as the Sync Gateway, real mutations can be suppressed and missed. To prevent this from happening, you can make the checksum documents unique to each Eventing Function. @@ -468,12 +470,41 @@ function OnUpdate(doc, meta) { // Business logic goes in here } ---- +.Translating strings +[NOTE] +==== +Bear in mind that using `crc64()` to convert strings will include any quotation marks as part of the conversion. +If you want to translate the string [.underline]#without# including the enclosing quotes, then use the <> instead. + +This does not apply to any other data type (e.g., numeric data or JSON data types). +==== + +[#crc_64_go_iso_call] +=== `crc_64_go_iso()` + +ifeval::['{page-component-version}' == '7.6'] +[.status]#Introduced in Couchbase Server 7.6# +endif::[] + +`crc_64_go_iso()` performs the same function as <>, but does not include the enclosing quotation marks from the parameter in the translation if its parameter type is `string`. + +Other datatypes work the same as the `crc64()` call. + + +[source,javascript] +---- +function OnUpdate(doc, meta) { + var crc_iso_str = couchbase.crc_64_go_iso(doc); + /// Code goes here +} +---- + [#base64_call] === `base64()` ifeval::['{page-component-version}' == '7.6'] -_(Introduced in Couchbase Server 7.6.2)_ +[.status]#Introduced in Couchbase Server 7.6# endif::[] The `base64()` functions let you pack large-dimensional arrays of floats as base64 encoded strings when you use the Eventing Service to generate vector embeddings. @@ -486,7 +517,7 @@ The following `base64()` functions are available: [source,javascript] ---- function OnUpdate(doc, meta) { - var base_str = base64Encode(doc); + var base_str = couchbase.base64Encode(doc); /// Code goes here } ---- @@ -496,20 +527,20 @@ function OnUpdate(doc, meta) { [source,javascript] ---- function OnUpdate(doc, meta) { - var base_str = base64Decode(doc); + var base_str = couchbase.base64Decode(doc); /// Code goes here } ---- + -* `base64Float32ArrayEncode()`, which takes a float32 number array and returns a base64 string. -* `base64Float32ArrayDecode()`, which takes a base64 encoded string and returns a float32 number array. -* `base64Float64ArrayEncode()`, which takes a float64 number array and returns a base64 string. -* `base64Float64ArrayDecode()`, which takes a base64 encoded string and returns a float64 number array. +* `couchbase.base64Float32ArrayEncode()`, which takes a float32 number array and returns a base64 string. +* `couchbase.base64Float32ArrayDecode()`, which takes a base64 encoded string and returns a float32 number array. +* `couchbase.base64Float64ArrayEncode()`, which takes a float64 number array and returns a base64 string. +* `couchbase.base64Float64ArrayDecode()`, which takes a base64 encoded string and returns a float64 number array. [#timers_general] === `createTimer()` and `cancelTimer()` -Timers are asynchronous compute. +Timers are asynchronously computed. They allow Eventing Functions to execute in reference to wall-clock events. [#createtimer_call] From b6721b7470aa91675ee9625820e622f227de5c6a Mon Sep 17 00:00:00 2001 From: Simon Dew <39966290+simon-dew@users.noreply.github.com> Date: Mon, 25 Nov 2024 15:41:54 +0000 Subject: [PATCH 4/7] DOC-12533: Feedback on Language Constructs (#297) * Update Analytics function name and example * Let AsciiDoc generate link text where possible * Prevent awkward line break in the page ToC * Updates after review * Beautify JavaScript example --- .../pages/eventing-language-constructs.adoc | 87 ++++++++----------- 1 file changed, 38 insertions(+), 49 deletions(-) diff --git a/modules/eventing/pages/eventing-language-constructs.adoc b/modules/eventing/pages/eventing-language-constructs.adoc index b20d16b30..432d45ce3 100644 --- a/modules/eventing/pages/eventing-language-constructs.adoc +++ b/modules/eventing/pages/eventing-language-constructs.adoc @@ -15,10 +15,10 @@ Certain capabilities have been removed and are not supported in order to handle Eventing Functions support the following features: -* <> -* <> -* <> -* <> +* <> +* <> +* <> +* <> [#basic_bucket_accessors] === Basic Keyspace Accessors @@ -77,7 +77,7 @@ function OnUpdate(doc, meta) { Advanced Keyspace Accessors expose a larger set of options and operators than <>. They have non-trivial argument sets and return values. -See xref:eventing-advanced-keyspace-accessors.adoc[Advanced Keyspace Accessors] for more details. +See xref:eventing-advanced-keyspace-accessors.adoc[] for more details. [#logging] === Logging @@ -196,10 +196,10 @@ To include comments in multiline statements, use `/* this format */` instead. The following features are not supported by Eventing Functions: -* <> -* <> -* <> -* <> +* <> +* <> +* <> +* <> [#global-state] === Global State @@ -264,13 +264,13 @@ The Eventing Service does not support importing libraries into Eventing Function Eventing Functions support the following built-in functions: -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> [#n1ql_call] === `N1QL()` @@ -376,14 +376,13 @@ The `close()` method on the iterable handle can throw an exception if the underl |=== [#analytics_call] -=== `ANALYTICS()` +=== `couchbase.{zwsp}analyticsQuery({wj})` ifeval::['{page-component-version}' == '7.6'] - [.status]#Introduced in Couchbase Server 7.6# endif::[] -The `ANALYTICS()` function provides integration with {sqlpp} Analytics directly from the Eventing Service. +The `couchbase.analyticsQuery()` function provides integration with {sqlpp} Analytics directly from the Eventing Service. Integrating Eventing with Analytics: @@ -391,38 +390,28 @@ Integrating Eventing with Analytics: * Simplifies Eventing code logic and improves code readability * Eliminates security and network latency issues with the `curl()` function +The following example assumes that the Analytics collection (dataset) called `default` already exists. + [source,javascript] ---- function OnUpdate(doc, meta) { - // Ignore information we don't care about - if (doc.type !== 'airline') return; - - // Get the total routes per IATA - var route_cnt = 0; - // Uses a true variable as a SQL++ parameter - var airline = doc.iata; - - var results = ANALYTICS( - "SELECT COUNT(*) AS cnt - FROM `travel-sample`.`inventory`.`route` - WHERE type = \"route\" - AND airline = $1", [doc.iata] - ); - - // Stream results using the 'for' iterator - for (var item of results) { - route_cnt = item.cnt; + var count = 0; + const limit = 4; + + let query = couchbase.analyticsQuery('SELECT * FROM default LIMIT $limit;', { + "limit": limit + }); + for (let row of query) { + ++count; } - // End the query and free the resources held - results.close(); - - // Log the KEY, AIRLINE and ROUTE_CNT - log("key: " + meta.id + ", airline: " + doc.iata + ", route_cnt: " + route_cnt); + if (count === limit) { + dst_bucket[meta.id] = 'yes'; + } } ---- -For more information about {sqlpp} Analytics, see xref:server:analytics:1_intro.adoc[What’s SQL++ for Analytics?]. +For more information about {sqlpp} Analytics, see xref:server:analytics:1_intro.adoc[]. [#crc64_call] === `crc64()` @@ -556,14 +545,14 @@ To cancel a Timer, you can do one of the following: * Call the `createTimer()` function again using a reference from the existing Timer you want to cancel. * Call the `cancelTimer()` function using `cancelTimer(callback, reference)`. -For more information about Timers, see xref:eventing-timers.adoc[Timers]. +For more information about Timers, see xref:eventing-timers.adoc[]. [#curl_call] === `curl()` The `curl()` function lets you interact with external entities through a REST endpoint from Eventing Functions, using either HTTP or HTTPS. -For more information about the `curl()` function, see xref:eventing-curl-spec.adoc[cURL]. +For more information about the `curl()` function, see xref:eventing-curl-spec.adoc[]. [#handler-signatures] @@ -571,9 +560,9 @@ For more information about the `curl()` function, see xref:eventing-curl-spec.ad The Eventing Service calls the following JavaScript functions on events like mutations and fired Timers: -* <> -* <> -* <> +* <> +* <> +* <> [#onupdate_handler] === OnUpdate Handler @@ -662,7 +651,7 @@ function OnUpdate(doc, meta) { } ---- -For more information about Timers, see xref:eventing-timers.adoc[Timers]. +For more information about Timers, see xref:eventing-timers.adoc[]. == Reserved Words From 8594188ee07b900a10dfd8a49d0ebe0a50057384 Mon Sep 17 00:00:00 2001 From: Simon Dew <39966290+simon-dew@users.noreply.github.com> Date: Mon, 25 Nov 2024 15:53:32 +0000 Subject: [PATCH 5/7] DOC-12533: Feedback on Language Constructs (#300) Revert changes to "Introduced in Couchbase Server 7.6" messages --- modules/eventing/pages/eventing-language-constructs.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/eventing/pages/eventing-language-constructs.adoc b/modules/eventing/pages/eventing-language-constructs.adoc index 432d45ce3..0b8675bc8 100644 --- a/modules/eventing/pages/eventing-language-constructs.adoc +++ b/modules/eventing/pages/eventing-language-constructs.adoc @@ -379,7 +379,7 @@ The `close()` method on the iterable handle can throw an exception if the underl === `couchbase.{zwsp}analyticsQuery({wj})` ifeval::['{page-component-version}' == '7.6'] -[.status]#Introduced in Couchbase Server 7.6# +_(Introduced in Couchbase Server 7.6)_ endif::[] The `couchbase.analyticsQuery()` function provides integration with {sqlpp} Analytics directly from the Eventing Service. @@ -472,7 +472,7 @@ This does not apply to any other data type (e.g., numeric data or JSON data type === `crc_64_go_iso()` ifeval::['{page-component-version}' == '7.6'] -[.status]#Introduced in Couchbase Server 7.6# +_(Introduced in Couchbase Server 7.6)_ endif::[] `crc_64_go_iso()` performs the same function as <>, but does not include the enclosing quotation marks from the parameter in the translation if its parameter type is `string`. @@ -493,7 +493,7 @@ function OnUpdate(doc, meta) { === `base64()` ifeval::['{page-component-version}' == '7.6'] -[.status]#Introduced in Couchbase Server 7.6# +_(Introduced in Couchbase Server 7.6)_ endif::[] The `base64()` functions let you pack large-dimensional arrays of floats as base64 encoded strings when you use the Eventing Service to generate vector embeddings. From 2ffcdf8f86db66fc9f05170122c8000097ad4ca9 Mon Sep 17 00:00:00 2001 From: sarahlwelton <110928505+sarahlwelton@users.noreply.github.com> Date: Wed, 27 Nov 2024 14:27:46 -0500 Subject: [PATCH 6/7] [DOC-12252] Add tip with links to other SDK examples (#283) * [DOC-12252] Add tip with links to other SDK examples * [DOC-12252] Changing formatting of SDK list per peer review --- modules/vector-search/pages/run-vector-search-sdk.adoc | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/modules/vector-search/pages/run-vector-search-sdk.adoc b/modules/vector-search/pages/run-vector-search-sdk.adoc index fb64a9bb9..3778ddaa7 100644 --- a/modules/vector-search/pages/run-vector-search-sdk.adoc +++ b/modules/vector-search/pages/run-vector-search-sdk.adoc @@ -11,6 +11,16 @@ For more information about how the Search Service scores documents in search results, see xref:search:run-searches.adoc#scoring[Scoring for Search Queries]. +[TIP] +==== +Not all available Couchbase SDK languages are covered by the examples on this page. + +For additional Vector Search examples, see the SDK documentation: + +xref:dotnet-sdk:howtos:full-text-searching-with-sdk.adoc#vector-search[.NET] | xref:cxx-sdk:howtos:vector-searching-with-sdk.adoc[C++] | xref:kotlin-sdk:howtos:full-text-search.adoc#vector-search[Kotlin] | xref:nodejs-sdk:howtos:full-text-searching-with-sdk.adoc#vector-search[Node.js] | xref:php-sdk:howtos:full-text-searching-with-sdk.adoc#vector-search[PHP] | xref:ruby-sdk:howtos:full-text-searching-with-sdk.adoc#vector-search[Ruby] | xref:scala-sdk:howtos:vector-searching-with-sdk.adoc[Scala] + +==== + == Prerequisites Choose your preferred programming language to view the applicable prerequisites for the examples on this page. From 4f8b5f8f9369180edd5724870b1011ff9a62dc12 Mon Sep 17 00:00:00 2001 From: Simon Dew <39966290+simon-dew@users.noreply.github.com> Date: Fri, 29 Nov 2024 23:17:54 +0000 Subject: [PATCH 7/7] DOC-12776: Delete legacy Eventing REST API page (#301) --- modules/eventing/pages/eventing-api.adoc | 951 ----------------------- 1 file changed, 951 deletions(-) delete mode 100644 modules/eventing/pages/eventing-api.adoc diff --git a/modules/eventing/pages/eventing-api.adoc b/modules/eventing/pages/eventing-api.adoc deleted file mode 100644 index c3dee7336..000000000 --- a/modules/eventing/pages/eventing-api.adoc +++ /dev/null @@ -1,951 +0,0 @@ -= Eventing REST API -:description: The Eventing REST API, available by default at port 8096, provides the methods available to work with and manipulate Couchbase Eventing Functions. -:page-edition: Enterprise Edition - -[abstract] -{description} - -NOTE: Changes to the Eventing Function definition files made outside of this REST API or the interactive UI are only supported for version 7.0 (and above) if the Eventing schemas located in https://github.com/couchbase/eventing/tree/master/parser are adhered to. - -As of version 7.1 Eventing now supports full xref:eventing-rbac.adoc[Eventing Role-Based Access Control] (RBAC). - -If the sample REST API shows two forms: - -* The first format is for privileged Eventing functions with a "Function Scope" of *+*+.+*+*; these functions can only be made or managed by users with the "Full Admin", "Eventing Full Admin" role. -In addition this is the default "Function Scope" for all functions after an upgrade from a prior version. -The creditionals for these examples will be "Administrator:password". - -* The second format uses RBAC and you must pass the parameters *bucket=[fs_bucket]&scope=[fs_scope]* to specify the *bucket* and the *scope* of the "Function Scope" to the REST call. In addition, due to the use or *&* and *?* characters, you will need to quote your REST call on the command line. -The creditionals for these examples will be "anyAuthedUser:password" (although "Administrator:password" can also use this form). - -If the sample REST API shows just a single format, then the REST API call does not require the parameters *bucket=[fs_bucket]&scope=[fs_scope]* and the action is fully determined by the *username* and *password* credentials passed to the REST call. - -.Eventing Functions API (basic activation/deactivation) -[cols="2,10,18"] -|=== -| HTTP Method | *URI Path* | *Description* - -| POST -| [.path]_/api/v1/functions/[function_name]/deploy_ -a| -Deploys an undeployed Function. Starting with version 6.5.0, this is the preferred invocation. -A deploy CURL example is provided for reference. - -| -2+a| -Sample API: -[source,console] ----- -curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/deploy ----- -[source,console] ----- -curl -XPOST 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/deploy?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| POST -| [.path]_/api/v1/functions/[function_name]/undeploy_ -a| -Undeploys a Function. Starting with version 6.5.0, this is the preferred invocation. -An undeploy CURL example is provided for reference. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/undeploy ----- -[source,console] ----- -curl -XPOST 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/undeploy?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| POST -| [.path]_/api/v1/functions/[function_name]/pause_ -a| -Pauses a Function and creates a DCP checkpoint such that on a subsequent resume no mutations will be lost. Starting with version 6.5.0, this is the preferred invocation. -A pause CURL example is provided for reference. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/pause ----- -[source,console] ----- -curl -XPOST 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/pause?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| POST -| [.path]_/api/v1/functions/[function_name]/resume_ -a| -Resumes a paused function from its paused DCP checkpoint. Starting with version 6.5.0, this is the preferred invocation. -A resume CURL example is provided for reference. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/resume ----- -[source,console] ----- -curl -XPOST 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/resume?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -|=== - - -.Eventing Functions API (advanced) -[cols="2,10,18"] -|=== -| HTTP Method | *URI Path* | *Description* - -| POST -| [.path]_/api/v1/functions/[function_name]_ -a| Import or create a single Function. -The Function name in the body must match that on the URL. -Function definition includes current settings. -The POST data or POST data file must be a single JSON object or an array containing a single JSON object - -| -2+a| -Sample API (from file): - -[source,console] ----- -curl -XPOST -d @./[function_name].json http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name] ----- -[source,console] ----- -curl -XPOST -d @./[function_name].json 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| POST -| [.path]_/api/v1/functions/_ -a| Imports or creates multiple Functions. -Function names must be unique. -When multiple Functions have the same name, an error is reported. -The POST data or POST data file must be either a single JSON object or an array containing a one or more JSON objects - -| -2+a| -Sample API (from file): - -[source,console] ----- -curl -XPOST -d @./[array_of_functions].json http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions ----- - -| POST -| [.path]_/api/v1/import/_ -a| Imports multiple Functions. -Function names must be unique. -When multiple Functions have the same name, an error is reported. -The POST data or POST data file must be either a single JSON object or an array containing a one or more JSON objects -Note if any Function's language_compatibility field is missing the value will be set to 6.0.0 (unlike the [.path]_/api/v1/functions_ above which will set the value to the highest version supported by the server). - -| -2+a| -Sample API (from file): - -[source,console] ----- -curl -XPOST -d @./[array_of_functions].json http://anyAuthedUser:password@192.168.1.5:8096/api/v1/import ----- - -| GET -| [.path]_/api/v1/functions/[function_name]_ -a| View a definition of a Function. -Provides a listing of a complete Function definition available in the cluster. -The Function could be in any state: deployed, undeployed, or paused. -If saved to a file the function definition can be imported into the cluster or a different cluster. -However any changes to the function definition made to the file outside the UI are discouraged. - -| -2+a| -Sample API (to standard out): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name] ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| -2+a| -Sample API (to file): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name] -o [function_name].json ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]?bucket=[fs_bucket]&scope=[fs_scope]' -o [function_name].json ----- - -| GET -| [.path]_/api/v1/functions_ -a| View definitions of all Functions. -Provides an array of definitions of all Functions available in the cluster. -The Functions could be in any state: deployed, undeployed, or paused. -If saved to a file the function definitions can be imported into the cluster or a different cluster. -However any changes to the function definition made to the file outside the UI are discouraged. - -If this API is run as a non-Administrator the return set will be filtered via RBAC to just the "Function Scopes" the user has access too. -| -2+a| -Sample API (to standard out): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions ----- - -| -2+a| -Sample API (to file): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions -o array_of_functions.json ----- - -| GET -| [.path]_/api/v1/export_ -a| This is a convenience method to export all function definitions. -Exported functions are always set to undeployed state at the time of export, regardless of the state in the cluster at time of export. -If saved to a file the function definitions can be imputed into the cluster or a different cluster. -However any changes to the function definition made to the file outside the UI are discouraged. - -If this API is run as a non-Administrator the return set will be filtered via RBAC to just the "Function Scopes" the user has access too. -| -2+a| -Sample API (to standard out): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/export ----- - -| -2+a| -Sample API (to file): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/export -o array_of_functions.json ----- - -| DELETE -| [.path]_/api/v1/functions/[function_name]_ -a| Deletes a specific Function from the cluster. -WARNING: Use this API with caution as it is irreversible. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XDELETE http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name] ----- -[source,console] ----- -curl -XDELETE 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| DELETE -| [.path]_/api/v1/functions_ -a| Deletes multiple Functions (*as in all Functions*) from the cluster. -WARNING: Use this API with caution as it is irreversible. - -If this API is run as a non-Administrator the deleted set will be filtered via RBAC to just the "Function Scopes" the user has access too. -| -2+a| -Sample API: - -[source,console] ----- -curl -XDELETE http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions ----- - -| GET -| [.path]_/api/v1/functions/[function_name]/settings_ -a| -Export or return the full definition for one Eventing Function in the cluster. The definition can be subsequently imported. -However any changes to the function definition made to the file outside the UI are discouraged. - -| -2+a| -Sample API (to standard out): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings ----- - -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| -2+a| -Sample API (to file): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings -o [function_name].json ----- - -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings?bucket=[fs_bucket]&scope=[fs_scope]' -o [function_name].json ----- - -| POST -| [.path]_/api/v1/functions/[function_name]/settings_ -a| -Updates an undeployed or paused function with the provided setting. -Note settings can only be altered when the function is paused or undeployed, attempting to adjust a deployed function will result in an error. -During an edit, settings provided are merged. Unspecified attributes retain their prior values. -Note that you must always specify *deployment_status* (deployed/undeployed) and *processing_status* (paused/not-paused) when using this REST endpoint to update any option or set of options. - -The current values of *deployment_status* and *processing_status* can be queried via _api/v1/status_ or _api/v1/status/[function_name]_ - -By adjusting *deployment_status* and *processing_status* this command can also deploy or resume a function, however it cannot pause or undeploy a function. - -| -2+a| -Sample API (alter worker_count): - -[source,console] ----- -curl -XPOST -d '{"deployment_status":false,"processing_status":false,"worker_count":6}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings ----- -[source,console] ----- -curl -XPOST -d '{"deployment_status":false,"processing_status":false,"worker_count":6}' 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| -2+a| -Sample API (alter app_log_max_files and app_log_max_size) _this function is currently undeployed_: - -[source,console] ----- -curl -XPOST -d '{"deployment_status":false,"processing_status":false,"app_log_max_files":5,"app_log_max_size":10485760}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings ----- -[source,console] ----- -curl -XPOST -d '{"deployment_status":false,"processing_status":false,"app_log_max_files":5,"app_log_max_size":10485760}' 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| -2+a| -Sample API (alter timer_context_size) _this function is currently paused_: - -[source,console] ----- -curl -XPOST -d '{"deployment_status":true,"processing_status":false,"timer_context_size":2048}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings ----- -[source,console] ----- -curl -XPOST -d '{"deployment_status":true,"processing_status":false,"timer_context_size":2048}' 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| -2+a| -Sample API (alter worker_count AND resume) _this function is currently paused_: - -[source,console] ----- -curl -XPOST -d '{"deployment_status":true,"processing_status":true,"worker_count":8}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings ----- -[source,console] ----- -curl -XPOST -d '{"deployment_status":true,"processing_status":true,"worker_count":8}' 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings?bucket=[fs_bucket]&scope=[fs_scope]' ----- - - -| GET -| [.path]_/api/v1/functions/[function_name]/config_ -a| -Export or return the configuration of the source keyspace and the eventing storage (metadata) keyspace for one Eventing Function in the cluster. The definition can be subsequently imported. -However any changes to the function definition made to the file outside the UI are discouraged. - -| -2+a| -Sample API (to standard out): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/config ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/config?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| -2+a| -Sample API (to file): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/config -o [function_name].json ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/config?bucket=[fs_bucket]&scope=[fs_scope]' -o [function_name].json ----- - -| POST -| [.path]_/api/v1/functions/[function_name]/config_ -a| -Import the configuration and alter the source keyspace and the eventing storage (metadata) keyspace for one Eventing Function in the cluster. -You can only change these values if a function is in the undeployed state and the two keyspaces exist. - -| -2+a| -Sample API (alter source and eventing storage keyspaces): - -[source,console] ----- -curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/config -d '{ "source_bucket": "bulk", "cust01": "orders", "source_collection": "customer01", "metadata_bucket": "rr100", "metadata_scope": "eventing", "metadata_collection": "metadata" }' ----- -[source,console] ----- -curl -XPOST 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/config?bucket=[fs_bucket]&scope=[fs_scope]' -d '{ "source_bucket": "bulk", "cust01": "orders", "source_collection": "customer01", "metadata_bucket": "rr100", "metadata_scope": "eventing", "metadata_collection": "metadata" }' ----- - -| -2+a| -Sample API (alter source and eventing storage keyspaces from a file): - -[source,console] ----- -curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/config -d @./[function_name].json ----- -[source,console] ----- -curl -XPOST 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/config?bucket=[fs_bucket]&scope=[fs_scope]' -d @./[function_name].json ----- - -| GET -| [.path]_/api/v1/functions/[function_name]/appcode_ -a| Export only the JavaScript code for one Eventing Function in the cluster. -Note the JavaScript is not escaped (unlike /api/v1/functions/[function_name]) and the code is runnable in other environments. -The JavaScript code can be subsequently imported. -However any changes to the function definition made to the file outside the UI are discouraged. - -| -2+a| -Sample API (to standard out): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/appcode ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/appcode?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| -2+a| -Sample API (to file): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/appcode -o [function_name].json ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/appcode?bucket=[fs_bucket]&scope=[fs_scope]' -o [function_name].json ----- - -| POST -| [.path]_/api/v1/functions/[function_name]/appcode_ -a| Import only the JavaScript code for one Eventing Function in the cluster. -Note the JavaScript supplied is not escaped (unlike /api/v1/functions/[function_name]) and could come from other environments. -It is highly recommended that you use the flag *--data-binary* or *--upload-file* when importing your JavaScript "appcode" fragments -to avoid potential encoding issues due to string escaping. - -| -2+a| -Sample API (import and replace JavaScript): - -[source,console] ----- -curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/appcode --data-binary 'function OnUpdate(doc, meta) { log("id",meta.id); }' ----- -[source,console] ----- -curl -XPOST 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/appcode?bucket=[fs_bucket]&scope=[fs_scope]' --data-binary 'function OnUpdate(doc, meta) { log("id",meta.id); }' ----- - -| -2+a| -Sample API (import and replace JavaScript from a file, do not use *-d*): - -[source,console] ----- -curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/import --data-binary @./[function_name].json ----- -[source,console] ----- -curl -XPOST 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/import?bucket=[fs_bucket]&scope=[fs_scope]' --data-binary @./[function_name].json ----- - -or - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/import --upload-file ./[function_name].json ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/import?bucket=[fs_bucket]&scope=[fs_scope]' --upload-file ./[function_name].json ----- - -|=== - - -.Eventing Status API (advanced) -[cols="2,10,18"] -|=== -| HTTP Method | *URI Path* | *Description* - -| GET -| [.path]_/api/v1/status_ -a| -Returns a list (array) of all Eventing Functions showing their corresponding *composite_status*. -A Function's status can have one of the following values - _undeployed_, _deploying_, _deployed_, _undeploying_, _paused_, and '_pausing_. -Note, there is no value of _resuming_ when resuming a paused Eventing Function the *composite_status* will return _deploying_ until it reaches the _deployed_ state. - -If this API is run as a non-Administrator the return set will be filtered via RBAC to just the "Function Scopes" the user has access too. -| -2+a| -Sample API (status): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/status ----- - -| GET -| [.path]_/api/v1/status/[function_name]_ -a| -Returns a specific Eventing Functions showing its corresponding *composite_status*. -It can have one of the following values - _undeployed_, _deploying_, _deployed_, _undeploying_, _paused_, and '_pausing_. -Note, there is no value of _resuming_ when resuming a paused Eventing Function the *composite_status* will return _deploying_ until it reaches the _deployed_ state. - -| -2+a| -Sample API (status): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/status/[function_name] ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/status/[function_name]?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -|=== - - -.Eventing Log API (advanced) -[cols="2,10,18"] -|=== -| HTTP Method | *URI Path* | *Description* - -| GET -| [.path]_/getAppLog?name=[function_name]_ -a| -Returns the most recent application log messages for a specific Eventing Function. - -This API by default accesses a single Eventing node but can access all Eventing nodes by setting the optional parameter *aggregate=true*. - -By default the amount of logging information returned is approximately 40960 bytes unless you specify the optional size parameter *size=#* where # is in bytes. Note when specifying the *size* parameter and fetching from more than one Eventing node only *size/#nodes* bytes are returned from each node. - -| -2+a| -Sample API (fetch recent Application log info from one Eventing node): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/getAppLog?name=[function_name] ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/getAppLog?name=[function_name]&bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| -2+a| -Sample API (fetch recent Application log info from all Eventing nodes): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/getAppLog?name=[function_name]&aggregate=true ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/getAppLog?name=[function_name]&aggregate=true&bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| -2+a| -Sample API (fetch recent Application log info from all Eventing nodes but limited to 2048 bytes): - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/getAppLog?name=[function_name]&aggregate=true&size=2048 ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/getAppLog?name=[function_name]&aggregate=true&size=2048&bucket=[fs_bucket]&scope=[fs_scope]' ----- - -|=== - -.Eventing List API (advanced) -[cols="2,10,18"] -|=== -| HTTP Method | *URI Path* | *Description* - -| GET -| [.path]_/api/v1/list/functions_ -a| -Returns a list (array) of the names of all Eventing Functions in the cluster. -The returned list can also be filtered by the following: *deployed* status _true_ or _false_ (in this case paused is considered deployed), -*source_bucket* filter by the bucket with the listen to keyspace, and *function_type* _notsbm_ or _sbm_ (the later if the functions that modifies its own listen to keyspace). - -If this API is run as a non-Administrator the return set will be filtered via RBAC to just the "Function Scopes" the user has access too. -| -2+a| -Sample API (list): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/list/functions ----- - -| GET -| [.path]_/api/v1/list/functions/query?deployed=true_ -a| -Returns a list (array) of the names of all deployed (or paused) Eventing Functions in the cluster. -Note, if we had specified _deployed=false_ we would get all undeployed functions. - -If this API is run as a non-Administrator the return set will be filtered via RBAC to just the "Function Scopes" the user has access too. -| -2+a| -Sample API (status): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/list/functions/query?deployed=true ----- - -| GET -| [.path]_/api/v1/list/functions/query?source_bucket=[bucket_name]_ -a| -Returns a list (array) of the names of Eventing Functions in the cluster that have a source keyspace under a particular bucket. - -If this API is run as a non-Administrator the return set will be filtered via RBAC to just the "Function Scopes" the user has access too. -| -2+a| -Sample API (status): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/list/functions/query?source_bucket=[bucket_name] ----- - -| GET -| [.path]_/api/v1/list/functions/query?function_type=sbm_ -a| -Returns a list (array) of the names of Eventing Functions in the cluster that modify their own a source keyspace. - -If this API is run as a non-Administrator the return set will be filtered via RBAC to just the "Function Scopes" the user has access too. -| -2+a| -Sample API (status): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/list/functions/query?function_type=sbm ----- - -| GET -| [.path]_/api/v1/list/functions/query?function_type=notsbm_ -a| -Returns a list (array) of the names of Eventing Functions in the cluster that *do not* modify their own a source keyspace. - -If this API is run as a non-Administrator the return set will be filtered via RBAC to just the "Function Scopes" the user has access too. -| -2+a| -Sample API (status): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/list/functions/query?function_type=notsbm ----- - -|=== - -.Eventing Global Config API (advanced) -[cols="2,10,18"] -|=== -| HTTP Method | *URI Path* | *Description* - -| GET -| [.path]_/api/v1/config_ -a| List global configuration. -The response shows all global Eventing settings. There are currently just two settings: -*enable_debugger* (default value of false) and *ram_quota* (default value of 256 MB). -Both of these settings can also be adjusted via the UI. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/config ----- - -| POST -| [.path]_/api/v1/config_ -a| Modify global configuration. -During an edit, settings provided are merged. Unspecified attributes retain their prior values. -The response indicates whether the Eventing service must be restarted for the new changes to take effect. - -| -2+a| -Sample API (alter ram_quota): - -[source,console] ----- -curl -XPOST -d '{"ram_quota": 512}' http://Administrator:password@192.168.1.5:8096/api/v1/config ----- - -| -2+a| -Sample API (alter enable_debugger): - -[source,console] ----- -curl -XPOST -d '{"enable_debugger": true}' http://Administrator:password@192.168.1.5:8096/api/v1/config ----- - -| -2+a| -Sample API (allow interbucket recursion): - -Note, setting the value of "allow_interbucket_recursion" to true is highly discouraged unless you have an advanced use case and follow strict non-production coding and verification. This will disable the safety checks that prevent running basic infinite recursive Eventing Functions - -[source,console] ----- -curl -X POST -u Administrator:password http://192.168.1.5:8091/_p/event/api/v1/config -d '{"allow_interbucket_recursion":true}' ----- - -| -2+a| -Sample API (disallow interbucket recursion): - -This is the default setting of which applies some sanity checks to disable running basic infinite recursive Eventing Functions. - -[source,console] ----- -curl -X POST -u Administrator:password http://192.168.1.5:8091/_p/event/api/v1/config -d '{"allow_interbucket_recursion":false}' ----- - -|=== - - -.Eventing Statistics API -[cols="2,10,18"] -|=== -| HTTP Method | *URI Path* | *Description* - -| GET -| [.path]_/api/v1/stats?type=full_ -a| Retrieve all statistics for the node. -This will return the full statistics set inclusive of events processing, events remaining, execution, failure, latency, worker PIDs and sequence processed. - -If this API is run as a non-Administrator the return set will be filtered via RBAC to just the "Function Scopes" the user has access too. -| -2+a| -NOTE: Omitting the parameter `type=full` will exclude `dcp_event_backlog_per_vb`, `doc_timer_debug_stats`, `latency_stats`, `plasma_stats`, and `seqs_processed` from the response. - -| -2+a| -Sample API (basic): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/stats ----- - -| -2+a| -Sample API (full): - -[source,console] ----- -curl -XGET http://anyAuthedUser:password@192.168.1.5:8096/api/v1/stats?type=full ----- - -| GET -| [.path]_/getExecutionStats?name=[function_name]_ -a| Retrieve only execution statistics. -This will return the subset of statistics for the node. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/getExecutionStats?name=[function_name] ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/getExecutionStats?name=[function_name]&bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| GET -| [.path]_/getLatencyStats?name=[function_name]_ -a| Retrieve only latency statistics. -This will return the subset of statistics for the node. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/getLatencyStats?name=[function_name] ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/getLatencyStats?name=[function_name]&bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| GET -| [.path]_/getFailureStats?name=[function_name]_ -a| Retrieve only failure statistics. -This will return the subset of statistics for the node. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/getFailureStats?name=[function_name] ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/getFailureStats?name=[function_name]&bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| GET -| [.path]_/resetStatsCounters?name=[function_name]_ -a| Resets statistics for the provided Eventing Function. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XGET http://Administrator:password@192.168.1.5:8096/resetStatsCounters?appName=[function_name] ----- -[source,console] ----- -curl -XGET 'http://anyAuthedUser:password@192.168.1.5:8096/resetStatsCounters?appName=[function_name]&bucket=[fs_bucket]&scope=[fs_scope]' ----- - -|=== - -.Eventing Functions API (*deprecated activation/deactivation*) -[cols="2,10,18"] -|=== -| HTTP Method | *URI Path* | *Description* - -| POST -| [.path]_/api/v1/functions/[function_name]/settings_ -a| -Deploys an undeployed Function or resumes a paused function from its paused DCP checkpoint. Deprecated, see (basic activation/deactivation) for preferred invocation. -A deploy/resume CURL example is provided for reference. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XPOST -d '{"deployment_status":true,"processing_status":true}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings ----- -[source,console] ----- -curl -XPOST -d '{"deployment_status":true,"processing_status":true}' 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| POST -| [.path]_/api/v1/functions/[function_name]/settings_ -a| -Undeploys a Function. Deprecated, see (basic activation/deactivation) for preferred invocation. -An undeploy CURL example is provided for reference. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XPOST -d '{"deployment_status":false,"processing_status":false}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings ----- -[source,console] ----- -curl -XPOST -d '{"deployment_status":false,"processing_status":false}' 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -| POST -| [.path]_/api/v1/functions/[function_name]/settings_ -a| -Pauses a Function and creates a DCP checkpoint such that on a subsequent resume no mutations will be lost. -Deprecated, see (basic activation/deactivation) for preferred invocation. -A pause CURL example is provided for reference. - -| -2+a| -Sample API: - -[source,console] ----- -curl -XPOST -d '{"deployment_status":true,"processing_status":false}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings ----- -[source,console] ----- -curl -XPOST -d '{"deployment_status":true,"processing_status":false}' 'http://anyAuthedUser:password@192.168.1.5:8096/api/v1/functions/[function_name]/settings?bucket=[fs_bucket]&scope=[fs_scope]' ----- - -|=== \ No newline at end of file