Couchbase

The Couchbase destination writes data to Couchbase Server. Couchbase Server is a distributed NoSQL document-oriented database. For information about supported versions, see Supported Systems and Versions in the Data Collector documentation.

The destination writes each record to a document in an existing bucket in the Couchbase database. Each Couchbase document has a unique ID or key that identifies the document. You specify the key for the document where the destination writes each record. You can configure the destination to use the compare and swap (CAS) value to detect conflicts with other processes before writing a record.

The Couchbase destination can use CRUD operations defined in the sdc.operation.type record header attribute to write data. You can define a default operation for records without the header attribute or value. You can also configure how to handle records with unsupported operations. For information about Data Collector change data processing and a list of CDC-enabled origins, see Processing Changed Data.

When you configure the Couchbase destination, you enter connection information, such as the nodes and bucket to connect to, as well as timeout properties for the connection. Optionally, you can enable TLS for the connection. You also enter information to authenticate with Couchbase Server.

CRUD Operation Processing

The Couchbase destination can insert, update, delete, or upsert data. The destination writes the records based on the CRUD operation defined in a CRUD operation header attribute or in operation-related stage properties.

The destination uses the header attribute and stage properties as follows:

CRUD operation header attribute
The destination looks for the CRUD operation in the sdc.operation.type record header attribute.
The attribute can contain one of the following numeric values:
  • 1 for INSERT
  • 2 for DELETE
  • 3 for UPDATE
  • 4 for UPSERT
If your pipeline has a CRUD-enabled origin that processes changed data, the destination simply reads the operation type from the sdc.operation.type header attribute that the origin generates. If your pipeline has a non-CDC origin, you can use the Expression Evaluator processor or a scripting processor to define the record header attribute. For more information about Data Collector changed data processing and a list of CDC-enabled origins, see Processing Changed Data.
Operation stage properties
If there is no CRUD operation in the sdc.operation.type record header attribute, the destination uses the operation configured in the Default Write Operation property.
If the sdc.operation.type record header attribute contains an unsupported value, the destination takes the action configured in the Unsupported Operation Handling property. The destination can discard the record, send the record for error handling, or write the record using the default operation.

Compare and Swap

You can configure the Couchbase destination to use the Couchbase compare and swap (CAS) value to detect conflicts with other processes before writing a record.

The Couchbase Lookup processor creates the couchbase.cas record header attribute for key/value lookups. The attribute stores a value that represents the state of the looked-up document.

When configured to use CAS and the couchbase.cas record header attribute exists, the destination sends Couchbase Server the attribute value with the write operation request. Couchbase Server compares the attribute value to the current CAS value for the document:
  • If the value of the record header attribute equals the current CAS value, then Couchbase Server writes the record to the document as requested.
  • If the value of the record header attribute does not equal the CAS value, then Couchbase Server perceives a conflict with another process and sends the unwritten record back to the destination. The destination sends the record to the pipeline for error handling.

When the couchbase.cas record header attribute does not exist, such as for records that originate from N1QL lookups, the destination cannot use the CAS value to detect conflicts.

Data Formats

The Couchbase destination writes data to Couchbase Server based on the data format that you select.

The Couchbase destination processes data formats as follows:
Avro
The destination writes records based on the Avro schema. You can use one of the following methods to specify the location of the Avro schema definition:
  • In Pipeline Configuration - Use the schema that you provide in the stage configuration.
  • In Record Header - Use the schema included in the avroSchema record header attribute.
  • Confluent Schema Registry - Retrieve the schema from Confluent Schema Registry. Confluent Schema Registry is a distributed storage layer for Avro schemas. You can configure the destination to look up the schema in Confluent Schema Registry by the schema ID or subject.

    If using the Avro schema in the stage or in the record header attribute, you can optionally configure the destination to register the Avro schema with Confluent Schema Registry.

The destination includes the schema definition in each file.
You can compress data with an Avro-supported compression codec. When using Avro compression, avoid using other compression properties in the destination.
Binary
The stage writes binary data to a single field in the record.
Delimited
The destination writes records as delimited data. When you use this data format, the root field must be list or list-map.
You can use the following delimited format types:
  • Default CSV - File that includes comma-separated values. Ignores empty lines in the file.
  • RFC4180 CSV - Comma-separated file that strictly follows RFC4180 guidelines.
  • MS Excel CSV - Microsoft Excel comma-separated file.
  • MySQL CSV - MySQL comma-separated file.
  • Tab-Separated Values - File that includes tab-separated values.
  • PostgreSQL CSV - PostgreSQL comma-separated file.
  • PostgreSQL Text - PostgreSQL text file.
  • Custom - File that uses user-defined delimiter, escape, and quote characters.
  • Multi Character Delimited - File that uses multiple user-defined characters to delimit fields and lines, and single user-defined escape and quote characters.
JSON
The destination writes records as JSON data.
Protobuf
Writes a batch of messages in each file.
Uses the user-defined message type and the definition of the message type in the descriptor file to generate the messages in the file.
For information about generating the descriptor file, see Protobuf Data Format Prerequisites.
SDC Record
The destination writes records in the SDC Record data format.
Text
The destination writes data from a single text field to the destination system. When you configure the stage, you select the field to use.
You can configure the characters to use as record separators. By default, the destination uses a UNIX-style line ending (\n) to separate records.
When a record does not contain the selected text field, the destination can report the missing field as an error or to ignore the missing field. By default, the destination reports an error.
When configured to ignore a missing text field, the destination can discard the record or write the record separator characters to create an empty line for the record. By default, the destination discards the record.

Configuring a Couchbase Destination

Configure a Couchbase destination to write data to a Couchbase database.

  1. In the Properties panel, on the General tab, configure the following properties:
    General Property Description
    Name Stage name.
    Description Optional description.
    Stage Library Library version that you want to use.
    Required Fields Fields that must include data for the record to be passed into the stage.
    Tip: You might include fields that the stage uses.

    Records that do not include all required fields are processed based on the error handling configured for the pipeline.

    Preconditions Conditions that must evaluate to TRUE to allow a record to enter the stage for processing. Click Add to create additional preconditions.

    Records that do not meet all preconditions are processed based on the error handling configured for the stage.

    On Record Error Error record handling for the stage:
    • Discard - Discards the record.
    • Send to Error - Sends the record to the pipeline for error handling.
    • Stop Pipeline - Stops the pipeline. Not valid for cluster pipelines.
  2. On the Couchbase tab, configure the following properties:
    Couchbase Property Description
    Connection Connection that defines the information required to connect to an external system.

    To connect to an external system, you can select a connection that contains the details, or you can directly enter the details in the pipeline. When you select a connection, Control Hub hides other properties so that you cannot directly enter connection details in the pipeline.

    Node List Comma-separated list of one or more nodes in a Couchbase cluster.
    Bucket Name of an existing Couchbase bucket to connect to.
    Scope Name of an existing Couchbase scope. To use the default scope for the bucket, enter _default.

    If you are using Couchbase SDK 2.x, you must use the default scope.

    For more information on scopes, see the Couchbase documentation.

    Default is _default.

    Collection Name of an existing Couchbase collection. To use the default collection for the bucket, enter _default.

    If you are using Couchbase SDK 2.x, you must use the default collection.

    For more information on collections, see the Couchbase documentation.

    Default is _default.

    Key-Value Timeout (ms) Maximum number of milliseconds allowed to execute each key-value operation.
    Connect Timeout (ms) Maximum number of milliseconds allowed to connect to Couchbase Server.
    Disconnect Timeout (ms) Maximum number of milliseconds allowed to gracefully close a connection.
    Advanced Environment Settings

    Client settings for connections with Couchbase Server. For available settings, see the Couchbase Java SDK documentation.

    Advanced environment settings do not apply to Couchbase SDK 3.x. Instead, you can use the SDC_JAVA_OPTS environment variable. For information on using environment variables for Data Collector, see Data Collector Environment Configuration.

  3. On the Credentials tab, configure the following properties:
    Credentials Property Description
    Authentication Mode Authentication to use to connect to Couchbase Server.
    Choose one of the following authentication modes based on the version of Couchbase you are using:
    • Bucket Authentication - Use for Couchbase 4.x.
    • User Authentication - Use for Couchbase 5.x and later.
    Bucket Password Couchbase bucket password.

    Required when Authentication Mode is set to Bucket Authentication.

    User Name Couchbase user name.

    Required when Authentication Mode is set to User Authentication.

    Password Couchbase password.

    Required when Authentication Mode is set to User Authentication.

    Use TLS Enables the use of TLS.
    Use Remote Keystore Enables loading the contents of the keystore from a remote credential store or from values entered in the stage properties. For more information, see Remote Keystore and Truststore.
    Private Key Private key used in the remote keystore. Enter a credential function that returns the key or enter the contents of the key.
    Certificate Chain Each PEM certificate used in the remote keystore. Enter a credential function that returns the certificate or enter the contents of the certificate.

    Using simple or bulk edit mode, click the Add icon to add additional certificates.

    Keystore File

    Path to the local keystore file. Enter an absolute path to the file or enter the following expression to define the file stored in the Data Collector resources directory:

    ${runtime:resourcesDirPath()}/keystore.jks

    By default, no keystore is used.

    Keystore Type Type of keystore to use. Use one of the following types:
    • Java Keystore File (JKS)
    • PKCS #12 (p12 file)

    Default is Java Keystore File (JKS).

    Keystore Password

    Password to the keystore file. A password is optional, but recommended.

    Tip: To secure sensitive information such as passwords, you can use runtime resources or credential stores. For more information about credential stores, see Credential Stores in the Data Collector documentation.
    Keystore Key Algorithm

    Algorithm to manage the keystore.

    Default is SunX509.

    Use Remote Truststore Enables loading the contents of the truststore from a remote credential store or from values entered in the stage properties. For more information, see Remote Keystore and Truststore.
    Trusted Certificates Each PEM certificate used in the remote truststore. Enter a credential function that returns the certificate or enter the contents of the certificate.

    Using simple or bulk edit mode, click the Add icon to add additional certificates.

    Truststore File

    Path to the local truststore file. Enter an absolute path to the file or enter the following expression to define the file stored in the Data Collector resources directory:

    ${runtime:resourcesDirPath()}/truststore.jks

    By default, no truststore is used.

    Truststore Type
    Type of truststore to use. Use one of the following types:
    • Java Keystore File (JKS)
    • PKCS #12 (p12 file)

    Default is Java Keystore File (JKS).

    Truststore Password

    Password to the truststore file. A password is optional, but recommended.

    Tip: To secure sensitive information such as passwords, you can use runtime resources or credential stores. For more information about credential stores, see Credential Stores in the Data Collector documentation.
    Truststore Trust Algorithm

    Algorithm to manage the truststore.

    Default is SunX509.

  4. On the Document Handling tab, configure the following properties:
    Document Property Description
    Document Key Unique ID or key for the document where the destination writes data. For example, you might specify an expression that resolves to the document key.
    Document Time-To-Live (seconds) Number of seconds after creation that a document expires. 0 or blank indicates documents do not expire. Default value is 0.
    Default Write Operation Default write operation to use when an operation type is not set in the sdc.operation.type record header attribute or sub-document operation:
    • Insert
    • Update
    • Upsert
    • Delete

    Default value is Upsert.

    Unsupported Operation Handling Action to take when the CRUD operation type defined in the sdc.operation.type record header attribute or the sub-document operation is not supported:
    • Discard - Discards the record.
    • Send to Error - Sends the record to the pipeline for error handling.
    • Use Default Operation - Writes the record to the destination system using the default operation.
    Use CAS Uses the Couchbase compare and swap (CAS) value to detect conflicts with other processes before writing a record.
    Allow Sub-Document Writes Allows writes to sub-documents.
    Sub-Document Path Path of the sub-document where destination writes the record. Use dot notation to separate components in the path. For more information, see the Couchbase documentation.

    If not specified, the destination writes the full document.

    Available when writes to sub-documents are allowed.

    Sub-Document Operation Write operation for the sub-document. The destination supports the following write operations for sub-documents:
    • INSERT
    • REPLACE
    • UPSERT
    • DELETE
    • ARRAY_PREPEND
    • ARRAY_APPEND
    • ARRAY_ADD_UNIQUE

    If not specified, the destination uses the write operation specified in the sdc.operation.type record header attribute or the default write operation.

    Available when writes to sub-documents are allowed.

    Durability Method Durability method to use:
    • Poll-based - Provides durability based on synchronous in-memory replication and disk persistence.
    • Durable Writes - Enforces Couchbase server durability requirements. This option is available only for Couchbase 6.5 or later and requires a minimum of 4 replicas configured on your bucket. For more information on Couchbase server durability and durable writes, see the Couchbase documentation.

    If you are using Couchbase SDK 2.x, you must use the default durability method.

    Default is Poll-based.

    Replicate To Number of times to replicate a document. The destination only considers the write successful after synchronous in-memory replication.

    With the default value, None, the destination does not wait for synchronous replication before considering the write complete. Couchbase will replicate the data asynchronously.

    Must be less than or equal to number of replicas configured for the bucket.

    Available when Durability Method is set to Poll-Based.
    Persist To Number of nodes to write a document to on disk. The destination only considers the write successful after synchronous disk persistence.

    With the default value, None, the destination does not wait for synchronous persistence before considering the write complete. Couchbase will persist the data asynchronously.

    If you select Master, the destination considers the write successful after the document persists on the master node. This option should be used only with Couchbase SDK 2.x and does not work with later versions.

    Must be less than or equal to number of replicas configured for the bucket plus one.

    Available when Durability Method is set to Poll-Based.

    Durability Level The level of durability for durable writes:
    • None - The destination does not wait for synchronous replication or persistence before considering the write complete.
    • Majority - The destination considers the write successful after the write is replicated on a majority of nodes.
    • Majority and Persist to Active - The destination considers the write successful after the write is replicated to a majority of nodes and it is persisted on the node hosting the active vBucket for the data.
    • Persist to Majority - The destination considers the write successful after the write is persisted to a majority of nodes.

    This property should be used only with Couchbase SDK 3.x and does not work with earlier versions.

    For more information on durability levels, see the Couchbase documentation.

    Default is None.

    Available when Durability Method is set to Durable Writes.

  5. On the Data Format tab, configure the following property:
    Data Format Property Description
    Data Format Format of data to be written. Use one of the following data formats:
    • Avro
    • Binary
    • Delimited
    • JSON
    • Protobuf
    • SDC Record
    • Text
  6. For Avro data, on the Data Format tab, configure the following properties:
    Avro Property Description
    Avro Schema Location Location of the Avro schema definition to use when writing data:
    • In Pipeline Configuration - Use the schema that you provide in the stage configuration.
    • In Record Header - Use the schema in the avroSchema record header attribute. Use only when the avroSchema attribute is defined for all records.
    • Confluent Schema Registry - Retrieve the schema from Confluent Schema Registry.
    Avro Schema Avro schema definition used to write the data.

    You can optionally use the runtime:loadResource function to load a schema definition stored in a runtime resource file.

    Register Schema Registers a new Avro schema with Confluent Schema Registry.
    Schema Registry URLs Confluent Schema Registry URLs used to look up the schema or to register a new schema. To add a URL, click Add and then enter the URL in the following format:
    http://<host name>:<port number>
    Basic Auth User Info User information needed to connect to Confluent Schema Registry when using basic authentication.

    Enter the key and secret from the schema.registry.basic.auth.user.info setting in Schema Registry using the following format:

    <key>:<secret>
    Tip: To secure sensitive information such as user names and passwords, you can use runtime resources or credential stores. For more information about credential stores, see Credential Stores in the Data Collector documentation.
    Look Up Schema By Method used to look up the schema in Confluent Schema Registry:
    • Subject - Look up the specified Avro schema subject.
    • Schema ID - Look up the specified Avro schema ID.
    Schema Subject Avro schema subject to look up or to register in Confluent Schema Registry.

    If the specified subject to look up has multiple schema versions, the destination uses the latest schema version for that subject. To use an older version, find the corresponding schema ID, and then set the Look Up Schema By property to Schema ID.

    Schema ID Avro schema ID to look up in Confluent Schema Registry.
    Include Schema Includes the schema in each file.
    Note: Omitting the schema definition can improve performance, but requires the appropriate schema management to avoid losing track of the schema associated with the data.
    Avro Compression Codec The Avro compression type to use.

    When using Avro compression, do not enable other compression available in the destination.

  7. For binary data, on the Data Format tab, configure the following property:
    Binary Property Description
    Binary Field Path Field that contains the binary data.
  8. For delimited data, on the Data Format tab, configure the following properties:
    Delimited Property Description
    Delimiter Format Format for delimited data:
    • Default CSV - File that includes comma-separated values. Ignores empty lines in the file.
    • RFC4180 CSV - Comma-separated file that strictly follows RFC4180 guidelines.
    • MS Excel CSV - Microsoft Excel comma-separated file.
    • MySQL CSV - MySQL comma-separated file.
    • Tab-Separated Values - File that includes tab-separated values.
    • PostgreSQL CSV - PostgreSQL comma-separated file.
    • PostgreSQL Text - PostgreSQL text file.
    • Custom - File that uses user-defined delimiter, escape, and quote characters.
    Header Line Indicates whether to create a header line.
    Delimiter Character Delimiter character for a custom delimiter format. Select one of the available options or use Other to enter a custom character.

    You can enter a Unicode control character using the format \uNNNN, where ​N is a hexadecimal digit from the numbers 0-9 or the letters A-F. For example, enter \u0000 to use the null character as the delimiter or \u2028 to use a line separator as the delimiter.

    Default is the pipe character ( | ).

    Record Separator String Characters to use to separate records. Use any valid Java string literal. For example, when writing to Windows, you might use \r\n to separate records.

    Available when using a custom delimiter format.

    Escape Character Escape character for a custom delimiter format. Select one of the available options or use Other to enter a custom character.

    Default is the backslash character ( \ ).

    Quote Character Quote character for a custom delimiter format. Select one of the available options or use Other to enter a custom character.

    Default is the quotation mark character ( " ).

    Replace New Line Characters Replaces new line characters with the configured string.

    Recommended when writing data as a single line of text.

    New Line Character Replacement String to replace each new line character. For example, enter a space to replace each new line character with a space.

    Leave empty to remove the new line characters.

    Charset Character set to use when writing data.
  9. For JSON data, on the Data Format tab, configure the following property:
    JSON Property Description
    Charset Character set to use when writing data.
  10. For protobuf data, on the Data Format tab, configure the following properties:
    Protobuf Property Description
    Protobuf Descriptor File Descriptor file (.desc) to use. The descriptor file must be in the Data Collector resources directory, $SDC_RESOURCES.

    For more information about environment variables, see Data Collector Environment Configuration in the Data Collector documentation. For information about generating the descriptor file, see Protobuf Data Format Prerequisites.

    Message Type Fully-qualified name for the message type to use when writing data.

    Use the following format: <package name>.<message type>.

    Use a message type defined in the descriptor file.
  11. For text data, on the Data Format tab, configure the following properties:
    Text Property Description
    Text Field Path Field that contains the text data to be written. All data must be incorporated into the specified field.
    Record Separator Characters to use to separate records. Use any valid Java string literal. For example, when writing to Windows, you might use \r\n to separate records.

    By default, the destination uses \n.

    On Missing Field When a record does not include the text field, determines whether the destination reports the missing field as an error or ignores the missing field.
    Insert Record Separator if No Text When configured to ignore a missing text field, inserts the configured record separator string to create an empty line.

    When not selected, discards records without the text field.

    Charset Character set to use when writing data.