Configure subsetting

Requires the Advanced API. The Advanced API requires an Enterprise license.

You can use the Tonic Structural API to configure subsetting for a workspace. You can also enable or disable subsetting for a workspace.

You can configure a table to be a target table or a lookup table. You can also remove the configuration.

Subsetting configuration format

You apply a subsetting configuration to individual tables.

A subsetting configuration identifies a table as a target table or a lookup table. For a target table, it also indicates how to identify the records to include in the subset.

The configuration includes:

• The name of the schema that contains the table. For requests to update or delete a subsetting rule, the schema name is a request parameter and not in the request body.

• The name of the table. For requests to update or delete a subsetting rule, the table name is a request parameter and not in the request body.

• Whether the table is a lookup table (IgnoreUpstreamTables is true). For a lookup table, all of the records are always included. WhereClause is ignored, and Percent is always 100. If the table is not a lookup table, then it is a target table.

• For a target table, to identify the records to include, either:

  • A WHERE clause to filter the source records.

  • A percentage of source records.

Subsetting configuration examples

Target table with percentage

The following example configures a table as a target table for which to include 5 percent of the records:

{
  "Schema": "public";
  "Table": "sales";
  "Percent": 5;
  "IgnoreUpstreamTables": false
}

Target table with WHERE clause

The following example configures a table as a target table for which to include records where the value of amount is less than 100.

{
  "Schema": "public";
  "Table": "sales";
  "WhereClause": "amount < 100";
  "IgnoreUpstreamTables": false
}

Lookup table

The following example configures a table as a lookup table:

{
  "Schema": "public";
  "Table": "states";
  "Percent": 100;
  "IgnoreUpstreamTables": true
}

For a lookup table, all of the records are always included. WhereClause is ignored, and Percent is always 100.

Enabling or disabling subsetting for a workspace

To enable subsetting for a workspace, use:

POST /api/workspace/{workspaceId}/subsetting/enable

To disable subsetting for a workspace, use:

POST /api/workspace/{workspaceId}/subsetting/disable

Retrieving the subsetting configurations for a workspace

To get the current list of subsetting configurations for a workspace, use:

GET api/workspace/{workspaceId}/subsetting

Adding a subsetting configuration

To add a subsetting configuration, use:

POST api/workspace/{workspaceId}/subsetting

The request includes the subsetting configuration to apply.

Structural checks whether the specified table has a current subsetting configuration.

• If it does, then Structural uses the provided configuration to update it.

• If it does not, then Structural returns an error.

Adding or updating a subsetting configuration

To either add or update a subsetting configuration, use:

PUT api/workspace/{workspaceId}/subsetting/{schema}/{table}

The request body provides the subsetting configuration to apply to the specified table.

Structural checks whether the specified table has a current subsetting configuration.

• If it does, then Structural uses the provided configuration to update it.

• If it does not, then Structural adds the subsetting configuration for the table.

Removing a subsetting configuration

To remove a subsetting configuration, use:

DELETE api/workspace/{workspaceId}/subsetting/{schema}/{table}

Structural removes the subsetting configuration for the specified table.