Update Tonic Structural subsetting rule

A GitHub action to create or update a subsetting rule for a table in a Tonic Structural workspace.

The subsetting rule configures the table either as a target table or a lookup table.

For a target table, to specify how to select the rows to include in the subset, you either:

• Provide a WHERE clause to identify the rows to select.
• Specify a percentage of the rows.

Inputs

Input	Description	Required	Default
structural-url	URL to Tonic Structural. For example: https://app.tonic.ai	No	https://app.tonic.ai
structural-api-key	API key for authentication. Stored as a secret.	Yes	-
workspace-id	Identifier of the workspace to apply the subsetting rule to.	Yes	-
schema	Name of the database schema that contains the affected table. Case-sensitive.	Yes	-
table	Name of the affected table. Case-sensitive.	Yes	-
where-clause	For a target table, a SQL WHERE clause to filter the included rows. Do not include the WHERE keyword. Mutually exclusive with percent and ignore-upstream-tables.	No*	-
percent	For a target table, the percentage of rows to include. Value is 0-100, and decimal values are allowed. Mutually exclusive with where-clause and ignore-upstream-tables.	No*	-
ignore-upstream-tables	If true, treats the table as a lookup table. A lookup table includes all rows and ignores upstream rules. Mutually exclusive with where-clause and percent.	No*	false

* Note: You must provide exactly one of either where-clause, percent, or ignore-upstream-tables.

Examples

Basic example - WHERE clause-based subsetting

- name: Update subsetting rule with WHERE clause
  uses: TonicAI/structural-update-subsetting-rule@v1
  with:
    structural-api-key: ${{ secrets.TONIC_API_KEY }}
    workspace-id: 'your-workspace-id'
    schema: 'public'
    table: 'users'
    where-clause: 'created_at > NOW() - INTERVAL ''90 days'''

Example - Percentage-based subsetting

- name: Update subsetting rule with percentage value
  uses: TonicAI/structural-update-subsetting-rule@v1
  with:
    structural-api-key: ${{ secrets.TONIC_API_KEY }}
    workspace-id: 'your-workspace-id'
    schema: 'public'
    table: 'users'
    percent: '25.5'

Example - Lookup table (Ignore upstream rules)

- name: Mark table as a lookup table
  uses: TonicAI/structural-update-subsetting-rule@v1
  with:
    structural-api-key: ${{ secrets.TONIC_API_KEY }}
    workspace-id: 'your-workspace-id'
    schema: 'public'
    table: 'countries'
    ignore-upstream-tables: 'true'

Important notes

• Mutually exclusive inputs: You must provide exactly one of:

  • where-clause: For conditional row filtering
  • percent: For percentage-based sampling
  • ignore-upstream-tables: For lookup tables that should include all rows

• Schema/table matching: The action uses schema and table to identify existing rules. If a rule exists for that combination of schema and table, it is updated. Otherwise, a new rule is created.

• Case sensitivity: Depending on your database type, schema and table names might be case-sensitive. Always match the exact case used in your database.

• Child workspaces: When applying rules to a child workspace, inheritance from the parent workspace is automatically broken, and all of the inherited rules are copied to the child.

• WHERE clause: Do not include the WHERE keyword in your clause. Only provide the condition. For example, id > 100, not WHERE id > 100.

• Percentage values: The percent input accepts decimal values. For example, 25.5 indicates to use 25.5% of the rows.

• Lookup tables: When ignore-upstream-tables is true, the table is treated as a lookup or reference table. The subset includes all of the lookup table rows are included regardless of any upstream relationships.

Development

Setup

npm install

Build

npm run package

This uses @vercel/ncc to compile the action into a single file in the dist folder.

Publish

Before you publish, make sure to:

1. Build the action: npm run package
2. Commit the dist folder to the repository
3. Tag your release: git tag -a v1 -m "Release v1"
4. Push the tag: git push origin v1