Getting Started with PDI
If you are new to Pentaho Data Integration, start here.
Use these tutorials to build your first transformations and jobs in Spoon.
In this topic
Pentaho Data Integration (PDI) tutorial
The following tutorial is intended for users who are new to the Pentaho suite or who are evaluating Pentaho as a data integration and business analysis solution. The tutorial consists of six basic steps, demonstrating how to build a data integration transformation and a job using the features and tools provided by Pentaho Data Integration (PDI).
The Data Integration perspective of PDI allows you to create two basic file types: transformations and jobs. Transformations describe the data flows for ETL such as reading from a source, transforming data and loading it into a target location. Jobs coordinate ETL activities such as defining the flow and dependencies for what order transformations should be run, or prepare for execution by checking conditions such as, "Is my source file available?" or "Does a table exist in my database?"
The aim of this tutorial is to walk you through the basic concepts and processes involved in building a transformation with PDI in a typical business scenario. In this scenario, you are loading a flat file (CSV) of sales data into a database to generate mailing lists. Several of the customer records are missing postal codes that must be resolved before loading into the database. In the preview feature of PDI, you will use a combination of steps to cleanse, format, standardize, and categorize the sample data. The six basic steps are:
Step 1: Extract and load data
Step 2: Filter for missing codes
Step 3: Resolve missing data
Step 4: Clean the data
Step 5: Run the transformation
Step 6: Orchestrate with jobs
Prerequisites
To complete this tutorial, you need the following items:
An installed version of the Pentaho 30-day trial.
Step 1: Extract and load data
In Step 1, you will retrieve data from a CSV flat file and use the Text File Input step to connect to a repository, view the file schema, and retrieve the data contents.
Create a new transformation
Follow these steps to create a new transformation.
If you want to insert a variable into a field that accepts variables, you can put your cursor in the fields and press CTRL+Spacebar to see a list of variables to insert. Fields that accept variables have a blue diamond.
Select File > New > Transformation in the upper-left corner of the PDI window.

Under the Design tab, expand the Input node, then select and drag a Text File Input step onto the canvas.
Double-click the Text File input step. In the Text file input window, you can set the properties of the step.

Text File Input File tab In the Step Name field, type
Read Sales Data.The Text file input step is now renamed to Read Sales Data.
Click Browse to locate the
sales_data.csvsource file in the...\design-tools\data-integration\samples\transformations\filesfolder. The Browse button appears in the upper-right side of the window near the File or Directory field.Change File type to
*.csv. Selectsales_data.csv, then click OK.The path to the source file appears in the File or directory field.
Click Add.
The path to the file appears under Selected Files.
View the content in the sample file
Follow these steps to look at the contents of the sample file.
Click the Content tab, then set the Format field to Unix.
Click the File tab again and click the Show file content in the lower section of the window.
The Number of lines (0-all lines) window appears. Click OK to accept the default.
The Content of first file window shows the file. Examine the file to see how that input file is delimited, what enclosure character is used, and whether or not a header row is present.
In the sample, the input file is comma delimited, using the enclosure character of a quotation mark ("). It contains a single header row containing field names.
Click the Close button to close the window.
Edit and save the transformation
Follow these steps to provide information about the data's content.
Click the Content tab. Use the fields under the Content tab to define how your data is formatted.
Verify that the Separator is set to comma (,) and that the Enclosure is set to quotation mark ("). Select Header and enter
1in the Number of header lines field.
Text File Input Content tab Click the Fields tab and click Get Fields to retrieve the input fields from your source file. When the Number of lines to sample window appears, enter
0in the field, then click OK.If the Scan Result window displays, click Close to close the window.

Text File Input Fields tab To verify that the data is read correctly, click the Content tab, then click Preview Rows.
In the Enter the number of rows you would like to preview window, click OK to accept the default.
The Examine preview data window appears.
Review the data. Do you notice any missing, incomplete, or variations of the data?
STATE & POSTALCODEboth contain<null>COUNTRYcontains bothUSAandUnited States.
Click OK to save the information that you entered in the step.
Enter a name for the transformation and provide additional properties using the Transformation Properties window. There are multiple ways to open the Transformation Properties window.
Right-click any empty space on the canvas and select Properties.
Double-click any empty space on the canvas to select Properties.
Enter the CTRL-T keyboard combination.
In the Transformation Name field, enter
Getting Started Transformation.Below the name, the filename is empty.
Click OK to close the Transformation Properties window.
To save the transformation, select File > Save.
When saving your transformation for the first time, you are prompted for a file location and name of your choice. The file extension
.ktris the usual file extension for transformations.
Load data into a relational database
Now you are ready to take all the records that are exiting the Filter Rows step (added in Step 2) where the POSTALCODE was not null (the true condition) and load them into a database table. You will use the Table Output step and a hop from the Text File Input step to direct the data stream into a database table. This section of the tutorial uses a pre-existing database established during the Pentaho installation, which is started along with the server.
Create the Table Output step
Follow these instructions to create the Table Output step.
Under the Design tab, expand the contents of the Output node.
Click and drag a Table Output step into your transformation.
Create a hop between the Read Sales Data and Table Output steps. To create the hop:
Press the SHIFT key.
Click the Read Sales Data (Text File Input) step and drag the mouse to draw a line to the Table Output step.
Release the SHIFT key.
Click the Table Output step.
Double-click the Table Output step to open its Edit properties dialog box.
Rename your Table Output step to Write to Database.
Create a connection to the database
Follow these steps to create a connection to the database.
Click New next to the Connection field. You must create a connection to the database.
The Database Connection window appears.
Provide the settings for connecting to the database.
FieldSettingConnection Name
Sample Data
Connection Type
Hypersonic
Host Name
localhost
Database Name
sampledata
Port Number
9001
User Name
pentaho_admin
Password
password (If
passworddoes not work, please check with your system administrator.)Click Test to verify your entries are correct. A success message appears. Click OK.
Note: If you get an error when testing your connection, ensure that you have provided the correct settings information as described in the table and that the sample database is running. Depending on your platform, see Start and stop the Pentaho Server for configuration on Windows or Start and stop the Pentaho Server for configuration on Linux.
Click OK to exit the Database Connections window.
Define the Data Definition Language (DDL)
DDLs are the SQL commands that define the different structures in a database such as CREATE TABLE. Fortunately, Pentaho can help you create the necessary DDL.
Enter
SALES_DATAin the Target Table text field.This table does not exist in the target database, so Pentaho can generate the DDL to create the table and execute it. In this scenario, the DDL is based on the stream of data coming from the previous step, which is the Read Sales Data step.
In the Table Output window, select the Truncate Table property.

Table Output step Truncate table field Click the SQL button in the bottom of the Table output dialog box to generate the DDL for creating your target table.
The Simple SQL editor window appears with the SQL statements needed to create the table.

Simple SQL editor Click Execute to execute the SQL statement.
The Results of the SQL statements window appears.
Examine the results, then click OK to close the Results of the SQL statements window.
Click Close in the Simple SQL editor window
Click OK to close the Table output window.
Save your transformation.
Step 2: Filter for missing codes
After completing Step 1: Extract and load data, you are ready to add a transformation component to your data pipeline. The source file contains several records that are missing postal codes. This section of the tutorial filters out those records that have missing postal codes, where the POSTALCODE is not null (the true condition), and ensures that only complete records are loaded into the database table.
Preview the rows read by the input step
Follow these steps to preview the rows read by the input step.
Right-click the Read Sales Data step and select Preview.

Transformation Menu showing how to access Preview Specify the number of rows to preview. Optionally, you can configure breakpoints which pause execution based on a defined condition, such as a field having a specific value or exceeding a threshold.
Click the Quick Launch button. Preview the data and notice that several of the input rows are missing values for the POSTALCODE field.

Preview showing missing postalcode fields Click Stop on the preview window to end the preview.
Separate the records with missing postal codes
Follow these instructions to use the Filter Rows transformation step to separate out those records missing postal codes. These records are resolved later in the tutorial.
Add a Filter Rows step to your transformation. Under the Design tab, select Flow > Filter Rows.
Insert your Filter Rows step between your Read Sales Data step and your Write to Database step.
Right-click and delete the hop between the Read Sales Data step and Write to Database steps.
Create a hop between the Read Sales Data step and the Filter Rows step. Create a hop by clicking the step, and then hold the SHIFT key down and click-and-drag to draw a line to the next step.
Create a hop between the Filter Rows step and Write to Database step.
In the dialog box that appears, select Result is TRUE.

Hop dialog set to Result is True Double-click the Filter Rows step. The Filter Rows window appears.
In the Step Name field, enter
Filter Missing Zips.Click in The condition field to open the Fields window. The available conditions appear.
In the Fields window select POSTALCODE and click OK.
Click the comparison operator field, which is set to = by default. The Functions window appears.
Select IS NOT NULL from the list of functions, and then click OK to close the Functions window.

Filter rows is set postalcode is not null Click OK to exit the Filter Rows window.
Note: You will return to this step later to configure the Send true data to step and Send false data to step settings after adding their target steps to your transformation.
Save your transformation.
Step 3: Resolve missing data
After completing Step 2: Filter for missing codes, you are ready to resolve the missing postal codes. In this section, you will learn how to use a second text file containing a list of cities, states, and postal codes, to look up the postal codes for those records in which the fields are missing, which is the false branch of your Filter rows step.
First, you will use a Text file input step to read from the source file. Then, you will use a Stream lookup step to bring the resolved postal codes into the stream. Lastly, you will use the Select values step to rename fields on the stream, remove unnecessary fields, and more.
Retrieve data from your lookup file
Follow these steps to retrieve data from your lookup file.
Add a new Text File Input step to your transformation.
This step retrieves the records from your lookup file. Do not add a hop yet.

Add Text File Input step to canvas Open the Text File Input step window, then enter
Read Postal Codesin the Step name property.Click Browse to navigate to the
Zipssortedbycitystate.csvsource file located in the directory...\design-tools\data-integration\samples\transformations\files.Change File type to
*.csv, selectZipsortedbycitrystate.csv, and click OK.The path to the source file appears in the File or directory field.
Click Add.
The path to the file appears under Selected files.
View the contents of the sample file
Follow these steps to view the contents of the sample file.
Click the Content tab, then set the Format field to Unix.
Click the File tab again and click the Show file content near the bottom of the window.
The Number of lines(0=all lines) window appears. Click the OKbutton to accept the default.
The Content of first file window shows the file. Examine the file to see how that input file is delimited, what enclosure character is used, and whether a header row is present. In the example, the input file is comma (,) delimited and the enclosure character is the quotation mark ("). A single header row contains field names.
Click Close to close the window.
Edit and save the transformation
Follow these steps to edit and save your transformation.
In the Content tab, change the Separator character to a comma (,) and confirm that the Enclosure setting is a quotation mark ("). Verify that the Header option is selected.
Under the Fields tab, click Get Fields to retrieve the data from your CSV file.
The Number of lines to sample window appears. Enter
0in the field, then click OK.
Results from Get Fields in the Fields tab If the Scan Result window displays, click Close to close it.
Click Preview rows to verify that your entries are correct.
When prompted to enter the preview size, click OK.
Review the information in the window, then click Close.
Click OK to exit the Text File input window.
Save the transformation.
Resolve missing zip code information
Follow these steps to resolve the missing postal code information.
Add a Stream Lookup step to your transformation by clicking the Design tab, expanding the Lookup folder, then selecting Stream Lookup.
Draw a hop from the Filter Missing Zips to the Stream lookup step. In the dialog box that appears, select Result is FALSE.
Create a hop from the Read Postal Codes step to the Stream lookup step.

Add a hop from Read Postal Codes to Stream Lookup Double-click the Stream lookup step to open the Stream Value Lookup window.
Rename Stream Lookup to Lookup Missing Zips.
From the Lookup step drop-down box, select Read Postal Codes as the lookup step. Perform the following:
In the key(s) to look up the value(s) table, define the CITY and STATE fields .
In row #1, open the drop-down menu in the Field column and select CITY.
Click in the LookupField column and select CITY.
In row #2, open the drop-down menu in the Field column and select STATE.
Click in the LookupField column and select STATE.

Stream value lookup example
Click Get Lookup Fields to pull the three fields from the Read Postal Code step.
POSTALCODE is the only field you want to retrieve. To delete the CITY and STATE lines, right-click in the line and select Delete Selected Lines.
In the New Name field, change the name POSTALCODE to ZIP_RESOLVED and verify that Type is set to String.
Select Use sorted list (i.s.o. hashtable).

Value lookup example Click OK to close the Stream Value Lookup edit properties dialog box.
Save your transformation.
Preview your transformation
Follow these steps to preview your transformation.
To preview the data, select and right-click the Lookup Missing Zips step. From the menu that appears, select Preview.
In the Transformation debug dialog window, click Quick Launch to preview the data flowing through this step.
In the Examine preview data window that appears, note that the new field, ZIP_RESOLVED, has been added to the stream containing your resolved postal codes.
Click Close to close the window.
If the Select the preview step window appears, click Close.
The execution results near the bottom of the PDI window show updated metrics in the Step Metrics tab.
Apply formatting to your transformation
Follow these steps to clean up the field layout on your lookup stream so that it matches the format and layout of the other stream going to the Write to Database step.
Add a Select Values step to your transformation by expanding the Transform folder and clicking Select Values.
Create a hop from the Lookup Missing Zips to the Select Values step.

Add hop from Lookup Missing Zips to Select Values Double-click the Select Values step to open its properties dialog box.
Rename the Select Values step to Prepare Field Layout.
Click Get fields to select to retrieve all fields and begin modifying the stream layout.
In the Fields list, find the # column and click the number for the ZIP_RESOLVED field.
Use CTRL+UP (Windows/Linux) or COMMAND+UP (macOS) to move ZIP_RESOLVED just below the POSTALCODE field, which is the one that still contains null values.

Move ZIP_RESOLVED field under POSTALCODES field Select the old POSTALCODE field in the list (line 20), right-click in the line, and select Delete Selected Lines
The original POSTALCODE field was formatted as a 9-character string. You must modify your new field to match the form. Click the Meta-Data tab.
In the first row of the Fields to alter table the meta-data for section, click in the Fieldname column and select ZIP_RESOLVED. Perform the following steps:
Enter
POSTALCODEin the Rename to column.Select String in the Type column and enter
9in the Length column.
POSTALCODE String type and length Click OK to exit the edit properties dialog box.
Draw a hop from the Prepare Field Layout (Select values) step to the Write to Database (Table output) step.
When prompted, select the Main output of the step option.
Save your transformation.

Renaming fields workflow example
Step 4: Clean the data
After completing Step 3: Resolve missing data, you can further cleanse and categorize the data into buckets before loading it into a relational database. In this section, you will cleanse the COUNTRY field data by mapping United States to USA using the Value mapper step. Cleaning the data ensures there is only one version of USA.
In addition, you will learn how to use buckets for categorizing the SALES data into small, medium, and large categories using the Number range step. You will learn how to insert these cleaning and categorizing functions into your transformation just prior to the Write to Database step on the canvas.
Add a Value mapper step to the transformation
Follow these steps to add the Value mapper step to the transformation.
Delete both hops connected to the Write to Database step. For each hop, right-click and select Delete.
Create some extra space on the canvas. Drag the Write to Database step toward the right side of your canvas.

Add space on canvas for Value mapper step Add the Value mapper step to your transformation by expanding the Transform folder and choosing Value mapper.
Create a hop between the Filter Missing Zips and Value mapper steps. In the dialog box that appears, select Result is TRUE.
Create a hop between the Prepare Field Layout and Value mapper steps. When prompted, select the Main output of the step option.

Add Value mapper step to the canvas
Set the properties in the Value Mapper step
Follow these steps to set the properties in the Value mapper step.
Double-click the Value mapper step to open its properties dialog box.
Click in the Fieldname to use field and select COUNTRY.
In the Field Values table, define the
United StatesandUSAfield values.In row #1, click the field in the Source value column and enter
United StatesThen, click the field in the Target value column and enter
USA
Set values for fields in the Value mapper step
Click OK.
Save your transformation.
Apply ranges
Follow these steps to apply ranges to your transformation.
Add a Number range step to your transformation by expanding the Transform folder and selecting Number range.
Create a hop between the Value mapper and Number range steps.
Create a hop between the Number range and Write to Database (which was built using Table output) steps. When prompted, select the Main output of the step option.

Add Number range step to the canvas Double-click the Number range step to open its properties dialog box.
Click in the Input field and select SALES from the list.
In the Output field enter
DEALSIZE.In the Ranges (min <=x< max) table, define the Lower Bound and Upper Bound field ranges along with the bucket Value.
In row #1, click the field in the Upper Bound column and enter
3000.0. Then, click the field in the Value column and enterSmall.In row #2, click the field in the Lower Bound column and enter
3000.0. Then, click the field in the Upper Bound column and enter7000.0. Click the field in the Value column and enterMedium.In row #3, click the field in the Lower Bound column and enter
7000.0. Then, click the field in the Value column and enterLarge.
Set ranges in Number Range step
Click OK.
Execute the SQL statement
Your database table does not yet contain the field DEALSIZE. Perform these steps to execute the SQL statement.
Double-click the Write to Database step to open its properties dialog box.
Click the SQL button at the bottom of the window to generate the new DDL for editing your original target table. Note that the Write to Database step was built using Table output.
The Simple SQL editor window appears with the SQL statements needed to
alterthe table.
Simple SQL editor to generate the DDL Click Execute to execute the SQL statement.
The Results of the SQL statements window appears. Examine the results, then click OK to close the window.
Click Close in the Simple SQL editor window to close it.
Click OK to close the Write to Database window. Note that the Write to Database step was built using Table output
Save your transformation.
Step 5: Run the transformation
Pentaho Data Integration provides a number of deployment options. The Running a Transformation section in the Pentaho Data Integration document explains these and other options available for execution. In this section of the tutorial, you create a transformation using the Local run option.
In the PDI client window, select Action > Run.
The Run Options window appears.
Keep the default Pentaho local option for this exercise.
It uses the native Pentaho engine and runs the transformation on your local machine. See the Pentaho Data Integration document if you are interested in setting up configurations that use another engine.
Click Run.
The transformation executes.

Transformation runs without errors
After the transformation runs, the Execution Results panel opens below the canvas.
Viewing the execution results
Use the tabs in the Execution Results section of the window to view how the transformation executed, pinpoint errors, and monitor performance.
Step Metrics
Provides statistics for each step in your transformation including how many records were read, written, or caused an error, as well as processing speed (rows per second) and more. This tab also indicates whether an error occurred in a transformation step.
This tutorial introduces no intentional transformation errors, so the transformation should run correctly. If a mistake does occur, you can view the steps that caused the transformation to fail highlighted in red. In the example below, the Lookup Missing Zips step caused an error.

Error message display Logging
Shows the logging details for the most recent execution of the transformation. It also allows you to drill deeper to determine where errors occur. Error lines are highlighted in red. In the example below, the Lookup Missing Zips step caused an error because it attempted to look up values on a field called POSTALCODE2 which did not exist in the lookup stream.

Transformation logging display Execution History
Provides access to the step metrics and log information from previous executions of the transformation. This feature works only if you have configured your transformation to log to a database through the Logging tab of the Transformation Settings dialog box.
Performance Graph
Analyzes the performance of steps based on a variety of metrics including how many records were read, written, or caused an error, as well as processing speed (rows per second) and more. Like the execution history, this feature requires you to configure your transformation to log to a database through the Logging tab found in the Transformation Settings dialog box.
Metrics tab
Shows a Gantt chart after the transformation or job runs. This information includes how long it takes to connect to a database, the time spent executing a SQL query, or the load time of a transformation.

Step metrics tab Preview Data
Shows a preview of the data.
Step 6: Orchestrate with jobs
Jobs are used to coordinate ETL activities such as:
Defining the flow and dependencies that control the linear order for the transformations to run.
Preparing for execution by checking conditions such as, "Is my source file available?" or "Does a table exist?"
Performing bulk load database operations.
Assisting file management, such as posting or retrieving files using FTP, copying files, and deleting files.
Sending success or failure notifications through email.
For this part of the tutorial, imagine that an external system is responsible for placing your sales_data.csv input in its source location every Saturday night at 9 p.m. You want to create a job that will verify that the file has arrived and then run the transformation to load the records into the database. In a subsequent exercise, you will schedule the job to run every Sunday morning at 9 a.m.
The following steps assume that you have built a Getting Started transformation as described in Step 1: Extract and load data of the tutorial.
Go to File > New > Job.

PDI job window Expand the General folder and drag a Start job entry onto the canvas.
The Start job entry defines where the execution will begin.
Note: Jobs run in a sequential order of steps and transformations can run in a parallel order of steps.
Expand the Conditions folder and add a File Exists job entry.
Draw a hop from the Start job entry to the File Exists job entry.

Draw hop from Start to File exists Double-click the File Exists job entry to open its properties dialog box. Click Browse and set the filter near the bottom of the window to All Files. Select the
sales_data.csvfrom the following directory:...\design-tools\data-integration\samples\transformations\files.Click OK to exit the Open File window.
Click OK to exit the Check if a file exists window.
Expand the General folder and add a Transformation job entry.
Draw a hop between the File Exists and the Transformation job entries.
Double-click the Transformation job entry to open its properties dialog box.
Click Browse to open the Select repository object window. Browse to and select the Getting Started transformation.
Click OK to close the Transformation window.
Save your job as Sample Job.
Click Run icon in the toolbar. When the Run Options window appears, select Local environment type and click Run. The Execution Results panel should open showing you the job metrics and log information for the job execution.

Job sample
PDI job tutorial
This is a shorter, standalone version of the job exercise.
Jobs are used to coordinate ETL activities such as:
Defining the flow and dependencies for what order transformations should be run.
Preparing for execution by checking conditions such as, "Is my source file available?" or "Does a table exist?"
Performing bulk load database operations.
File management such as posting or retrieving files using FTP, copying files and deleting files.
Sending success or failure notifications through email.
For this exercise, imagine that an external system is responsible for placing your sales_data.csv input in its source location every Saturday night at 9 p.m. You want to create a job that will check to see that the file has arrived and run your transformation to load the records into the database. In a subsequent exercise, you will schedule the job to be run every Sunday morning at 9 a.m.
To complete this exercise, you must have completed the exercises in the Pentaho Data Integration (PDI) tutorial.
Go to File > New > Job.

PDI Job Window Expand the General folder and drag a Start job entry onto the graphical workspace.
The Start job entry defines where the execution will begin.
Expand the Conditions folder and add a File Exists job entry.
Draw a hop from the Start job entry to the File Exists job entry.
Double-click the File Exists job entry to open its Edit Properties dialog box. Click Browse and set the filter near the bottom of the window to All Files. Select the
sales_data.csvfrom the following location:...\design-tools\data-integration\samples\transformations\files.Click OK to exit from the Open File window.
Click OK to exit from the Check if a file exists window.
In Spoon, expand the General folder and add a Transformation job entry.
Draw a hop between the File Exists and the Transformation job entries.
Double-click the Transformation job entry to open its edit Properties dialog box.
Click Browse to open the Select repository object window. Browse to and select the transformation you created in the Pentaho Data Integration (PDI) tutorial.
Expand the repository tree to find your sample transformation. Select it and click OK.

Select repository object window Save your job as Sample Job.
Click Run icon in the toolbar. When the Run Options window appears, choose Local environment type and click Run. The Execution Results panel should open showing you the job metrics and log information for the job execution.

Job Sample
Getting started with PDI and Hadoop
Pentaho provides a complete big data analytics solution that supports the entire big data analytics process. From big data aggregation, preparation, and integration, to interactive visualization, analysis, and prediction, Pentaho allows you to harvest the meaningful patterns buried in big data stores. Analyzing your big data sets gives you the ability to identify new revenue sources, develop loyal and profitable customer relationships, and run your organization more efficiently and cost effectively.
Next steps
The tutorials above are designed to quickly demonstrate basic PDI features.
For more detailed information about PDI features and functions, see the following topics in the Pentaho Data Integration document:
Learn about the PDI Client
Use Pentaho Repositories in PDI
Schedule Perspective in the PDI Client
Last updated
Was this helpful?

