From 1c59555f6d90fa2aa7b56234c2442ab33a69c994 Mon Sep 17 00:00:00 2001 From: "mahesh.nagaraj" Date: Thu, 6 Sep 2018 23:34:00 +0530 Subject: [PATCH 1/2] Timers-edit: Edits from PMs feedback --- content/eventing/eventing-Terminologies.dita | 7 - .../eventing/eventing-adding-function.dita | 8 +- content/eventing/eventing-examples.dita | 109 -------------- content/eventing/eventing-faq.dita | 16 -- .../eventing-language-constructs.dita | 141 +++++------------- .../troubleshooting-best-practices.dita | 20 --- 6 files changed, 41 insertions(+), 260 deletions(-) diff --git a/content/eventing/eventing-Terminologies.dita b/content/eventing/eventing-Terminologies.dita index 42c763642b..7523b0a25c 100644 --- a/content/eventing/eventing-Terminologies.dita +++ b/content/eventing/eventing-Terminologies.dita @@ -124,12 +124,5 @@ code implementing the Function, all processing checkpoints, and other artifacts in the metadata provider are purged. Before deleting, make sure you have undeployed the Function. -
- Timers -

Timers provide execution of code at a preconfigured clock time or after a specified number - of seconds. Using timers, you can write a simple JavaScript Function handler code to delay - or trigger the execution of a Function at specific wall-clock time events. Timers allow - archiving of expired documents at a preconfigured clock time.

-
diff --git a/content/eventing/eventing-adding-function.dita b/content/eventing/eventing-adding-function.dita index 6d9af92201..efd1145bdd 100644 --- a/content/eventing/eventing-adding-function.dita +++ b/content/eventing/eventing-adding-function.dita @@ -28,8 +28,6 @@ Source Bucket

The name of a bucket currently defined on the cluster.

-

For more information on Source Bucket, refer to .

 @@ -96,9 +94,9 @@
  • Click Deploy. This displays the Confirm Deploy Function dialog. The Feed Boundary determines whether documents previously in existence needs to be included in the Function's activities: the options are Everything and From now. The - Everything option invokes a Function on all the data present in the cluster. The - From now option invokes a Function during future instances of data mutation, post - Function deployment.
    • + Everything option invokes a Function on all data mutations. The From now + option invokes a Function during future instances of data mutation, post Function + deployment.
  • Click Deploy Function. This deploys the Function and returns you to the main Eventing screen. The display indicates that the Function is now deployed and running. From this point, your defined Function will run, first, on all existing documents; and diff --git a/content/eventing/eventing-examples.dita b/content/eventing/eventing-examples.dita index 39f047d3de..22a0a63e94 100644 --- a/content/eventing/eventing-examples.dita +++ b/content/eventing/eventing-examples.dita @@ -374,115 +374,6 @@ function OnDelete(meta) {

    • -
    Example 4

    Goal: When a - document in an existing bucket is about to expire, a new document is created in a newly - created bucket.

    Implementation: Write an OnUpdate handler, which runs - whenever a document is created or mutated. The handler calls a timer routine, which executes a - callback function, two minutes prior to any document’s established expiration. This function - retrieves a specified value from the document, and stores it in a document of the same name, - in a specified target bucket. The original document in the source bucket is not changed.. -

    For this example, the buckets created such as source, target, and metadata buckets, are - used. A new document is created within the source bucket, and this document has its - expiration — or Time To Live (TTL) — set to occur ten minutes after the document's creation. -

    Python script for this Example is provided for reference. Using the Couchbase SDK, - you can create or modify the document expiration. In this example, the Couchbase SDK Python - client creates a document and sets the document's expiration. -

    from couchbase.cluster import Cluster -from couchbase.cluster import PasswordAuthenticator -import time -cluster = Cluster('couchbase://localhost:8091') -authenticator = PasswordAuthenticator('Administrator', 'password') -cluster.authenticate(authenticator) - -cb = cluster.open_bucket('source') -cb.upsert('SampleDocument2', {'a_key': 'a_value'}) -cb.touch('SampleDocument2', ttl=10*60)

    The - script imports a Couchbase cluster object, and authenticates against it, using (for - demonstration purposes) the Full Administrator username and password (the cluster is assumed - to be accessible on localhost). The script then opens the existing source bucket, and - inserts a new document, named SampleDocument2, whose body is {'a_key': - 'a_value'}.

    For information on installing the Couchbase Python SDK, refer - to Start Using the - SDK. For information on using the Couchbase Python SDK to establish - bucket-expiration, refer to Document - Operations.

    Procedure

    Proceed as follows:

      -
    1. Install the Couchbase SDK Python client and from the appropriate folder, start - Python../python
      2. -
    2. On the Python prompt, enter the provided - code.>>> from couchbase.cluster import Cluster ->>> from couchbase.cluster import PasswordAuthenticator ->>> import time ->>> cluster = Cluster('couchbase://localhost:8091') ->>> authenticator = PasswordAuthenticator('Administrator', 'password') ->>> cluster.authenticate(authenticator) ->>> cb = cluster.open_bucket('source') ->>> cb.upsert('SampleDocument2', {'a_key': 'a_value'}) -OperationResult<rc=0x0, key='SampleDocument2', cas=0x1519ec8cdee90000> ->>> cb.touch('SampleDocument2', ttl=10*60) -OperationResult<rc=0x0, key='SampleDocument2', cas=0x1519ec8e686c0000> ->>>
      3. -
    3. To verify bucket creation, access the Buckets screen from the Couchbase Web - Console and click the Document tab of the Source bucket. The new - document gets displayed.
      4. -
    4. [Optional Step] Click on a document's id to view the metadata information.
      5. -
    5. From the Couchbase Web Console > Eventing page, click ADD FUNCTION, - to add a new Function. The ADD FUNCTION dialog appears.
      6. -
    6. In the ADD FUNCTION dialog, for individual Function elements provide the below - information:
        -
      • For the Source Bucket drop-down, select source.
        • -
      • For the Metadata Bucket drop-down, select metadata.
        • -
      • Enter add_timer_before_expiry as the name of the Function you are creating in - the FunctionName text-box.
        • -
      • Enter text Function that adds timer before document expiry, in the - Description text-box.
        • -
      • For the Settings option, use the default values.
        • -
      • For the Bindings option, add two bindings. For the first binding specify - source as the name of the bucket, and specify src as the associated - value. For the second binding, specify target as the name of the bucket, and - specify tgt as the associated value.
        • -
      7. -
    7. After providing all the required information in the ADD FUNCTION dialog, click - Next: Add Code. The add_timer_before_expiry dialog appears.
      8. -
    8. The add_timer_before_expiry dialog initially contains a placeholder code block. - You will substitute your actual add_timer_before_expiry code in this block. -

      9. -
    9. Copy the following Function, and paste it in the placeholder code block of - add_timer_before_expiry dialog.

      function OnUpdate(doc, meta) { - if (meta.expiration > 0 ) //do only for those documents that have a non-zero TTL - { - var expiry = new Date(meta.expiration); - // Compute 2 minutes from the TTL timestamp - var twoMinsPrior = new Date(expiry.setMinutes(expiry.getMinutes()-2)); - var context = {docID : meta.id}; - createTimer(DocTimerCallback, twoMinsPrior , meta.id, context); - log('Added Doc Timer to DocId:', meta.id); - } -} -function DocTimerCallback(context) - { - log('DocTimerCallback Executed for DocId:', String(context.docID)); - tgt[context.docID] = "To Be Expired Key's Value is:" + JSON.stringify(src[context.docID]); - log('Doc Timer Executed for DocId', String(context.docID)); - }

      After pasting, the screen appears as displayed below:

      10. -
    10. Click Save.
      11. -
    11. To return to the Eventing screen, click Eventing tab.
      12. -
    12. From the Eventing screen, click Deploy.
      13. -
    13. In the Confirm Deploy Function dialog, select Everything from the Feed - boundary option.
      14. -
    14. Click Deploy. The function is deployed and starts running within a few seconds. -

      As a result, a new document — like the original, named - SourceDocument2 — is created, with a value based on that of the original. After - two minutes has elapsed, check the documents within the source bucket: the original - SourceDocument2 is no longer visible, having been removed at its defined - expiration-time.

      15. -
    diff --git a/content/eventing/eventing-faq.dita b/content/eventing/eventing-faq.dita index 728b3a8b23..5222439238 100644 --- a/content/eventing/eventing-faq.dita +++ b/content/eventing/eventing-faq.dita @@ -165,22 +165,6 @@

    We block one of the mutations alone and hand it over to the debugger session. The rest of the mutations continue to be serviced by the event handler.

    -
  • Are timers scalable?

    Timers get automatically sharded across Eventing nodes and - therefore are elastically scalable. Due to sharding, triggering of timers at or after a - specified time interval is guaranteed. However, triggering of timers may either be on - the same node where the time was created, or on a different node. Relative ordering - between two specific timers cannot be maintained.

    • -
  • -

    Can I use Debugger to debug timers?

    -

    Timers cannot be debugged using the Visual Debugger.

    -
    • -
  • What happens when the Function handler code contains a timestamp in the past?

    When a - Function handler code contains a timestamp in the past, upon a successful Function - deployment, the system executes the code in the next available time slot.

    • -
  • What is the Timer behavior post reboot?

    During a boot operation, all clocks in the - cluster nodes get synchronized. Post-startup, cluster nodes get periodically - synchronized using clock synchronization tools such as Network Time Protocol (NTP). -

    • diff --git a/content/eventing/eventing-language-constructs.dita b/content/eventing/eventing-language-constructs.dita index 70b2025f9d..d4c5977495 100644 --- a/content/eventing/eventing-language-constructs.dita +++ b/content/eventing/eventing-language-constructs.dita @@ -72,9 +72,10 @@ function OnUpdate(doc, meta) { according to the rules of the named-parameter substitution in the N1QL grammar specification.

    - The N1QL construct is still in development and may have some + The N1QL queries in events are a BETA feature and may have some rough edges and bugs, and may change significantly before the final GA release. This - release version of Couchbase Server 5.5 is intended for development purposes only. + Beta-release version of Couchbase Server 5.5 is intended for development purposes only; no + Enterprise Support is provided for Beta features.

    The iterator is an input iterator (elements are read-only). The keyword this cannot be used in the body of the iterator. The variables created inside the iterator @@ -91,6 +92,41 @@ function OnUpdate(doc, meta) { } +

    The Function handler code supports N1QL queries. Top level N1QL keywords, such as + SELECT, UPDATE, and INSERT, are available as keywords in Functions.

    +

    During deployment, if a handler code includes an N1QL query, then the system + generates a warning message. Warning Message: "Handler <function_name> uses + Beta features. Do not use in production environments."However, the warning + message does not prevent the Function deployment.

    +

    You must use $<variable>, as per N1QL specification, to use a + JavaScript variable in the query statement. The object expressions for substitution are not + supported and therefore you cannot use the meta.id expression in the + query statement.

    +

    Instead of meta.id expression, you can use var id = + meta.id in an N1QL query.

    +

    +

    +

    +

    When you use a N1QL query inside a Function handler, remember to use an escaped + identifier for bucket names with special characters (`bucket-name`). + Escaped identifiers are surrounded by backticks and support all identifiers in JSON

    +

    For example:

    +
    Handler Signatures

    The Eventing Service supports two event-handlers:

    • OnUpdate Handler
      • @@ -215,106 +251,5 @@ function OnUpdate(doc, meta) {

      Reserved words as a property bindings value

    -
    - <b>Support for N1QL in Function Handlers</b> -

    - The N1QL queries in events are a BETA feature and may have some rough - edges and bugs, and may change significantly before the final GA release. This - Beta-release version of Couchbase Server 5.5 is intended for development purposes only; no - Enterprise Support is provided for Beta features. -

    -

    The Function handler code supports N1QL queries. Top level N1QL keywords, such as - SELECT, UPDATE, and INSERT, are available as keywords in Functions.

    -

    During deployment, if a handler code includes an N1QL query, then the system - generates a warning message. Warning Message: "Handler <function_name> uses Beta features. Do not - use in production environments."However, the warning message does not prevent - the Function deployment.

    - -

    You must use $<variable>, as per N1QL specification, to use - a JavaScript variable in the query statement. The object expressions for substitution are - not supported and therefore you cannot use the meta.id expression in - the query statement.

    -

    Instead of meta.id expression, you can use var id = - meta.id in an N1QL query.

    -

    -

      -
    • Invalid N1QL query - DELETE FROM `transactions` WHERE username = $meta.id;
      • -
    • Valid N1QL query - var id = meta.id; -DELETE FROM `transactions` WHERE username = $id;
      • -
    -

    -

    When you use a N1QL query inside a Function handler, remember to use an escaped - identifier for bucket names with special characters (`bucket-name`). - Escaped identifiers are surrounded by backticks and support all identifiers in JSON

    -

    For example:

    -
      -
    • -

      If the bucket name is beer-sample, then use the N1QL - query such as: SELECT * FROM `beer-sample` WHERE type...

      -
      • -
    • -

      If bucket name is beersample, then use the N1QL query - such as: SELECT * FROM beersample WHERE type ...

      -
      • -
    -
    -
    - Timers -

    Creating a Timer

    -

    To create a timer use the below - syntax:createTimer(callback, timestamp, reference, context)

    -
    -

    In the createTimer syntax:

    -

    -

    -

    -

    A sample createTimer language construct is provided for reference. - createTimer(DocTimerCallback, twoMinsPrior, meta.id, context)

    -

    In the sample construct:

    -

    -

    -

    -

    A few ascpects related to timer construct are listed below:

    -

    -

    -

    diff --git a/content/eventing/troubleshooting-best-practices.dita b/content/eventing/troubleshooting-best-practices.dita index 5e35281db1..496ccb6730 100644 --- a/content/eventing/troubleshooting-best-practices.dita +++ b/content/eventing/troubleshooting-best-practices.dita @@ -98,25 +98,5 @@ options. This way you can monitor, debug and troubleshoot errors during the Function execution.

    -
    - What are a few best practices while passing timer related timestamps? -

    Perform a timestamp check to avoid triggering of timers during the stale-time period.

    -

    To handle delays during Function backlogs, in the Function handler code, you can program - some additional time to allow triggering of timers. If this additional time period is also - breached, then the time status is considered as stale-time. If your business logic is - time-sensitive, then the Function handler code should refrain from triggering of timers - during this stale-time period.

    -

    The following code snippet ensures a valid timestamp check is performed before the Function - handler code gets executed. - func callback(context) -{ - //context.my_deadline is the parameter in the timer payload - if new Date().getTime() > context.my_deadline - { - // timestamp is back-dated, do not execute the rest of the timer - return; - } -}

    -
    From 5f47862fd7801861405c13a68f5300edf5bf098e Mon Sep 17 00:00:00 2001 From: "mahesh.nagaraj" Date: Fri, 7 Sep 2018 02:20:05 +0530 Subject: [PATCH 2/2] Timer-edit:Removed export functions page --- content/eventing/eventing-api.dita | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/eventing/eventing-api.dita b/content/eventing/eventing-api.dita index dbb8a32790..cd92ce9dc9 100644 --- a/content/eventing/eventing-api.dita +++ b/content/eventing/eventing-api.dita @@ -5,6 +5,10 @@ The Functions REST API, available by default at port 8096, provides the methods available to work with Couchbase Functions. +

    + The Functions REST API is a Beta feature intended for development purposes only, do not + use them in production; no Enterprise Support is provided for Beta features. +