(DOCSP-15799) Write Model Strategies (#154)

Author: biniona-mongodb

source/sink-connector/configuration-properties.txt

@@ -50,11 +50,14 @@ See the following categories for a list of related configuration properties:
    * - :doc:`Sink Connector Error Handling Properties </sink-connector/configuration-properties/error-handling>`
      - Specify how to respond to errors and configure the dead letter queue.
 
+   * - :doc:`Connector Post-processor Properties </sink-connector/configuration-properties/post-processors>`
+     - Specify transformations of Kafka topic data.
+
    * - :doc:`Connector Id Strategy Properties </sink-connector/configuration-properties/id-strategy>`
      - Specify how the connector generates document ids.
 
-   * - :doc:`Connector Post-processor Properties </sink-connector/configuration-properties/post-processors>`
-     - Specify transformations of Kafka topic data.
+   * - :doc:`Connector Write Model Strategy Properties </sink-connector/configuration-properties/post-processors>`
+     - Specify how the connector writes data to MongoDB.
 
    * - :doc:`Topic Override Properties </sink-connector/configuration-properties/topic-override>`
      - Override how the connector processes data on specific Kafka topics.
@@ -77,8 +80,9 @@ for more information on these settings.
    Connector Topic </sink-connector/configuration-properties/kafka-topic>
    Connector Message Processing </sink-connector/configuration-properties/connector-message>
    Connector Error Handling </sink-connector/configuration-properties/error-handling>
-   Id Strategy </sink-connector/configuration-properties/id-strategy>
    Post-processors <sink-connector/configuration-properties/post-processors>
+   Id Strategy </sink-connector/configuration-properties/id-strategy>
+   Write Model Strategy <sink-connector/configuration-properties/write-strategies>
    Topic Override <sink-connector/configuration-properties/topic-override>
    Change Data Capture <sink-connector/configuration-properties/cdc>
    Time Series <sink-connector/configuration-properties/time-series>

source/sink-connector/configuration-properties/post-processors.txt

@@ -121,7 +121,7 @@ Settings
      - | **Type:** string
        |
        | **Description:**
-       | The class that specifies the ``WriteModel`` the connector should
+       | The class that specifies the ``WriteModelStrategy`` the connector should
          use for :manual:`Bulk Writes </core/bulk-write-operations/index.html>`.
 
        .. seealso::
@@ -137,4 +137,3 @@ Settings
           com.mongodb.kafka.connect.sink.writemodel.strategy.DefaultWriteModelStrategy
 
        | **Accepted Values**: A fully qualified Java class name
-

source/sink-connector/configuration-properties/write-strategies.txt

@@ -0,0 +1,120 @@
+=====================================
+Sink Connector Write Model Strategies
+=====================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+Use the strategies in the following table to specify how the sink connector
+writes data into MongoDB. You can specify a write strategy with the following
+configuration:
+
+.. code-block:: properties
+
+   writemodel.strategy=<a writemodel strategy>
+
+.. include:: /includes/sink-config-link.rst
+
+.. _sink-connector-write-model-strategies:
+
+Strategies
+----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 75
+
+   * - Name
+     - Description
+
+   * - | **DefaultWriteModelStrategy**
+       | 
+     - | **Description:**
+       | This strategy uses the ``ReplaceOneDefaultStrategy`` by default, and the ``InsertOneDefaultStrategy`` if you set the ``timeseries.timefield`` option.
+       | 
+       | This is the default value for the ``writemodel.strategy`` configuration setting.
+
+   * - | **InsertOneDefaultStrategy**
+       | 
+     - | **Description:**
+       | Insert each sink record into MongoDB as a document. 
+       | Apply the following configuration to your sink connector to specify this setting: 
+       
+       .. code-block:: properties
+           
+          writemodel.strategy=com.mongodb.kafka.connect.sink.writemodel.strategy.InsertOneDefaultStrategy
+
+   * - | **ReplaceOneDefaultStrategy**
+       |
+     - | **Description:**
+       | Replaces at most one document in MongoDB that matches a sink record by the ``_id`` field. If no documents match, insert the sink record as a new document.
+       | Apply the following configuration to your sink connector to specify this setting: 
+       
+       .. code-block:: properties
+           
+          writemodel.strategy=com.mongodb.kafka.connect.sink.writemodel.strategy.ReplaceOneDefaultStrategy
+
+   * - | **ReplaceOneBusinessKeyStrategy**
+       | 
+     - | **Description:**
+       | Replaces at most one document that matches a sink record by a specified business key. If no documents match, insert the sink record as a new document.
+       | Apply the following configuration to your sink connector to specify this setting: 
+       
+       .. code-block:: properties
+           
+          writemodel.strategy=com.mongodb.kafka.connect.sink.writemodel.strategy.ReplaceOneBusinessKeyStrategy
+       
+       | To see an example showing how to use this strategy, see our :ref:`guide on write model strategies <kafka-sink-write-model-replace-example>`.
+   
+   * - | **DeleteOneDefaultStrategy**
+       | 
+     - | **Description:**
+       | Deletes at most one document that matches your sink connector's key structure by the ``_id`` field only when the document contains a null value structure.
+       | This is implicitly specified when you set ``mongodb.delete.on.null.values=true``.
+       | You can set this explicitly with the following configuration: 
+       
+       .. code-block:: properties
+
+          writemodel.strategy=com.mongodb.kafka.connect.sink.writemodel.strategy.DeleteOneDefaultStrategy
+
+   * - | **DeleteOneBusinessKeyStrategy**
+       | 
+     - | **Description:**
+       | Deletes at most one MongoDB document that matches a sink record by a business key.
+       | Apply the following configuration to your sink connector to specify this setting: 
+       
+       .. code-block:: properties
+           
+          writemodel.strategy=com.mongodb.kafka.connect.sink.writemodel.strategy.DeleteOneBusinessKeyStrategy
+
+       | To see an example showing how to use this strategy, see our :ref:`guide on write model strategies <kafka-sink-write-model-delete-example>`.
+
+   * - | **UpdateOneTimestampsStrategy**
+       | 
+     - | **Description:**
+       | Add ``_insertedTS`` (inserted timestamp) and ``_modifiedTS`` (modified timestamp) fields into documents.
+       | Apply the following configuration to your sink connector to specify this setting: 
+       
+       .. code-block:: properties
+           
+          writemodel.strategy=com.mongodb.kafka.connect.sink.writemodel.strategy.UpdateOneTimestampsStrategy
+
+       | To see an example showing how to use this strategy, see our :ref:`guide on write model strategies <kafka-sink-write-model-time-example>`.
+
+   * - | **UpdateOneBusinessKeyTimestampStrategy**
+       | 
+     - | **Description:**
+       | Add ``_insertedTS`` (inserted timestamp) and ``_modifiedTS`` (modified timestamp) fields into documents that match a business key.
+       | Apply the following configuration to your sink connector to specify this setting: 
+       
+       .. code-block:: properties
+           
+          writemodel.strategy=com.mongodb.kafka.connect.sink.writemodel.strategy.UpdateOneBusinessKeyTimestampStrategy

source/sink-connector/fundamentals.txt

@@ -6,7 +6,7 @@ Fundamentals
    :titlesonly:
    :maxdepth: 1
 
-   Write Strategies </sink-connector/fundamentals/write-strategies>
+   Write Model Strategies </sink-connector/fundamentals/write-strategies>
    Post-processors </sink-connector/fundamentals/post-processors>
    Data Transformations </sink-connector/fundamentals/data-transformations>
    Error Handling Strategies </sink-connector/fundamentals/error-handling-strategies>