Connect Amperity Bridge to Amazon Redshift

Amperity Bridge for Amazon Redshift lets you use approved Amazon Redshift tables and views as the data surface for the data that you send to Amperity. Your team defines the schemas, tables, and views that Amperity may access, and Amperity ingests from those approved objects on a schedule, without requiring you to build or maintain a separate file export or feed pipeline.

Early access

Amperity Bridge for Amazon Redshift is available as an inbound-only connection, offered to select customers as part of early access. Outbound support–writing data from Amperity to Amazon Redshift–is not available. Contact your Amperity representative to learn more.

Important

Amperity Bridge for Amazon Redshift performs full-table and full-view exports by default. A table or view that has a primary key and a version column may be configured for incremental sync instead.

Review the limitations before you configure a bridge.

How it works

Amperity Bridge for Databricks, Google BigQuery, and Snowflake connects through each platform’s native data-sharing protocol. Amperity Bridge for Amazon Redshift is different. It uses an UNLOAD export pattern:

1. Amperity schedules and orchestrates the inbound bridge run.

2. Amperity uses an approved, role-based access path to run a query against your Amazon Redshift using the Amazon Redshift Data API.

3. Amazon Redshift unloads the result set of the configured table or view to the storage for your Amperity tenant.

4. Amperity ingests the exported files into your Amperity source and domain tables.

Because the compute for the export runs in your Amazon Redshift, you retain visibility into query history and workload impact, and you control what Amperity can query through standard Amazon Redshift grants.

Area	Behavior
Query and export pattern	Amperity runs an UNLOAD statement from your Amazon Redshift to the storage for your Amperity tenant.
Where compute runs	The query and the export run on your Amazon Redshift compute, which means that they appear in your query history and in your billing.
Data surface	The bridge reads from the Amazon Redshift tables and views that you approve. You determine which objects are exposed to Amperity.
Row and column selection	The bridge uses SELECT * against the configured table or view. An incremental run adds a WHERE clause on the version column. To expose a subset of rows or columns, create a view and expose that view instead of the base table.
Load behavior	Full load by default. Each run expects the configured object to represent the complete data set that Amperity should load. A table or view may be configured for incremental sync instead. Each run then unloads only the rows whose version column advanced since the previous sync, and Amperity merges those rows into the existing domain table by primary key.
Deployment models	Both provisioned clusters and Serverless workgroups are supported.
Encryption	Exported objects use server-side encryption with AES256.

Data types

Most Amazon Redshift data types are supported by Amperity Bridge.

Important

If an upstream data type changes, edit the bridge in Amperity, accept the changes, and then save and sync the bridge.

Note

GEOGRAPHY, GEOMETRY, HLLSKETCH, INTERVAL, and VARBYTE data types are unsupported.

The following table describes how Amazon Redshift data types map to Amperity data types.

Amazon Redshift data type	Amperity data type
BIGINT A signed eight-byte integer. Note Synonymous with INT8.	Integer A numeric value, such as the quantity of items purchased. For example: 1 12345
BOOLEAN A value that can be TRUE, FALSE, or NULL. Note Synonymous with BOOL.	Boolean A value that can be TRUE, FALSE, or NULL.
CHAR A fixed-length character string that is padded with blanks. Default length is 1. Maximum length is 4096 bytes. Note Synonymous with BPCHAR, CHARACTER, and NCHAR.	String A string of characters.
DATE Calendar date values with no time element.	Date An ISO-8601 compliant date value, such as a birthdate. For example: 2021-11-04
DECIMAL (p,s) A number with a specified precision and scale. Precision is 1-38 and scale is the number of digits to the right of the decimal point. Default precision and scale is (18,0). Note Synonymous with NUMERIC. Important The precision and scale of the Amazon Redshift column are carried through to Amperity. A decimal column that does not report both a precision and a scale cannot be synced.	Decimal (p,s) A fixed point number, such as for prices or message sizes. The number of characters in the decimal value is configurable. For example: 1.50 (prices) 1874.380 (message sizes) 141.48042 (order subtotals)
DOUBLE PRECISION A double-precision (64 bit) floating-point number. Note Synonymous with DOUBLE, FLOAT, and FLOAT8.	Float A floating point number. For example: 3.14 3.14159
GEOGRAPHY A collection of points, linestrings, and polygons that represent a set or subset of the surface of the Earth.	Warning The Amazon Redshift GEOGRAPHY data type is unsupported. Exclude fields with GEOGRAPHY data types from tables before sharing them with Amperity.
GEOMETRY A pairs of real numbers that represent features in a planar–Euclidean and Cartesian–coordinate system.	Warning The Amazon Redshift GEOMETRY data type is unsupported. Exclude fields with GEOMETRY data types from tables before sharing them with Amperity.
HLLSKETCH A HyperLogLog sketch that is used to estimate the number of distinct values in a data set.	Warning The Amazon Redshift HLLSKETCH data type is unsupported. Exclude fields with HLLSKETCH data types from tables before sharing them with Amperity.
INTEGER A signed four-byte integer. Note Synonymous with INT and INT4.	Integer A numeric value, such as the quantity of items purchased. For example: 1 12345
INTERVAL Intervals of time on a scale of years to months or days to seconds. Note Includes INTERVAL DAY TO SECOND and INTERVAL YEAR TO MONTH.	Warning The Amazon Redshift INTERVAL data type is unsupported. Exclude fields with INTERVAL data types from tables before sharing them with Amperity.
REAL A single-precision (32 bit) floating-point number. Note Synonymous with FLOAT4.	Float A floating point number. For example: 3.14 3.14159
SMALLINT A signed two-byte integer ranging from -32,768 to 32,767. Note Synonymous with INT2.	Integer A numeric value, such as the quantity of items purchased. For example: 1 -12345
SUPER A SUPER value stores semi-structured data, including arrays, structures, and scalar values.	String A string of characters. Note A SUPER value is schemaless–its shape may vary from row to row–and does not map to a nested Amperity data type. Use a view or a custom domain table to cast or coerce the fields within a SUPER value to supported Amperity data types.
TIME Time data stored as HH:MI:SS without a time zone. Note Synonymous with TIME WITHOUT TIME ZONE.	String A string of characters that represents HH:MI:SS time data.
TIMESTAMP Date and time values without a time zone. Note Synonymous with TIMESTAMP WITHOUT TIME ZONE.	Datetime ISO-8601 compliant date and time values, such as a purchase or transaction, the time at which data was last updated, or a campaign launch date. For example: Mon Nov 30 2020 16:00:00 GMT-0800 (Pacific Standard Time) Sat Sep 02 2017 14:36:19 GMT-0700 (Pacific Daylight Time)
TIMESTAMPTZ Date and time values with a time zone. Note Synonymous with TIMESTAMP WITH TIME ZONE. Important The time zone offset is dropped when a TIMESTAMPTZ value is synced to Amperity.	Datetime ISO-8601 compliant date and time values, such as a purchase or transaction, the time at which data was last updated, or a campaign launch date. For example: Mon Nov 30 2020 16:00:00 GMT-0800 (Pacific Standard Time) Sat Sep 02 2017 14:36:19 GMT-0700 (Pacific Daylight Time)
TIMETZ Time data stored as HH:MI:SS with a time zone. Note Synonymous with TIME WITH TIME ZONE.	String A string of characters that represents HH:MI:SS time data with a time zone offset.
VARBYTE A variable-length binary value. Default length is 64000 bytes. Maximum length is 16777216 bytes. Note Synonymous with BINARY, BINARY VARYING, and VARBINARY.	Warning The Amazon Redshift VARBYTE data type is unsupported. A table that includes a VARBYTE column fails when the bridge runs its export. Amperity Bridge reads a Redshift table by unloading it to Parquet, and Amazon Redshift can only unload VARBYTE columns to text or CSV format . Exclude the column, or use a view or a custom domain table to coerce it to a supported Amperity data type before sharing it with Amperity Bridge. For example, use FROM_VARBYTE to return the column as a string: SELECT customer_id ,first_name ,last_name ,FROM_VARBYTE(email_bytes, 'utf8') AS email ,FROM_VARBYTE(phone_bytes, 'utf8') AS phone FROM binary_table
VARCHAR A variable-length character string. Default length is 256 bytes. Maximum length is 65535 bytes. Note Synonymous with CHARACTER VARYING, NVARCHAR, and TEXT.	String A sequence of characters, such as first and last names, email addresses, physical addresses, UUIDs and other IDs, phone numbers, ZIP codes, product names, and descriptions. May be empty. For example: John Smith John Smith johnsmith @ domain.com 123 Main Street 206-555-1111 00002ac0-0915-3cb4-b7c7-5ee192b3bd49 ACME pants “A data source that pulls from an Amazon S3 bucket.”

Incremental sync

Every table and view that is mapped by the bridge syncs in Full mode by default. Each run unloads the entire object and replaces the contents of the Amperity domain table.

A table or view may be configured to sync in Incremental mode instead. An incremental run unloads only the rows whose version column advanced since the previous sync, and then merges those rows into the existing domain table by primary key. When a row in the increment has the same primary key as a row that is already in the domain table, the row with the higher version value wins; when the two versions are equal, the newly read row wins.

Incremental sync suits large objects that change in place–such as transaction, order, and interaction history–where unloading the whole object on every run is expensive on your Amazon Redshift compute.

Note

Incremental sync is enabled per tenant. Contact your Amperity representative to have it enabled. Until it is, the Sync mode options are not shown and every table and view syncs in Full mode.

Per-table settings

Sync mode is configured for each table and view individually, during the table mapping step of adding a bridge or by editing a saved bridge. A table or view that is set to Incremental requires the following settings.

Setting	Details
Sync mode	Full or Incremental. A table or view that is set to Full unloads in its entirety on every run and ignores the remaining settings.
Primary key	The column, or the combination of columns, that uniquely identifies a row in the Amazon Redshift table or view. This is what the merge matches on. Select more than one column when no single column identifies a row. See composite primary keys. Important The key must identify exactly one row. A full load copies duplicate keys into the domain table as it finds them, and an incremental run then applies the update to every copy, so the duplicates persist. A Primary key column must map to an Amperity String, Integer, Date, or Datetime data type. Columns of other types are not offered. When the mapped domain table already has a primary key of its own–such as a custom domain table–Amperity merges on that key and shows it instead of asking for one.
Version column	A column whose value, whenever a row is inserted or updated, is higher than every value already in the table–not merely higher than that row’s own previous value. An updated-at timestamp or a table-wide sequence number works. Amperity reads the highest value that is already in the domain table, subtracts the lookback window, and unloads only the rows beyond that point. A row whose version does not advance past that bound when the row is updated is not picked up by an incremental run. A Version column must map to an Amperity Integer or Datetime data type. A Date column may not be used as a version column. Important Do not use a nullable column, or a per-row revision counter, as the version column. A null is never unloaded by an incremental run, because it fails the comparison against the lower bound, so the row is missed until the table is re-read in full. When an updated-at column stays null until a row is first updated, sync a view that falls back to the row’s creation time instead–for example, COALESCE(updated_at, created_at)–and point the bridge at that view. A per-row revision counter does not work, because the bound is the highest version in the whole table. Once any row reaches revision 500, an update that takes another row from revision 2 to 3 is below the bound and is never read. A version value that is dated in the future fails the same way. Each run starts from the highest version that Amperity holds, so a single future-dated row raises the bound past the rows that follow it, and later runs skip real changes until the table is re-read in full.
Lookback	How far behind the highest known version each run re-reads, so that rows that arrived late at the source are not missed. Re-read rows merge harmlessly. For a Datetime version column, the lookback is a duration, such as 15 minutes, 12 hours, or 3 days. The default is one day. Select None for no lookback. For an Integer version column, the lookback is a plain number in the units of the column itself, and it is required. There is no default.

Tip

When a table or view has no column of a supported type, create a view that casts one, grant SELECT on that view, and point the bridge at it. For example, cast a Decimal order ID to BIGINT to use it as a primary key, or cast a Date updated-on column to TIMESTAMP to use it as a version column.

A Date carries no time of day, so a version column cast from one advances only once a day. Use a lookback of at least one day.

Composite primary keys

A primary key may span more than one column. Select every column that is required to identify a row uniquely–for example, an order line that is identified by an order ID together with a line number.

Behavior	Details
Matching	A row in the increment matches a row in the domain table only when every key column is equal.
Nulls	A key column may contain nulls, and a null matches only another null. Rows with null key components are merged rather than dropped.
Column order	The order in which the columns are selected does not matter. Amperity stores the key in a consistent order.
Changing the key	Changing the columns in the primary key of a saved bridge causes the next run of that table to sync in full. The run after that merges again.

When an incremental table syncs in full

A table or view that is configured for Incremental still unloads in its entirety under any of the following conditions. In each case the run is a complete and correct load, and the run after it merges again.

Condition	Details
First sync	There is nothing in Amperity to merge into yet.
The domain table is empty	There is no version value to read a starting point from.
The primary key or the version column changed	The contents that are already in Amperity were assembled under the previous key or version column, so they are re-read once under the new one.
A schema change was accepted	After a schema change is accepted on the bridge, the affected table is re-read once so that its contents match the new schema.
A full re-read was requested	See re-read a table in full.

Re-read a table in full

An incremental table may be re-read in its entirety for a single run, without changing how it is configured. Do this to pick up rows that were deleted at the source, or rows that arrived with a version older than the lookback window.

To re-read a table in full

	In Amperity, go to Sources and then, under Inbound share, select the Amazon Redshift bridge.
	From the ellipses menu, select Sync. Amperity lists every table and view that is configured for incremental sync.
	Set the Sync mode to Full for each table that should be re-read in its entirety, and then select Sync.

The choice applies to that run only. The configuration of the table is unchanged, and the next run merges again.

From Amazon Redshift

A connection between Amazon Redshift and Amperity brings tables from your Amazon Redshift account into Amperity as domain tables. It requires configuration steps to be made in both Amperity and Amazon Redshift.

Amperity accesses tables in your Amazon Redshift account using two IAM roles that you create. Amperity reaches your catalog through the first; your Amazon Redshift writes the exported data through the second.

Role	Who assumes it	What it does
Query role	Amperity	Reads your catalog–databases, schemas, and tables–and issues the UNLOAD statements that retrieve data.
Unload role	Amazon Redshift, on your behalf	Chains into the Amperity storage role so that Amazon Redshift can write the exported data to the storage for your Amperity tenant.

1. Get details

2. Configure Amazon Redshift

3. Add inbound bridge

Get details

Before you configure the bridge, gather the following from your AWS and Amazon Redshift environment.

Category	Information needed	Why it matters
AWS and Amazon Redshift environment	The AWS account ID; the cluster identifier or Serverless workgroup name; the database name; the region.	Identifies the source environment and confirms the region and connectivity requirements.
Approved data objects	The schema names; the table and view names; any column exclusions, row filters, or masking that is applied by a view.	Defines exactly what data Amperity can access.
Amazon S3 landing location	Whether you are using Bring Your Own Storage (BYOS) or storage that is managed by Amperity.	Determines where the UNLOAD output lands and who manages the access policy for that bucket.
Schedule and volume	The expected export cadence; the approximate table sizes and row counts.	Supports performance planning and helps size your first sync.
Operational owner	Who owns IAM, Amazon Redshift grants, and troubleshooting on your side.	Gives Amperity a contact for schema changes and incident triage.

Configuration responsibilities

Amperity Bridge for Amazon Redshift is self-service. Configuration is split between the values that Amperity provides and the resources that you create in your AWS account.

Amperity provides	Your team configures
The Amperity query role. The External ID. The Amperity storage role. See Values from Amperity.	The Amazon Redshift schemas, tables, and views that Amperity may access. The query role. The unload role. The database permissions and grants. The database user, for a provisioned cluster.

Values from Amperity

The values that you need to write the IAM policies are specific to your tenant. Amperity shows them at the start of the bridge flow.

Open the Sources page. Under Inbound shares click Add bridge, choose Amazon Redshift, choose Create new bridge, and then give the bridge a name.

The dialog box displays three copyable values.

Value	Use it for
Amperity query role	The principal that your query role must trust.
External ID	Your query role should allow only principals with this external ID to assume it.
Amperity storage role	The role that your unload role is given permission to assume.

Important

Copy all three values before continuing.

Configure Amazon Redshift

To configure Amazon Redshift to connect with Amperity you need to create the query role and the unload role in the AWS account that owns your Amazon Redshift, attach the unload role to your cluster or workgroup, and then grant read access within Amazon Redshift to the identity that the queries run as. On a provisioned cluster you must also create the database user that the queries run as.

Note

IAM gets Amperity as far as the cluster. It grants no access to any data. Access to data is granted inside Amazon Redshift, as described in Grant database access.

Note

Bring Your Own Storage (BYOS)

These instructions describe Amperity-managed storage, where your unload role chains into the Amperity storage role that Amperity provides. If your tenant uses Bring Your Own Storage, the storage role lives in your own AWS account and you manage its trust yourself. See Provision storage on Amazon AWS, and work with your Amperity representative for the BYOS storage-role details.

Create the database user (provisioned cluster only)

This step applies only if you are using a provisioned cluster. On a provisioned cluster the queries run as a named Amazon Redshift database user. Amperity does not create it, so create it now. The name that you choose goes into the permission policy for the query role in the next step.

Connect to your cluster as a superuser through the Query editor v2 in the Amazon Redshift console, and then run the following. Modify the name to what you want, but use all lowercase characters.

CREATE USER amperity PASSWORD DISABLE;

Note

You can set a real password by replacing DISABLE with the password that you want. Nothing about the integration changes. Amperity is never given the password and never uses it.

A password would only let someone log in as this user directly, which is not needed for the bridge, which is why Amperity recommends DISABLE.

Create the query role

In the AWS account that owns your Amazon Redshift, create an IAM role for Amperity to assume.

Important

The name of the query role must start with AmperityRedshiftBridge, such as AmperityRedshiftBridgeQuery.

The Amperity role that assumes it is permitted to assume only roles named this way. A role whose name starts with anything else is rejected when you enter its ARN, and a role that is renamed later fails at sync time.

The role must also sit at the root of the path–arn:aws:iam::123456789012:role/AmperityRedshiftBridgeQuery. An ARN with a path, such as role/my-team/AmperityRedshiftBridgeQuery, is rejected.

Trust policy

Substitute the Amperity query role and External ID that you copied from the values that Amperity provides.

Important

Trust the query role ARN exactly as it is given, rather than the whole Amperity account.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AmperityQueryRoleAssume",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<AMPERITY_QUERY_ROLE_ARN>"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<AMPERITY_EXTERNAL_ID>"
        }
      }
    }
  ]
}

Permission policy: Redshift Serverless

Attach this policy for a Serverless workgroup. Replace <REGION> with the region that your Amazon Redshift runs in and <YOUR_ACCOUNT_ID> with the 12-digit AWS account that owns it. <WORKGROUP_UUID> is the workgroup’s UUID from its ARN, and not its name.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Execute",
      "Effect": "Allow",
      "Action": [
        "redshift-data:ListDatabases",
        "redshift-data:ListTables",
        "redshift-data:DescribeTable",
        "redshift-data:ExecuteStatement",
        "redshift-serverless:GetCredentials"
      ],
      "Resource": "arn:aws:redshift-serverless:<REGION>:<YOUR_ACCOUNT_ID>:workgroup/<WORKGROUP_UUID>"
    },
    {
      "Sid": "ReadResult",
      "Effect": "Allow",
      "Action": [
        "redshift-data:DescribeStatement",
        "redshift-data:GetStatementResult"
      ],
      "Resource": "*"
    }
  ]
}

Permission policy: provisioned Redshift instance

Attach this policy instead for a provisioned cluster. Replace <REGION> with the region that your Amazon Redshift runs in and <YOUR_ACCOUNT_ID> with the 12-digit AWS account that owns it. <CLUSTER_IDENTIFIER> is your cluster’s identifier, <DATABASE> is the database that you connect through, and <DB_USER> is the database user that you created.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ExecuteCluster",
      "Effect": "Allow",
      "Action": [
        "redshift-data:ListDatabases",
        "redshift-data:ListTables",
        "redshift-data:DescribeTable",
        "redshift-data:ExecuteStatement",
        "redshift:GetClusterCredentials"
      ],
      "Resource": [
        "arn:aws:redshift:<REGION>:<YOUR_ACCOUNT_ID>:cluster:<CLUSTER_IDENTIFIER>",
        "arn:aws:redshift:<REGION>:<YOUR_ACCOUNT_ID>:dbuser:<CLUSTER_IDENTIFIER>/<DB_USER>",
        "arn:aws:redshift:<REGION>:<YOUR_ACCOUNT_ID>:dbname:<CLUSTER_IDENTIFIER>/<DATABASE>"
      ]
    },
    {
      "Sid": "ReadResult",
      "Effect": "Allow",
      "Action": [
        "redshift-data:DescribeStatement",
        "redshift-data:GetStatementResult"
      ],
      "Resource": "*"
    }
  ]
}

Note

DescribeStatement and GetStatementResult are keyed by statement ID rather than by a resource ARN, which is why AWS requires them on “*”.

Create the unload role

Create a second IAM role in the same AWS account. You can name this anything you like.

Trust policy

Attach this policy for this role. Replace <YOUR_ACCOUNT_ID> with the 12-digit AWS account that owns your Amazon Redshift, which is the same account that you are creating these roles in.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RedshiftAssume",
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "redshift-serverless.amazonaws.com",
          "redshift.amazonaws.com"
        ]
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<YOUR_ACCOUNT_ID>"
        }
      }
    }
  ]
}

Permission policy

Attach this policy for this role. Substitute the Amperity storage role that you copied from the values that Amperity provides. This is the role’s only permission. It holds no storage access of its own and reaches storage by chaining.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AssumeAmperityStorageRole",
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "<AMPERITY_STORAGE_ROLE_ARN>"
    }
  ]
}

Attach the role to your Amazon Redshift

Important

This step is required. Amazon Redshift can only use IAM roles that are associated with it, so a correctly written role that is not attached still fails at UNLOAD time.

Associate the unload role using the Amazon Redshift console:

• For a provisioned cluster, open your cluster, and then from the Actions menu select Manage IAM roles.

• For a Serverless workgroup, open your namespace, and then under Security and encryption select Manage IAM roles.

Grant database access

IAM gets Amperity as far as the cluster. It grants no access to any data. That is granted inside Amazon Redshift, to the database identity that the queries run as.

Which identity to grant to

Deployment	Identity
Provisioned cluster	The database user that you created, which is the same one that you enter as the Database user when you add the inbound bridge.
Serverless	Amazon Redshift derives the identity from the query role that Amperity assumes and names it “IAMR:<QUERY_ROLE_NAME>”.

Grant the reads

The statements are the same for both deployments. Only the grantee differs. Run them as a superuser or as the owner of the objects, once per schema and once per table that you intend to sync.

On a provisioned cluster the grantee is simply your database user.

GRANT USAGE ON SCHEMA <SCHEMA> TO <DB_USER>;
GRANT SELECT ON <SCHEMA>.<TABLE_OR_VIEW> TO <DB_USER>;

On Serverless the identity name contains a colon, which is why Amazon Redshift requires it in double quotes.

GRANT USAGE ON SCHEMA <SCHEMA> TO "IAMR:<QUERY_ROLE_NAME>";
GRANT SELECT ON <SCHEMA>.<TABLE_OR_VIEW> TO "IAMR:<QUERY_ROLE_NAME>";

Grant only what you want Amperity to see. Amperity can read exactly what this identity can read, and nothing more. If you want Amperity to have access to only a subset of the columns on a particular table, consider creating a view that exposes only those columns, and granting SELECT on the view instead of the table.

Note

Metadata security

If your Amazon Redshift cluster or workgroup has metadata security enabled, the query identity also needs the ACCESS CATALOG permission–or a database role that carries it–before Amperity can read your table schemas. Without it, catalog reads fail even after USAGE and SELECT have been granted.

Important

External table access

If some of your Amazon Redshift tables are external tables rather than standard internal tables, be aware that permission management for external tables is less fine-grained. Amazon Redshift grants access to external tables, such as Amazon Redshift Spectrum or external schemas, at the schema level and not per table. This means that you will not be able to expose a single external table without granting access to the entire schema, which may be inconvenient.

Workaround: create a view that selects only the intended external table, and then grant Amperity SELECT permission on the view instead, to keep exposure scoped.

How much to grant

Grant only the schemas and objects that you plan to sync. You do not have to open up every database on the cluster. Amperity lists the databases that this identity can read and skips the rest.

You can widen the grants later. New ones are picked up the next time that Amperity reads your catalog.

Add inbound bridge

Configure an inbound bridge to connect Amazon Redshift with Amperity.

To add an inbound bridge

	In Amperity, go to Sources and add a new Amazon Redshift bridge.
	Enter your connection and IAM details: select the Deployment (provisioned cluster or Serverless workgroup); enter the Region, the Cluster identifier or Workgroup name, and the Database, plus the Database user for a provisioned cluster; then enter your AWS account ID, the Query role ARN you created–whose role name must start with AmperityRedshiftBridge–and the Unload role name you created.
	Select Save and continue. Amperity validates the query role, external ID, and network path by reading your Amazon Redshift catalog through the connection.
	Discover the approved schemas, tables, and views, and select the objects that you want to bring into Amperity.
	Map each selected object to an Amperity source or domain table. When incremental sync is enabled for your tenant, set the Sync mode for each object. An object that is set to Incremental also requires a Primary key and a Version column.
	Save the bridge. Amperity schedules and runs the sync, and shows run status, runtime, and any errors on the bridge’s detail page.

Once saved, the bridge runs alongside any other bridges or couriers that you already use. You do not need to migrate everything to Amperity Bridge for Amazon Redshift at once.

Note

Amperity does not assign primary keys to the domain tables that the bridge creates. Use a custom domain table to assign primary keys, apply semantic tags, and shape the data to support any of your Amperity workflows.

The Primary key that incremental sync merges on is a setting on the bridge and does not assign a primary key to the domain table. When the mapped domain table does have a primary key of its own, incremental sync merges on that key.

Tip

Amperity recommends starting with one to three representative tables or views, including at least one higher-volume feed, to validate Amazon Redshift query runtime, UNLOAD duration, ingestion timing, and workload impact before expanding further.

To Amazon Redshift

Amperity Bridge for Amazon Redshift supports inbound data into Amperity only. An outbound bridge–writing data from Amperity to Amazon Redshift–is not available.

Contact your Amperity representative if outbound Amazon Redshift connectivity is required for your use case.

Limitations

Amperity Bridge for Amazon Redshift has the following limitations.

Limitation	Details
Full loads by default	Each configured table or view must represent the complete data set that Amperity should load during that run, unless it is configured for incremental sync.
Incremental sync does not pick up deletes	A row that is deleted at the source stays in the Amperity domain table, and so does a row that arrives with a version older than the lookback window. Re-read the table in full to pick up either one.
A null version column is never read incrementally	A row whose version column is null fails the comparison that selects the increment, so it is never unloaded by an incremental run. Use a version column that is never null.
Not every column may be a primary key or a version column	A Primary key column must map to an Amperity String, Integer, Date, or Datetime data type, and a Version column must map to an Amperity Integer or Datetime data type. See per-table settings.
Schema changes require the bridge to be re-saved	If columns are added, removed, or renamed on a table or view that is used by the bridge, syncs may fail until the bridge is reopened and saved again. Row-level logic behind a view–such as filters, masking, or business logic–can be changed without affecting the bridge, as long as the exposed column schema stays the same.
SELECT * semantics	The bridge reads the full result set of the configured object, apart from the WHERE clause that an incremental run adds on the version column. To expose a subset of rows or columns, create a view and point the bridge at that view.
Your compute is used	The query and the UNLOAD statement run on your Amazon Redshift compute. Your team should monitor the workload and the associated Amazon Redshift costs.
Cross-region transfer costs may apply	If your Amazon Redshift and the storage that is used by your Amperity tenant are in different AWS regions, AWS cross-region data transfer charges may apply.
Outbound is not available	Amperity Bridge for Amazon Redshift supports inbound data into Amperity only.

Frequently asked questions

Question	Answer
Does the bridge support incremental loads?	Yes, per table and view. A table or view that is configured for incremental sync unloads only the rows whose version column advanced since the previous sync, and Amperity merges those rows into the existing domain table by primary key. Everything else unloads in full on every run.
May the primary key span more than one column?	Yes. Select every column that is required to identify a row uniquely. A row in the increment matches a row in the domain table only when every key column is equal, and a null matches only another null. See composite primary keys.
What happens to rows that are deleted in Amazon Redshift?	An incremental run does not pick them up, because a deleted row has no version value to advance. Re-read the table in full to bring the domain table back in line with the source.
Can I change which rows are included without reconfiguring the bridge?	Yes. You can update the row filters or the business logic behind an approved view without re-registering the bridge, as long as the exposed column schema does not change.
Can Amperity ingest directly from Amazon S3 instead of Amazon Redshift?	Direct Amazon S3 ingestion may be available for some architectures. Amperity Bridge for Amazon Redshift is designed for the case where you want Amperity to read directly from approved Amazon Redshift tables and views, and to have Amazon Redshift perform the export.
Can I use this bridge alongside other bridges and ingestion methods?	Yes. You can use Amperity Bridge for Amazon Redshift for selected feeds and continue to use other bridges or file-based ingestion for others.
Who pays for the Amazon Redshift compute?	The query and the UNLOAD statement run on your Amazon Redshift compute, which means that your team should monitor and budget for that workload.
Does Amazon Redshift query history show what Amperity users query inside Amperity?	No. It shows the export query that the bridge generates, which is a SELECT * against the approved table or view as part of the UNLOAD statement. An incremental run adds a WHERE clause on the version column.
What encryption is used for exported files?	Exported objects use server-side encryption with AES256.
Is an outbound bridge available?	No. Amperity Bridge for Amazon Redshift supports inbound data into Amperity only. Contact your Amperity representative if outbound Amazon Redshift connectivity is required for your use case.