Connect Amazon Redshift¶

Connect a customer-owned calibration view from a provisioned Redshift cluster or Redshift Serverless workgroup. Squoosh reads your aggregate counts through the Redshift Data API; you decide how those counts are computed.

This connector has not been validated against a live account. It ships at the authentication stage, with fixture-tested snapshot parsing. It is not eligible to ground AI shoppers or receive unattended snapshot refreshes until live validation and promotion are complete.

What the connection does¶

Squoosh verifies access by selecting dimension, bucket, and sessions from the view with LIMIT 1. A snapshot uses the same three columns with LIMIT 10001. It follows all result pages and refuses a view with more than 10,000 rows. It never discovers your schema or chooses source tables for you.

Each served dimension is tagged self-reported because your SQL defines what was counted. Duplicate dimension/bucket rows are summed. Counts must be non-negative safe integers, including when Redshift returns them as decimal strings. Missing dimensions stay absent with warnings. A conversion rate requires a positive session denominator, taken from device rows, otherwise geography, otherwise channel. A real zero conversion count is preserved; a missing conversion row produces no rate.

Prepare your view¶

In the Amazon Redshift console → Query editor v2, connect to the intended database. Have your data owner build the view using the CSV template columns. Every dimension and conversion total must cover the same last 28 full UTC days, excluding today. If you use a different window, change the view and Squoosh's View window in days together.

This illustrative SQL assumes a table named reporting.session_facts with one row per session, a UTC session_started_at timestamp, canonical device/country/channel labels, and a boolean converted. Replace those source names and definitions with your own. Squoosh does not create or execute this setup SQL.

CREATE OR REPLACE VIEW public.squoosh_calibration AS
WITH bounds AS (
  SELECT DATE_TRUNC(
    'day', CONVERT_TIMEZONE(CURRENT_SETTING('timezone'), 'UTC', SYSDATE)
  ) AS until_utc
), window_sessions AS (
  SELECT s.*
  FROM reporting.session_facts s CROSS JOIN bounds b
  WHERE s.session_started_at >= b.until_utc - INTERVAL '28 days'
    AND s.session_started_at < b.until_utc
)
SELECT 'device' AS dimension, device_category AS bucket,
       COUNT(DISTINCT session_id) AS sessions
FROM window_sessions GROUP BY device_category
UNION ALL
SELECT 'geo', country_iso2, COUNT(DISTINCT session_id)
FROM window_sessions GROUP BY country_iso2
UNION ALL
SELECT 'channel', channel_group, COUNT(DISTINCT session_id)
FROM window_sessions GROUP BY channel_group
UNION ALL
SELECT 'conversion', 'total', COUNT(DISTINCT session_id)
FROM window_sessions WHERE converted = true;

The UTC boundary above converts the session clock explicitly before truncating the day. Use an IANA time zone name or UTC for the database session. See AWS's SYSDATE, CURRENT_SETTING, CONVERT_TIMEZONE, and DATE_TRUNC references. Test your view's bounds as the database identity Squoosh will use.

Enter database, schema, and view as separate identifier components, without surrounding quotes, spaces, dots, comment markers, or SQL fragments. Each must match ^[A-Za-z_][A-Za-z0-9_$]{0,127}$. Squoosh double-quotes each component; use the actual stored names, normally lowercase for names created without quotes. Default schema is public; default view is squoosh_calibration. Redshift's own identifier and database-name limits also apply. See Names and identifiers.

Create credentials and grants¶

1. In IAM → Users, create or choose a dedicated IAM user with a lowercase name. Under Permissions → Add permissions, attach a policy reviewed by your AWS administrator for this database and cluster or workgroup.
2. Grant redshift-data:ExecuteStatement, redshift-data:DescribeStatement, redshift-data:GetStatementResult, and redshift-data:CancelStatement. The same IAM identity must submit, poll, read, and cancel statements. Follow AWS's Data API IAM policies for resource and statement-owner restrictions.
3. Add the database authentication permission for the path you choose:

1. In Query editor v2, grant the effective database identity USAGE on the schema and SELECT on the view. For the explicit provisioned-cluster Database user path, create the user first, for example:

CREATE USER squoosh_reader PASSWORD DISABLE;
GRANT USAGE ON SCHEMA public TO squoosh_reader;
GRANT SELECT ON public.squoosh_calibration TO squoosh_reader;

An IAM-derived database user uses a name such as "IAM:squoosh_reader"; roles use "IAMR:role_name". If it does not yet exist, attempt verification, let your administrator inspect/create the effective user, grant access, then verify again. Do not assume mixed-case IAM names fold the same way. See database grants.

1. If using Secrets Manager, find the ARN in Secrets Manager → Secrets → your secret → Secret details. The secret holds the database username/password. For a provisioned cluster, its cluster identifier must match the connection. Squoosh stores only the ARN as a setting; AWS resolves the secret. See Data API secrets.
2. Under IAM → Users → your user → Security credentials → Access keys → Create access key, create the pair for this integration. Save the secret when it is shown. Paste the access key ID and secret into Squoosh; the secret is stored in encrypted credentials. This beta accepts long-lived IAM user keys; temporary session tokens and cross-account AssumeRole are not supported. See AWS access keys.

If you use AWS's managed AmazonRedshiftDataFullAccess policy for Serverless, its credential permission requires the workgroup tag key RedshiftDataFullAccess. A custom policy can grant the workgroup permission without that managed-policy condition. Have your administrator choose the appropriate scope; the managed policy is broader than this connector needs. See the managed policy reference.

Connect in Squoosh¶

1. Open Integrations → Amazon Redshift → Connect.
2. Enter the AWS access key pair and the AWS Region shown in the Redshift console.
3. Enter exactly one Cluster identifier or Serverless workgroup name. Find these under Provisioned clusters → Clusters or Redshift Serverless → Workgroup configuration. This version accepts workgroup names, not workgroup ARNs.
4. Enter Database, Schema, and Calibration view separately. If applicable, enter Database user or Secrets Manager secret ARN, following the table above.
5. Set View window in days to the number of full UTC days actually covered by your view, then click Connect.

Squoosh records your declared window, not the window requested by a later caller. Every snapshot carries window_declared_by_customer; Squoosh cannot verify the view's filter. An empty view can pass the access probe but produces a no_data snapshot failure until populated.

What Squoosh reads and never reads¶

Squoosh receives the three aggregate columns, column metadata, statement status, row count, pagination tokens, and provider errors. It sends only the fixed read-only SELECT plus statement describe/result/cancel operations. It does not download raw session rows, customer names, emails, purchase details, passwords from Secrets Manager, or unrelated tables. Keep personal data out of the view's bucket labels. Your view may scan underlying data inside your warehouse to compute the aggregates.

Limits and caveats¶

• This beta remains at authentication stage until a real account validates its requests and parser. Connection success does not mean it is grounding AI shoppers.
• 10,000 result rows maximum before duplicate summing. A 10,001st row or a reported larger result is rejected, never clipped into a partial rate. Undocumented page size is handled by following every NextToken within the deadline.
• 30 seconds total per attempt. Signing, submission, polling, result bodies, and cancellation share that budget. The final second is reserved for best-effort cancellation. If submission returns no statement ID, or cancellation fails, AWS may continue the query. A cold Serverless workgroup may need a later retry. The CancelStatement API can cancel only a running statement.
• Queries consume customer warehouse compute. The row LIMIT is not a scan-cost ceiling. Configure warehouse workload/time limits and keep the view inexpensive. The descriptor's minimum refresh interval is six hours; unattended refresh is disabled at this stage.
• Data API quotas are per account per Region: 30 ExecuteStatement, 100 DescribeStatement, 20 GetStatementResult, and 3 CancelStatement calls per second. Throttling can arrive as HTTP 400. AWS also limits results to 500 MB compressed and 64 KB per row. See Data API limits.
• Commercial AWS and GovCloud regional endpoints are supported. China/ISO partitions, temporary AWS credentials, and workgroup ARNs are outside this version's scope.
• Verification proves column access, not the correctness of all view rows, session semantics, or the date window. Full snapshot validation runs across all rows. Missing or invalid data does not become an invented distribution.

Troubleshooting¶

Related¶

• CSV / Excel import: the shared aggregate template and an alternative data path.
• AI shoppers: how calibration is used after a source is eligible.
• Redshift Data API: AWS authentication and execution model.
• GetStatementResult: result metadata, typed fields, and pagination.