Oracle - Merge

Overview

The Oracle - Merge Snap executes a SQL Merge with given properties.

The documents that are provided in the input view will be merged into the provided table on the provided database. Each document on the input view is expected to be merged or created with/as a new record in the table. Learn more about SQL Merges: Oracle Merge.

Important: JDBC Driver upgrade and behavior change

The Oracle JDBC Driver is upgraded from OJDBC6 JAR (v11.2.0.4) to OJDBC10 JAR (v19.20.0.0) in the latest distribution in October 2023 and deployed to the stable distribution in the November 2023 release (after the Snaplex upgrade). The latest JDBC driver upgrade is backward-compatible. Learn more: Oracle JDBC driver and JOOQ upgrades.

You can consume this driver upgrade with the 434patches23000 Snap Pack version.

This JDBC driver upgrade has resulted in specific behavior changes that include errors, status codes, and success and failure messages. Learn more about the behavior changes to ensure your migration to the upgraded driver is seamless.

Prerequisites

None.

Snap views

Type Description Examples of upstream and downstream Snaps
Input

This Snap has exactly one document input view.

The columns of the selected table need to be mapped upstream using a Mapper Snap. The Mapper Snap will provide the target schema, which reflects the schema of the table that is selected for the Merge Snap.

Expected input: Document that conforms to the input view schema of the Snap. The input view schema is provided to an upstream Mapper Snap based on the selected service object.

Output

This Snap has at most one output view.

If an output view is available, then the original document that was used to create the statement will be output with the status of the merge executed.

Expected output: Document which represents the status of the merge operation for that document. Each merge operation is represented as one document in the output view.

Learn more about Error handling.

Snap settings

Legend:
  • Expression icon (): Allows using pipeline parameters to set field values dynamically (if enabled). SnapLogic Expressions are not supported. If disabled, you can provide a static value.
  • SnapGPT (): Generates SnapLogic Expressions based on natural language using SnapGPT. Learn more.
  • Suggestion icon (): Populates a list of values dynamically based on your Snap configuration. You can select only one attribute at a time using the icon. Type into the field if it supports a comma-separated list of values.
  • Upload : Uploads files. Learn more.
Learn more about the icons in the Snap settings dialog.

Merges will be batched up until the account's batch size property or until the structure of the update statement changes. An update statement will change if an incoming document contains different keys than a previous document.

The merge condition can only use variables, no constants or pipeline parameters. A good example for a merge condition is SALARY = $SALARY (here we use the SALARY variable of the input document).

A bad example for a merge condition is SALARY = '100000' (this will not work since we validate the provided columns in the condition against the types defined in the table schema). You do not want to use the expression toggle on the merge condition, there is support for it but it requires undocumented functions. The bad example can be rewritten by using an upstream Mapper Snap, where '10000' is mapped to the SALARY variable, which then can be used in the merge condition as defined in a good example. The same applies for pipeline parameters, which need to be mapped upstream similarly using a Mapper Snap.

Field/Field set Description

Label

String

Required. Specify a unique name for the Snap. Modify this to be more appropriate, especially if more than one of the same Snaps is in the pipeline.

Default value: Oracle - Merge

Schema name

String/Expression/ Suggestion

Specify the database schema name. The suggestions in the Schema field are populated only when at least a single table exists in the schema. If no tables exist to use that schema, only SYS, SYSTEM, and XDB are populated.

The values can be passed using the pipeline parameters but not the upstream parameter.

Example: SYS

Default value: None

Table name

String/Expression/ Suggestion

Required. Specify the table that the rows will be inserted into. This list is populated based on the tables associated with the selected schema.

The values can be passed using the pipeline parameters but not the upstream parameter.

Example: people

Default value: None

Number of retries

Integer/Expression

Specifies the maximum number of attempts to be made to receive a response. The request is terminated if the attempts do not result in a response.

When you enable retry and a connection failure occurs that cannot be recovered by retry, the Snap writes a connection failure error in the error view. In some cases, the error view records might contain duplicate data that was written to the database. Ensure to verify all the records in the error file before you restart the merge request. You can locate the duplicate records in the error view by checking the $reason property for the sub-string: Connection is not available, request timed out.

Example: 3

Default value: 0

Retry interval (seconds)

Integer/Expression

Specifies the time interval between two successive retry requests. A retry happens only when the previous attempt resulted in an exception.

When you enable retry and a connection failure occurs that cannot be recovered by retry, the Snap writes a connection failure error in the error view. In some cases, the error view records might contain duplicate data that was written to the database. Ensure to verify all the records in the error file before you restart the merge request. You can locate the duplicate records in the error view by checking the $reason property for the sub-string: Connection is not available, request timed out.

Example: 10

Default value: 1

Merge condition

String/Expression

Required. The ON condition of the merge statement. A boolean-type expression is expected. For an explanation of merge syntax, see Oracle Merge.

Default value: None

Session parameters

Use this fieldset to set the National Language Support (NLS) parameters. Learn more about Setting NLS Parameters. The NLS parameters override the default value, for example, comma (,) set for the session in the initialization parameter file or set by the client with environment variables, such as a decimal point.
Session parameter name

String/Expression

Specify the name of the NLS parameter.

  • This Snap supports the Enable, Disable, and Force commands in session parameters.
  • This field supports only pipelines parameters, and not upstream values.

Example: NLS_TERRITORY

Default value: None

Session parameter value

String/Expression

Specify the value for the NLS parameter. This field supports only pipelines parameters, and not upstream values.

Example: CZECH REPUBLIC

Default value: None

Snap execution

Dropdown list
Choose one of the three modes in which the Snap executes. Available options are:
  • Validate & Execute: Performs limited execution of the Snap and generates a data preview during pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during pipeline runtime.
  • Execute only: Performs full execution of the Snap during pipeline execution without generating preview data.
  • Disabled: Disables the Snap and all Snaps that are downstream from it.

Default value: Execute only

Example: Validate & execute

Examples

  1. Using a conditional update
  2. Error handling of the Snap (Oracle Merge)