Source Qualifier Transformation Overview

Transformation type:
Active
Connected

For more information about Application Source Qualifier transformations, see the
corresponding help topic for your PowerExchange product.

When you add a relational or a flat file source definition to a mapping, you need
to connect it to a Source Qualifier transformation. The Source Qualifier
transformation represents the rows that the Integration Service reads when it
runs a session.

Use the Source Qualifier transformation to complete the following tasks:

Join data originating from the same source database. You can join two or
more tables with primary key-foreign key relationships by linking the sources to
one Source Qualifier transformation.
Filter rows when the Integration Service reads source data. If you include a
filter condition, the Integration Service adds a WHERE clause to the default
query.
Specify an outer join rather than the default inner join. If you include a user-
defined join, the Integration Service replaces the join information specified by
the metadata in the SQL query.
Specify sorted ports. If you specify a number for sorted ports, the Integration
Service adds an ORDER BY clause to the default SQL query.
Select only distinct values from the source. If you choose Select Distinct, the
Integration Service adds a SELECT DISTINCT statement to the default SQL
query.
Create a custom query to issue a special SELECT statement for the
Integration Service to read source data. For example, you might use a
custom query to perform aggregate calculations.

Target Load Order

You specify a target load order based on the Source Qualifier transformations in
a mapping. If you have multiple Source Qualifier transformations connected to
multiple targets, you can designate the order in which the Integration Service
loads data into the targets.

If one Source Qualifier transformation provides data for multiple targets, you can
enable constraint-based loading in a session to have the Integration Service load
data based on target table primary and foreign key relationships.
Datetime Values

When you use a datetime value or a datetime parameter or variable in the SQL
query, change the date format to the format used in the source. The Integration
Service passes datetime values to source systems as strings in the SQL query.
The Integration Service converts a datetime value to a string, based on the
source database.

The following table describes the datetime formats for each database type:

Source Date Format

DB2 YYYY-MM-DD-HH24:MI:SS
Informix YYYY-MM-DD HH24:MI:SS
Microsoft SQL Server MM/DD/YYYY HH24:MI:SS
ODBC YYYY-MM-DD HH24:MI:SS
Oracle MM/DD/YYYY HH24:MI:SS
Sybase MM/DD/YYYY HH24:MI:SS
Teradata YYYY-MM-DD HH24:MI:SS

Some databases require you to identify datetime values with additional

punctuation, such as single quotation marks or database specific functions. For
example, to convert the $$$SessStartTime value for an Oracle source, use the
following Oracle function in the SQL override:

to_date (‘$$$SessStartTime’, ‘mm/dd/yyyy hh24:mi:ss’)

For Informix, use the following Informix function in the SQL override to convert
the $$$SessStartTime value:

DATETIME ($$$SessStartTime) YEAR TO SECOND

For information about database specific functions, see the database

documentation

Parameters and Variables

You can use parameters and variables in the SQL query, user-defined join, source filter,
and pre- and post-session SQL commands of a Source Qualifier transformation. Use any
parameter or variable type that you can define in the parameter file. You can enter a
parameter or variable within the SQL statement, or you can use a parameter or variable as
the SQL query. For example, you can use a session parameter, $ParamMyQuery, as the
SQL query, and set $ParamMyQuery to the SQL statement in a parameter file.
The Integration Service first generates an SQL query and expands each parameter or
variable. It replaces each mapping parameter, mapping variable, and workflow variable
with its start value. Then it runs the query on the source database.

When you use a string mapping parameter or variable in the Source Qualifier
transformation, use a string identifier appropriate to the source system. Most databases
use a single quotation mark as a string identifier. For example, to use the string parameter
$$IPAddress in a source filter for a Microsoft SQL Server database table, enclose the
parameter in single quotes as follows: ‘$$IPAddress.’

When you use a datetime mapping parameter or variable, or when you use the built-in
variable $$$SessStartTime, change the date format to the format used in the source. The
Integration Service passes datetime values to source systems as strings in the SQL query

Source Qualifier Transformation Properties

Configure the following Source Qualifier transformation properties on the Properties tab:

Option Description
SQL Query Defines a custom query that replaces the default query the Integration
Service uses to read data from sources represented in this Source Qualifier
transformation. A custom query overrides entries for a custom join or a
source filter.
User-Defined Specifies the condition used to join data from multiple sources represented
Join in the same Source Qualifier transformation.
Source Filter Specifies the filter condition the Integration Service applies when querying
rows.
Number of Indicates the number of columns used when sorting rows queried from
Sorted Ports relational sources. If you select this option, the Integration Service adds an
ORDER BY to the default query when it reads source rows. The ORDER
BY includes the number of ports specified, starting from the top of the
transformation.
When selected, the database sort order must match the session sort order.
Tracing Level Sets the amount of detail included in the session log when you run a
session containing this transformation.
Select Distinct Specifies if you want to select only unique rows. The Integration Service
includes a SELECT DISTINCT statement if you choose this option.
Pre-SQL Pre-session SQL commands to run against the source database before the
Integration Service reads the source.
Post-SQL Post-session SQL commands to run against the source database after the
Integration Service writes to the target.
Output is Relational source or transformation output that does not change between
Deterministic session runs when the input data is consistent between runs. When you
configure this property, the Integration Service does not stage source data
 for recovery if transformations in the pipeline always produce repeatable
data.
Output is Relational source or transformation output that is in the same order
Repeatable between session runs when the order of the input data is consistent. When
output is deterministic and output is repeatable, the Integration Service
does not stage source data for recovery.

Default Query
For relational sources, the Integration Service generates a query for each Source Qualifier
transformation when it runs a session. The default query is a SELECT statement for each
source column used in the mapping. In other words, the Integration Service reads only the
columns that are connected to another transformation.

The following figure shows a single source definition connected to a Source Qualifier
transformation:
Although there are many columns in the source definition, only three columns are
connected to another transformation. In this case, the Integration Service generates a
default query that selects only those three columns:

SELECT CUSTOMERS.CUSTOMER_ID, CUSTOMERS.COMPANY,

CUSTOMERS.FIRST_NAME
FROM CUSTOMERS

If any table name or column name contains a database reserved word, you can create and
maintain a file, reswords.txt, containing reserved words. When the Integration Service
initializes a session, it searches for reswords.txt in the Integration Service installation
directory. If the file exists, the Integration Service places quotes around matching
reserved words when it executes SQL against the database. If you override the SQL, you
must enclose any reserved word in quotes.

When generating the default query, the Designer delimits table and field names
containing the following characters with double quotes:

/ + - = ~ ` ! % ^ & * ( ) [ ] { } ' ; ? , < > \ | <space>

Viewing the Default Query

You can view the default query in the Source Qualifier transformation.

To view the default query:

1.From the Properties tab, select SQL Query.

The SQL Editor displays the default query the Integration Service uses to select source
data.
2.Click Generate SQL.
3.Click Cancel to exit.

Note: If you do not cancel the SQL query, the Integration Service overrides the default
query with the custom SQL query.

Do not connect to the source database. You only connect to the source database when you
enter an SQL query that overrides the default query.

You must connect the columns in the Source Qualifier transformation to another
transformation or target before you can generate the default query.

Overriding the Default Query

You can alter or override the default query in the Source Qualifier transformation by
changing the default settings of the transformation properties. Do not change the list of
selected ports or the order in which they appear in the query. This list must match the
connected transformation output ports.

When you edit transformation properties, the Source Qualifier transformation includes
these settings in the default query. However, if you enter an SQL query, the Integration
Service uses only the defined SQL statement. The SQL Query overrides the User-
Defined Join, Source Filter, Number of Sorted Ports, and Select Distinct settings in the
Source Qualifier transformation.

Note: When you override the default SQL query, you must enclose all database reserved
words in quotes.