On this Page

Overview

This 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.

Upcoming

Snap type:

Write

Snap Input/Output:

Expected upstream Snaps: 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 downstream Snaps: The Snap will output one document for every record merged, hence any document processing Snap can be used downstream.
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.
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.

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.

Prerequisites:

[None]

Support and limitations:

Works in Ultra Tasks.

Account:

This Snap uses account references created on the Accounts page of SnapLogic Manager to handle access to this endpoint. See Oracle Account for information on setting up this type of account.

Views:

Input	This Snap has exactly one document input view.
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.
Error	This Snap has at most one document error view and produces zero or more documents in the view.

Settings

Label

Required. Specify the name for the Snap. You can modify this to be more specific, especially if you have more than one of the same Snap in your pipeline.

Schema name

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

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

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.

Example: 3

Default value: 0

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.

Retry interval (seconds)

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

Example: 10

Default value: 1

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.

Merge condition

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

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.

Default value: None.
Example: NLS_TERRITORY

Session parameter value

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

Default value: None.

Example: CZECH REPUBLIC

Examples

Following are two examples. The first one using a conditional update of one of the values which gets then merged into the data using a Oracle Merge Snap. The second one will showcase error handling.

In the first example, we will drop a table, insert data into a newly created table, update one of records and then merge that update result into the same table.

The first Oracle Execute Snap will drop the existing table. We use an error view to handle the case where the table does not exist yet. Both the error and the output view then are funneled into a Union Snap which triggers the actual insertion data provided by a JSON Generator Snap.
Then we use a Mapper Snap to map back the original input data and use a Conditional Snap to update the value of the color black with #0000.
Next, we merge the updated value back into the table using the Oracle Merge Snap. There we define the merge condition as "color"=$color.
- Hint: The table COLOR1 was created on the fly, and the color column is created lowercase. We quote the color column in the merge condition since it is defined as a lower case column on the table.
- Hint: Multiple columns can be used in an expression such as "color"=$color and "value"=$value
Finally, we execute a select to verify the color black was updated was updated.

In the second example, we use an error view on the Oracle Merge Snap.

Here we miss-typed the variable in the condition, which will trigger an error. The error will be written to the error view of the Snap, which then can be used for debugging purpose or further processing.
An example of the error view is shown below.

Error is the message provided by SnapLogic.
Reason is defined as the message provided by the Oracle Database, which includes the database error code.
Original is defined as the data from the input view.

error: "SQL operation failed"
reason: "ORA-38104: Columns referenced in the ON Clause cannot be updated: "color"\n, error code: 38104, SQL state: 99999"
original:  {color:red, value:#f00}
   color: "red"
   value: "#f00"
resolution: "Please check for valid Snap properties and input data."
stacktrace: "com.Snaplogic.Snap.api.SnapDataException: SQL operation failed\n at com.Snaplogic.Snap.api.sql.DatabaseUtils.handleUpdateResult(DatabaseUtils.java:449)\n at com.

Oracle - Merge

Overview

Upcoming

Settings

Examples