Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Create Documents After Expiration

  • Capella Operational
    March 23, 2025
    + 12
    When a document in an existing collection is about to expire, use the Eventing Service to create a new document in a different collection.

    The OnUpdate JavaScript handler listens to mutations or data changes within a specified source collection. The Eventing Function calls a Timer, which executes a callback function before a document expires and retrieves a value from that document. This function then stores a document with the same key in a specified target collection.

    The original document in the source collection does not change when its value is copied. The document is then deleted folowing the bucket’s expiration date.

    Prerequisites

    Before trying out the examples on this page, you must first:

    • Create two buckets called bulk and rr100 with a minimum size of 100MB.

    • Inside the bulk bucket, create two keyspaces called bulk.data.source and bulk.data.target.

    • Inside the rr100 bucket, create one keyspace called rr100.eventing.metadata.

    For more information about creating buckets, scopes, and collections, see Manage Buckets.

    Do not add, modify, or delete documents in the Eventing storage keyspace rr100.eventing.metadata while your Eventing Functions are in a deployed state.

    Example: Create a New Document When a Document Expires

    This example walks you through how to create a new document whenever another document expires.

    Create a New Document

    You can create a test document with an expiration time in one of the following ways:

    • Using a SQL++ statement in the Query Workbench

    • Using the command line KV client (cbc)

    • Using a Python or Java SDK script

    To use a SQL++ statement in the Query Workbench:

    1. Go to Data Tools  Query.

    2. For the Query Context, select bulk as the bucket and data as the scope.

    3. In the code editor, enter the following query:

    sql++
    Copy
    UPSERT INTO `bulk`.`data`.`source` (KEY, VALUE) VALUES ("SampleDocument2", {"a_key":"a_value"}, {"expiration":600});

    For information about setting a document’s expiration time with SQL++, see Insert a document with expiration.

    You now have a document in the source collection with a set expiration date. This document is deleted after 600 seconds.

    Create an Eventing Function

    To create a new Eventing Function:

    1. Go to Data Tools  Eventing.

    2. Click Add Function.

    3. In the Settings page, enter the following Function settings:

      • add_timer_before_expiry under Name.

      • Fire a Timer before a document expires. under Description.

      • The keyspace bulk.data.source under Listen to Location.

      • The keyspace rr100.eventing.metadata under Eventing Storage.

    4. Click Next.

    5. In the Bindings page, click Add Binding and create two bindings.

      • For the first binding:

        • Select Bucket.

        • Enter src as the Alias Name.

        • Enter the keyspace bulk.data.source under Bucket, Scope, and Collection.

        • Select Read Only under Permission.

      • For the second binding:

        • Select Bucket.

        • Enter tgt as the Alias Name.

        • Enter the keyspace bulk.data.target under Bucket, Scope, and Collection.

        • Select Read and Write under Permission.

    6. Click Next.

    7. In the code editor, replace the placeholder JavaScript code with the following code sample:

      javascript
      Copy
      function OnUpdate(doc, meta) {
    // Only processes for those documents that have a non-zero TTL
    if (meta.expiration == 0 ) return;
    // Gets the TTL and computes 2 minutes prior to the TTL. JavaScript Date() takes msec.
    var twoMinsPrior = new Date((meta.expiration - 2*60) * 1000);
    // Creates a context and then creates a timer with the context
    var context = { docID : meta.id, expiration : meta.expiration };
    createTimer(DocTimerCallback, twoMinsPrior , meta.id, context);
    log('OnUpdate add Timer 2 min. prior to TTL to DocId:',  meta.id);
}
function DocTimerCallback(context) {
    log('DocTimerCallback 1 on DocId:', String(context.docID));
    // Creates a new document with the same ID, but in the target collection
    tgt[context.docID] = "To Be Expired in 2 min., Key's Value is:" + JSON.stringify(src[context.docID]);
    log('DocTimerCallback 2 src expiry:', new Date(context.expiration  * 1000));
    log('DocTimerCallback 3 tgt archive via Key:', String(context.docID));
}

    8. Click Create function to create your Eventing Function.

    The OnUpdate handler creates a Timer that fires 2 minutes before the document’s expiration time.

    Deploy the Eventing Function

    Deploy your Eventing Function:

    1. Go to Data Tools  Eventing.

    2. Click More Options (⋮) next to add_timer_before_expiry.

    3. Click Deploy to deploy your Function.

    After it’s deployed, the Eventing Function executes on all existing documents and any documents you create in the future.

    Check the Eventing Function Log

    To check the Eventing Function log:

    1. Go to Data Tools  Eventing.

    2. Click the Log icon next to the add_timer_before_expiry Eventing Function. You should see the line "OnUpdate add Timer 2 min. prior to TTL to DocId:" "SampleDocument2".

    Wait a few minutes and check the Eventing Function log again. The Timer has fired and executed the DocTimerCallback function 2 minutes before the TTL was scheduled. You should see the following lines in the log:

    2024-05-07T21:01:15.386+00:00 [INFO] "DocTimerCallback 3 tgt archive via Key:" "SampleDocument2"
2024-05-07T21:01:15.386+00:00 [INFO] "DocTimerCallback 2 src expiry:" "2024-05-07T21:02:05.000Z"
2024-05-07T21:01:15.236+00:00 [INFO] "DocTimerCallback 1 on DocId:" "SampleDocument2"
2024-05-07T21:01:06.821+00:00 [INFO] "OnUpdate add Timer 2 min. prior to TTL to DocId:" "SampleDocument2"
    The document had an expiration time of 600 seconds, or 10 minutes. The DocTimerCallback function fires a Timer 2 minutes before the initial expiration time.

    The final result is a new document named SourceDocument2 which contains a copy of the data from the original document. This new document is written to the target collection.

    The original document in the source collection is deleted after it reaches its expiration time of 10 minutes. The new document in the target collection is not deleted.