Table Source Resources YAML Reference

This guide is a detailed reference for the CLI project YAML files that define your Reverse ETL table sources.

Table sources require Rudder CLI v0.27.0 or later. The retl-sources validate and retl-sources preview commands support table sources from v0.28.0. In v0.28.0 and earlier, you must also enable the table source experimental flags. See Manage Reverse ETL Table Sources using Rudder CLI.

Overview

A table source reads rows straight from a table in your warehouse, or from files under an S3 bucket prefix, with no SQL query in between. To sync the result of a query instead, use a SQL model.

You define a table source by setting kind to retl-source-table. Table sources use version: rudder/v1 only. Rudder CLI rejects any other version.

You can store the YAML files anywhere in the project directory. Define one table source per file: spec must be a mapping, not a list.

Table source resources

The spec parameter has the following structure:

Set exactly one of account and account_id.

Table sources have no description field, because the Reverse ETL API doesn’t store one for table sources.

Fields by source definition

Reference an account

An account reference must point to an account in the same project, and that account’s type must match source_definition. For example, a postgres table source can’t reference a Snowflake account.

Rudder CLI manages only BigQuery, PostgreSQL, and Snowflake accounts. For other warehouses and for S3, set account_id to the ID of an account that already exists in your workspace. Rudder CLI doesn’t check a raw account_id locally.

Example definitions

version: rudder/v1
kind: retl-source-table
metadata:
  name: users-table
spec:
  id: users-table
  display_name: Users
  account: "#account:prod-pg"
  source_definition: postgres
  primary_key: id
  schema: public
  table: users
  enabled: true

version: rudder/v1
kind: retl-source-table
metadata:
  name: orders-table
spec:
  id: orders-table
  display_name: Orders
  account_id: "2rzPI1ARibivIvNH5DSpAKGTATy"
  source_definition: redshift
  primary_key: order_id
  schema: analytics
  table: orders

version: rudder/v1
kind: retl-source-table
metadata:
  name: events-archive
spec:
  id: events-archive
  display_name: Events Archive
  account_id: "2rzPI1ARibivIvNH5DSpAKGTATy"
  source_definition: s3
  bucket_name: my-analytics-bucket
  object_prefix: events/2026/

Validation rules

rudder-cli validate and rudder-cli apply check table sources before they call the API. Every error names the field it refers to.

Update and delete behavior

• Updates: Changes to display_name, enabled, the account, primary_key, bucket_name, and object_prefix update the source in place.
• source_definition: Changing it fails the apply. Create a new source with a new id instead.
• schema and table: Changing either fails the apply while a destination is connected to the source, including connections you created in the dashboard. Delete the connection first, or create a new source for the new table.
• Delete: RudderStack refuses to delete a source that still has connections. If the connections are in your project, rudder-cli apply deletes them first. Delete connections you created outside the project in the dashboard.

See also

• Manage Reverse ETL Table Sources using Rudder CLI
• Reverse ETL Connections YAML Reference
• SQL Model Resources YAML Reference
• Account Resources YAML Reference