Transferring data to SQL Database

This guide explains how to transfer data to SQL Database to store and further process information.

Introduction

Use the SQL Database destination to transfer data to an SQL Database. Adverity supports the following engine types:

  • Amazon Redshift

  • Microsoft SQL Server

  • MySQL

  • Oracle

  • Postgres

  • SAP HANA

  • Snowflake

You can assign multiple destinations to a datastream. For more information on possible limitations, see Assigning multiple destinations to a datastream.

Prerequisites

Before you complete the procedure in this guide, perform all of the following actions:

Procedure

To transfer data from a datastream to SQL Database, follow these steps:

  1. Add SQL Database as a destination to the workspace which contains the datastream or to one of its parent workspaces.

  2. Assign the SQL Database destination to the datastream.

  3. Configure transfer settings.

Adding SQL Database as a destination

To add SQL Database as a destination to a workspace, follow these steps:

  1. Select the workspace you work with in Adverity and then, in the platform navigation menu, click Destinations.

  2. Click + Add Destination.

  3. Click SQL Database.

  1. In the Configuration page, fill in the following fields:

    Name

    (Optional) Rename the destination.

    Engine type

    Select the SQL engine type from the drop-down list.

    Hostname

    Specify the URL of the SQL Database. If you use a port other than the default setting for this SQL Database, specify the port in the format hostname:port.

    Database

    Specify the name of the database where to transfer the data.

    Username

    Enter the username for SQL Database destination.

    Password

    Enter the password for SQL Database destination.

    For more information on advanced configuration settings, see Advanced SQL Database tips.

  1. Click Create.

Assigning SQL Database as a destination

To assign the SQL Database destination to a datastream, follow these steps:

  1. Select the workspace you work with in Adverity and then, in the platform navigation menu, click Datastreams.

  1. Select the chosen datastream.

  1. In the Transfer section, click + Assign destination.

  2. Click Assign existing destinations.

  1. Select the SQL Database checkbox in the list.

  2. Click Save.

Configuring transfer settings

To configure transfer settings, follow these steps:

  1. Select the workspace you work with in Adverity and then, in the platform navigation menu, click Datastreams.

  1. Select the chosen datastream.

  1. In the Destinations section, find the SQL Database destination in the list, and click on the right.

  2. Click Destination settings.

  1. Fill in the following fields:

    Table name

    Specify the target table in the destination where to transfer data from the datastream. The name can contain alphanumeric characters and underscores. For example, target_table. To specify a schema, use the syntax schemaName.tableName.

    By default, Adverity saves data from each datastream in a different table named {datastream_type}_{datastream_id} (for example, mailgun_83).

    You can specify the same target table for several datastreams. If a column is shared between datastreams, Adverity performs a full outer join and concatenates values. If a column is not shared between datastreams, Adverity writes null values in the relevant cells.

    Use placeholders to create unique, dynamic table names in the destination. Use the following placeholders:

    Placeholder

    Description

    {datastream_id}

    The datastream ID.

    {datastream_type}

    The Datastream Type.

    {extract_id}

    The data extract ID.

    {meta[*]}

    Replace * with a metadata placeholder to use metadata in the table name. For example, {meta[datastream_URI]} uses the datastream URI as the table name. For more information on metadata and placeholders, see Using placeholders.

    {name}

    The automatically generated filename of the data extract.

    {scheduled_day}

    The day when the data fetch was scheduled to run.

    {scheduled_month}

    The month when the data fetch was scheduled to run.

    {scheduled_year}

    The year when the data fetch was scheduled to run.

    Truncate

    Select this checkbox to delete all rows from the relevant table in the destination before transferring the latest data extract.

    Datastream

    Select this checkbox to overwrite data in the target table if both of these conditions are satisfied:

    • The data was previously transferred from this datastream. Data transferred from other datastreams is not overwritten.

    • The date ranges of the existing and the new data set overlap. Adverity overwrites existing data in the target table if it refers to the same dates as the new data from the datastream.

    For example, if the existing data in the target table refers to 10 January 2022 - 14 January 2022, and the data from the datastream refers to 13 January 2022 - 17 January 2022, then Adverity overwrites data in the target table for 13 January 2022 and 14 January 2022.

    If you select this checkbox, specify the column in your data extract that contains the dates in Date Range.

    Date Range

    Select the column in your data extract that contains the dates.

    Filename

    Select this checkbox to overwrite the relevant data in the destination if a data extract with the same filename already exists in the destination.

    Key Columns

    Select this checkbox to overwrite data in the destination based on the key columns defined in the Data Mapping of the datastream. Adverity executes this overwrite option after all the other overwrite options. When you select this checkbox, the configuration to overwrite data based on dates does not have an effect.

  2. Click Save.

Advanced SQL Database tips

Configuration

To configure the SQL Database destination, follow these steps:

  1. Select the workspace you work with in Adverity and then, in the platform navigation menu, click Destinations.

  2. Click the SQL Database destination in the list.

  1. In the secondary menu, click Configuration.

  2. Fill in the following fields:

    Load state table

    Select the checkbox to create a load state table. The load state table is a table in the destination which contains information about each data transfer. The load state table contains the following fields:

    Fieldname

    Description

    datastream_id

    datastream ID.

    datastream_name

    datastream name.

    datastream_url

    datastream URL.

    extract_filename

    Filename of the data extract.

    range_start

    Start date and time of the fetch.

    range_end

    End date and time of the fetch.

    uuid

    Unique ID of the data transfer to the target table.

    load_state

    State of the data transfer. The possible states are failed, finished, and running.

    load_start

    Date and time when the data transfer started.

    load_end

    Date and time when the data transfer finished.

    target_schema

    Data schema used in the target table.

    target_table

    Name of the target table.

    nrows

    Number of rows in the target table.

    ncols

    Number of columns in the target table.

    Name of load state table

    Enter a name for the load state table. The default name of a load state table is dt_loadstate.

    Options

    Specify the options for the database in JSON format.

    Default schema

    Specify the default schema used in the database.

  3. Click Save.

Technical details of transferring data to SQL Database

When transferring a data extract to SQL Database, Adverity creates the following additional columns in the target table:

dt_created

The date the data extract was created.

dt_updated

The date the data extract was last updated.

dt_filename

The automatically generated filename of the data extract.

In addition, Adverity creates a temporary table in SQL Database with the name _stage. This ensures that no partial updates are made to the database (guarantee of atomicity). Adverity deletes this temporary table after the data transfer is complete or has been aborted.

Troubleshooting: Data transfer to SQL Database fails after changing the table structure of the data extract

A data transfer to SQL Database may fail because of a change in the table structure of the data extract. To ensure the frictionless operation of production systems, Adverity only modifies existing tables in SQL Database if the changes are considered neutral, such as adding a new field to the table. Changes to the table structure of the data extract are not considered neutral. As a consequence, Adverity does not update the existing table in SQL Database resulting in failed data transfer.

The following actions change the table structure of the data extract:

  • You change the key columns in the datastream's Data Mapping. For more information on key columns, see Setting key columns.

  • You change the data type of a column in the datastream's Data Mapping. For more information on the data types used in Adverity, see Data types used in data harmonization.

  • You change the maximum character length of values in a column which contains String values.

To resolve this problem, follow these steps:

  1. In SQL Database, modify or drop the table that corresponds to the datastream.

  2. In Adverity, transfer data from the datastream to SQL Database.

Troubleshooting: Adverity cannot access SQL Database destination

If Adverity cannot access the SQL Database destination, the destination may restrict access based on IP address.

To resolve this issue, follow these steps:

  1. Find the IP address of your Adverity instance. To find the IP address of your Adverity instance, contact Adverity Customer Support.

  2. Add Adverity's IP address to the whitelist of your destination.