# Teradata Teradata

Source: https://userguide.qualytics.io/source-datastore/datastore/jdbc/teradata/

Adding and configuring a Teradata connection within Qualytics empowers the platform to build a symbolic link with your schema to perform operations like data discovery, visualization, reporting, syncing, profiling, scanning, anomaly surveillance, and more.

This documentation provides a step-by-step guide on adding Teradata as a source datastore in Qualytics. It covers the entire process from initial connection setup to testing and finalizing the configuration.

By following these instructions, enterprises can ensure their Teradata environment is properly connected with Qualytics, unlocking the platform's potential to help you proactively manage your full data quality lifecycle.

![teradata-connection-form](https://userguide.qualytics.io/assets/source-datastores/datastore/jdbc/teradata/overview/teradata-connection-form.png)

Let’s get started 🚀

## Teradata Setup Guide

Qualytics connects to Teradata through the **Teradata JDBC driver**. It uses JDBC metadata APIs to discover databases, tables, columns, and primary keys. Qualytics automatically filters out Teradata system databases (`DBC`, `SYSLIB`, `SYSSPATIAL`, `SYSUDTLIB`, `SystemFe`, `TDQCD`, `TDStats`, `TDPUSER`, `SYSUIF`, `All`, `Crashdumps`, `EXTUSER`, `LockLogShredder`, `SQLJ`, `SYSADMIN`, `SYSBAR`, `SYSJDBC`) during schema discovery.

### Minimum Teradata Permissions (Source Datastore)

| Permission | Purpose |
| --- | --- |
| `LOGON` | Allow the user to log on to the Teradata system |
| `SELECT ON <database_name>` | Read data from all tables for profiling and scanning |
| `SHOW ON <database_name>` | View object definitions (DDL) for metadata discovery |
| `SELECT ON DBC.DatabasesV` | Read database metadata for schema discovery |

> **Note**
>
> Qualytics cannot write to Teradata, so a Teradata datastore cannot be used as an enrichment datastore. Use an enrichment datastore on another connector instead.

### Example: Source Datastore User (Read-Only)

Replace `<database_name>` and `<password>` with your actual values.

```sql
-- Create a dedicated read-only user
CREATE USER qualytics_read AS
  PASSWORD = '<password>'
  PERM = 0
  SPOOL = 1000000000;

-- Grant logon access
GRANT LOGON ON ALL TO qualytics_read;

-- Grant read access to the target database
GRANT SELECT ON <database_name> TO qualytics_read;
GRANT SHOW ON <database_name> TO qualytics_read;
```

> **Tip**
>
> If using **LDAP authentication**, ensure the LDAP user has the same `SELECT` and `SHOW` privileges on the target database.

### Troubleshooting Common Errors

| Error | Likely Cause | Fix |
| --- | --- | --- |
| `Authentication failed` | Incorrect username or password | Verify the credentials and ensure the user exists in the Teradata system |
| `User does not have SELECT access` | The user lacks `SELECT` on the target database or table | Run `GRANT SELECT ON <database_name> TO <user>` |
| `User does not have SHOW access` | The user lacks `SHOW` on the target database | Run `GRANT SHOW ON <database_name> TO <user>` |
| `Connection refused` | The Teradata server is not reachable or the port is incorrect | Verify the host and port, and ensure the Teradata server allows connections from the Qualytics IP |
| `Database does not exist` | The database name provided in the connection form is incorrect | Verify the database name with `SELECT DatabaseName FROM DBC.DatabasesV` |

### Detailed Troubleshooting Notes

#### Authentication Errors

The error `Authentication failed` indicates that the credentials are incorrect.

Common causes:

- **Incorrect password**: the password does not match the one set for the user.
- **User does not exist**: the username was misspelled or does not exist in the Teradata system.
- **LDAP authentication**: if LDAP is enabled, the credentials must match the LDAP directory, not the Teradata internal user store.

> **Note**
>
> Teradata authentication can be configured to use internal, LDAP, or Kerberos mechanisms. Ensure the authentication method in the connection form matches the server configuration.

#### Permission Errors

The error `User does not have SELECT access` means the user authenticated successfully but lacks the necessary grants on the target database.

Common causes:

- **Missing `SELECT` on database**: the user does not have `SELECT` on the target database or specific tables.
- **Missing `SHOW` on database**: the user cannot view object definitions needed for metadata discovery.
- **Access to system databases**: the user is trying to access a filtered system database (e.g., `DBC`, `SYSLIB`).

#### Connection Errors

The error `Connection refused` means the Teradata server is not reachable from the Qualytics server.

Common causes:

- **Firewall**: a firewall is blocking connections on the Teradata port (default 1025).
- **Server not running**: the Teradata server is not started or is in a maintenance state.
- **Wrong host**: the hostname or IP address in the connection form is incorrect.

> **Tip**
>
> Start by confirming credentials are valid (authentication errors), then verify database permissions (permission errors), and finally check network connectivity (connection errors).

## Add a Source Datastore

A source datastore is a storage location Qualytics connects to so it can profile, scan, and monitor data. Adding Teradata as a source lets Qualytics query it through the Teradata JDBC driver and run quality operations on the tables it discovers.

Before you start, review the [Minimum Teradata Permissions](https://userguide.qualytics.io/source-datastore/datastore/jdbc/teradata/#minimum-teradata-permissions-source-datastore) the connecting user needs.

> **Warning: The destination lives on another connector**
>
> Qualytics cannot write to Teradata, so a Teradata datastore cannot be used as an enrichment datastore. Create one on a supported connector, then link it as the Teradata datastore's destination. See [Supported Connectors](https://userguide.qualytics.io/source-datastore/enrichment-datastore/supported-connectors/) for the list.

### Field reference

The **Add Datastore** page shows the sections below when Teradata is selected. When reusing an existing connection, the **Connection Properties** and **Secrets Management** sections come already filled in and read-only: Qualytics has already validated those credentials, so you fill in only the **Location** and the **General** fields. To change a saved connection's credentials, edit the connection through the [Manage Connections](https://userguide.qualytics.io/settings/connections/manage-connections/) page; edits there apply to every datastore that reuses the connection.

#### Connection Properties

These fields define the Teradata system Qualytics connects to and the account it connects with. They belong to the connection: when reusing an existing connection, they come already filled in and read-only.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Connection Name** | Yes | Text | A label for the saved connection (e.g., `acme_teradata_reporting`), so other datastores can reuse it later. |
| **Host** | Yes | Text | The hostname or address of the Teradata system. |
| **Port** | No | Number | The port the system accepts connections on. Left empty, the connection uses the default `1025`. |
| **Enable LDAP** | No | Checkbox | Turn it on when the account is authenticated by your directory service rather than by Teradata itself. |
| **User** | Yes | Text | The Teradata account Qualytics connects as. |
| **Password** | Yes | Text | The password for that account. |
| **Max Parallelization** | No | Number | Caps how many queries Qualytics runs at the same time against a datastore reached through this connection, from 1 to 100. Leave it empty for no explicit limit. The cap applies per datastore, so datastores sharing this connection each get their own allowance. Sits in the collapsed **Advanced** section of the form. See [Max Parallelization](https://userguide.qualytics.io/source-datastore/datastore/connection/how-it-works/#max-parallelization). |

#### Secrets Management

This group is optional: use it only if you want Qualytics to pull credentials from a secrets manager instead of typing them into the form. Turn on **HashiCorp Vault** to show the fields below. Despite the label, any secrets manager that exposes a compatible REST API works, not only HashiCorp Vault; see [HashiCorp Vault](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/introduction/). It also belongs to the connection: read-only when reusing an existing connection.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Login URL** | Yes | Text | The full URL of the login endpoint (e.g., `https://vault.example.com/v1/auth/approle/login`). With Vault namespaces, add the namespace after `/v1/`, as in `/v1/<namespace>/auth/approle/login`. |
| **Credentials Payload** | Yes | Text | A JSON body containing the credentials Vault expects (e.g., `{"role_id":"...","secret_id":"..."}`). |
| **Token JSONPath** | Yes | Text | The JSONPath that extracts the client token from Vault's response. Defaults to `$.auth.client_token`. |
| **Secret URL** | Yes | Text | The full URL of the secret, including `https://` and the host (e.g., `https://vault.example.com/v1/secret/data/teradata`). With Vault namespaces, add the namespace after `/v1/`. |
| **Token Header Name** | Yes | Text | The HTTP header name used to send the token. Defaults to `X-Vault-Token`. |
| **Data JSONPath** | Yes | Text | The JSONPath that extracts the key/value pairs from Vault's response. Use `$.data.data` for a KV version 2 secret (its API path contains `/data/`) and `$.data` for KV version 1 or the database secrets engine. The form pre-fills `$.data`. |

> **Note**
>
> Reference a key from the secret in any **Connection Properties** or **Authentication** field with `${key}`, for example `${password}`. Write it with braces (`${key}`, never `$.key`) and match the key name's case. Qualytics resolves it each time the connection is opened, so a changed value takes effect on the next connection. Setup steps, the namespace rule, and a troubleshooting page are on the [HashiCorp Vault](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/introduction/) pages.

#### Location

Pick the database or databases Qualytics should read from, and choose whether the connection is encrypted. You fill these in on both flows.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Use SSL** | No | Checkbox | Encrypt the connection to the Teradata system. Selected by default. Clear it only when the system does not accept encrypted connections, in which case the connection is made without encryption. |
| **Database** | Yes | Option | One or more Teradata databases to read from. Each database you pick becomes its own Qualytics datastore. Click the refresh icon to load the ones visible to the account. |

> **Note: Database is the schema**
>
> Teradata treats a database as the schema, so there is no separate catalog selection before it. The field is sent as the datastore's schema.

> **Note: One datastore per database**
>
> Selecting more than one database creates one source datastore per database, named from the **Name Template**. See [Multi-Schema Source Datastore Creation](https://userguide.qualytics.io/source-datastore/datastore/multi-schema/overview/) for details.

> **Note: System databases**
>
> Teradata's built-in system databases, such as `DBC`, `SYSLIB`, and `TDStats`, are left out of discovery, so they do not appear in the list.

#### General

Common fields for every source datastore, shown below the **Location** section. You fill these in on both flows.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Name Template** | No | Text | Defines the naming pattern for each source datastore being created. Use `{{schema}}` as a placeholder that gets replaced with the actual database name (e.g., `td_{{schema}}` becomes `td_sales`). Left empty, the datastore is named from the connection name and the database. |
| **Group** | No | Option | Organizes your datastores under a shared group in the navigation tree. Select an existing group or create a new one with the **Add New Group** toggle. |
| **Teams** | Yes | Option | Select one or more teams to associate with this source datastore. |
| **Initiate Sync** | No | Checkbox | Automatically sync the datastore to detect containers and fields after creation. |

Below the form, an information banner lists the **Public addresses** and **Private addresses** your datastore connections originate from. Allow the ones that match your network setup through your security groups or firewall rules; see [How Connections Work](https://userguide.qualytics.io/source-datastore/datastore/connection/how-it-works/#finding-the-addresses-to-allow) for where the addresses come from.

### Steps

There are two ways to set up the connection: reuse a connection you already saved (**Existing Connection**) or create a new one from scratch (**New Connection**). The tabs below walk through each option; pick the one you want to follow. Each field is described in the [Field reference](https://userguide.qualytics.io/source-datastore/datastore/jdbc/teradata/#source-field-reference) above.

**Tab: New Connection**

**Step 1**: Navigate to the **Datastores** page.

**Step 2**: Click the **Add**  button at the top-right corner and choose **Source** .

**Step 3**: The **Add Datastore** page opens.

**Step 4**: Select **New Connection** next to the **Search**  field.

**Step 5**: Select **Teradata** from the connector grid. Use the search field to filter connectors by name.

**Step 6**: Fill in the **Connection Properties**: the **Connection Name**, **Host**, **Port**, **User**, and **Password**, and turn on **Enable LDAP** if your account is authenticated by a directory service.

**Step 7**: Optionally, expand **Secrets Management** to retrieve credentials from a secrets manager.

**Step 8**: Fill in the **Location** fields (**Use SSL** and **Database**) and the **General** fields.

**Step 9**: Click **Test connection**. A success message confirms that the connection has been verified.

> **Info**
>
> The **Finish** and **Next** buttons stay disabled until the connection test passes on the current values. If the test fails, see [Troubleshooting Common Errors](https://userguide.qualytics.io/source-datastore/datastore/jdbc/teradata/#troubleshooting-common-errors).

**Step 10**: Click **Finish** to create the datastore.

> **Tip**
>
> To link a destination so Qualytics can write anomalies and metadata from the first operation, click **Next** instead of **Finish**. It has to live on a connector other than Teradata; see [Link Enrichment on Datastore Creation](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-during-creation/).

**Step 11**: A success dialog confirms that your datastore has been added. Click **Go to your datastore** to open its page.

**Tab: Existing Connection**

**Step 1**: Navigate to the **Datastores** page.

**Step 2**: Click the **Add**  button at the top-right corner and choose **Source** .

**Step 3**: The **Add Datastore** page opens.

**Step 4**: Select **Existing Connection** next to the **Search**  field.

**Step 5**: Select the saved Teradata connection from the grid. Use the search field to filter connections by name. The **Connection Properties** and **Secrets Management** sections come already filled in and read-only.

> **Tip: Start a new connection from this one**
>
> To use the selected connection as a starting point for a brand-new connection instead, click the **Duplicate as a new connection**  button on the selected connection. The form switches to **New Connection** mode with the connection's settings already filled in for you to adjust.

**Step 6**: Fill in the **Location** fields (**Use SSL** and **Database**) and the **General** fields. These are the only fields left to fill in.

**Step 7**: Click **Test connection**. A success message confirms that the connection has been verified.

> **Info**
>
> The **Finish** and **Next** buttons stay disabled until the connection test passes on the current values. If the test fails, see [Troubleshooting Common Errors](https://userguide.qualytics.io/source-datastore/datastore/jdbc/teradata/#troubleshooting-common-errors).

**Step 8**: Click **Finish** to create the datastore.

> **Tip**
>
> To link a destination so Qualytics can write anomalies and metadata from the first operation, click **Next** instead of **Finish**. It has to live on a connector other than Teradata; see [Link Enrichment on Datastore Creation](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-during-creation/).

**Step 9**: A success dialog confirms that your datastore has been added. Click **Go to your datastore** to open its page.

## API Payload Examples

### Creating a Source Datastore

This section provides a sample payload for creating a datastore. Replace the placeholder values with actual data relevant to your setup.

**Endpoint (Post):** `/api/datastores (post)`

**Tab: Creating a source datastore with a new connection**

```json
{
    "name": "your_datastore_name",
    "teams": ["Public"],
    "schema": "schema_name",
    "enrichment_only": false,
    "trigger_sync": true,
    "connection": {
        "name": "your_connection_name",
        "host": "teradata_host",
        "port": 1025,
        "username": "teradata_user",
        "password": "teradata_password",
        "type": "teradata"
        }
}
```

**Tab: Creating a datastore with an existing connection**

```json
{
    "name": "your_datastore_name",
    "teams": ["Public"],
    "schema": "schema_name",
    "enrichment_only": false,
    "trigger_sync": true,
    "connection_id": 123
}
```

**Tab: Create a Source Datastore using the CLI**

```bash
# Step 1: Create a Connection
qualytics connections create \
    --type teradata \
    --name "your_connection_name" \
    --host ${TERADATA_HOST} \
    --port 1025 \
    --username ${TERADATA_USER} \
    --password ${TERADATA_PASSWORD}

# Step 2: Create a Source Datastore
qualytics datastores create \
    --name "your_datastore_name" \
    --connection-name "your_connection_name" \
    --schema dbc
```

> **Note: Use SSL**
>
> The payloads above leave **Use SSL** at its default, so the connection is encrypted. To connect
> to a system that does not accept encrypted connections, send `ssl` as `"false"` under the
> connection's `parameters`:
>
> ```json
> {
>     "connection": {
>         "name": "your_connection_name",
>         "host": "teradata_host",
>         "port": 1025,
>         "username": "teradata_user",
>         "password": "teradata_password",
>         "type": "teradata",
>         "parameters": {
>             "ssl": "false"
>         }
>     }
> }
> ```

### Link an Enrichment Destination

**Endpoint Patch:**

`/api/datastores/{datastore-id}/enrichment/{enrichment-id} (patch)`

*Last updated: November 3, 2026.*