Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

On this Page

Table of Contents
maxLevel2
excludeOlder Versions|Additional Resources|Related Links|Related Information

Snap type:

Write


Description:

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.


More info on SQL Merges can be found at Oracle Merge.


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.


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


Info
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 Task Pipelines.


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:


InputThis Snap has exactly one document input view.
OutputThis 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. 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



The database schema name. In case it is not defined, then the suggestion for the Table Name will retrieve all tables names of all schemas. The property is suggestible and will retrieve available database schemas during suggest values.

Note

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

ExampleSYS
Default value:  [None]


Table name

Required. Name of table to execute insert on

Note

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


Examplepeople

Default value:  [None]


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]


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

Note

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

Note

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.


Multiexcerpt include macro
nameSnap Execution
pageSOAP Execute


Multiexcerpt include macro
nameExecution_Detail_Write
pageSOAP Execute


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.


Expand
title1. Using a conditional update

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.


Expand
title2. Error handling

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.


Code Block
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.  
 



Excerpt Include
Oracle Snap Pack
Oracle Snap Pack
nopaneltrue