Use table workspace variables to conveniently manage data that is best presented in tabular form. These variables enable simple visualization and presentation of tables, enhancing the clarity and accessibility of your data. Easily automate processes to respond to table updates or update data in tables, further streamlining your work and increasing efficiency.

Create table: set the table schema

You can create tables both automatically and manually:
1. Automatically:
  - Use the Create a workspace variable step:
    Name the table: Provide a meaningful name. The programmatic name is auto-generated by converting the display name to lowercase, removing special characters, and replacing spaces with underscores.
    Select data type: Choose Table as the variable type.
    Define columns: Specify the table columns (see schema rules below).
    Select integration: Choose a Torq integration to execute the step.
2. Manually:
  1. Navigate to the Workspace Variables page: Go to Build > Workspace Variables.
  2. Create a new workspace variable: Click the + icon in the Variables column and set the variable type to Table. Give the table variable a meaningful name.
Define the table schema: Set the table schema by specifying the table columns.
- Add columns: Use Add Column to define column headers and value types as needed.
  - When using the Create a workspace variable step to define the table schema automatically, you can switch to JSON mode to create the table from a JSON object or set the schema dynamically using the workflow context.
- Default system columns: Every table is created with the following default columns:
  - id: Row index.
  - created_by: User who created the row.
  - created_at: Timestamp of row creation.
  - updated_by: User who last updated the row.
  - updated_at: Timestamp of last update.

Column names must begin with a letter (a-z) or an underscore (_). Subsequent characters can be letters, digits (0-9), or underscores.
Some names are reserved because they are SQL keywords.
Cells support long text, boolean, number, or JSON formats.
Table workspace variables have the following guardrails for optimal performance and stability.

Create a table from JSON

Creating a table from JSON allows you to dynamically define the schema by referencing an existing table or using a centralized source such as a workspace variable. This approach is particularly useful when standardizing or replicating tables across multiple workspaces.

JSON-based schema creation is only supported when using the Create a workspace variable step. It is not available when creating a table directly from the Workspace Variables page.

To define the table schema in JSON format, switch to JSON mode in the Create a workspace variable step and choose one of the following methods:

From workflow context: Generate the schema dynamically using data from the workflow context, such as the output of a previous Get a workspace variable step:
{{ $.get_a_workspace_variable.api_object.variable.table }}

Custom JSON format: Manually define the table schema using the required JSON structure. When using this method, workflow context variables cannot be referenced.

{
  "columns": [
    {
      "name": "title",
      "text": {
        "default_value": ""
      }
    },
    {
      "name": "priority",
      "number": {}
    },
    {
      "name": "completed",
      "boolean": {}
    },
    {
      "name": "additional_info",
      "json": {}
    }
  ]
}

Manage and operate tables

You can manage table workspace variables both automatically and manually.

Automatically manage tables

Use dedicated steps to operate on tables automatically:

Insert Into Table: Add new data entries.
Update Table: Modify existing data.
Delete From Table: Remove data entries.
Query Table: Retrieve specific columns, sort data, and filter cells based on specified conditions.
Update a workspace variable: Update the table schema.

To run these steps, you need a Torq integration.

Manually manage tables

In the Workspace Variables page, at the top right of the table preview, you can:

Add Rows: Insert new data into the table.
Modify the Table Schema: Add new columns to expand the table structure.
Delete Rows: Remove selected records.
Revert Unsaved Changes: Discard modifications that have not yet been saved.

Example: Add user information to a table

In this example, we collect user survey responses in a structured table format. First, populate the table with the users you want to survey, in this case, users who were locked out of Okta. When you select the table name, the table schema is automatically populated.

Trigger workflows upon table updates

Use the System Events > Variable Updated trigger to automatically respond to changes in a table workspace variable.

The Variable Updated internal trigger applies only to Table workspace variables and does not support other variable types such as Text, JSON, Number, or Boolean.

Example: Trigger a workflow when a new row is added

Create a workflow that's triggered whenever a new row is added to the table.

Add trigger: Use System Events > Variable Updated as the workflow trigger.
Define conditions: Configure trigger conditions to specify the table name and the exact update type (for example, row created).

In this example, each new row includes the email address of the user to be surveyed.

The workflow automatically sends the survey questions to that user.
The user’s responses are then written back to the same table row, centralizing the data and streamlining the collection process.

Query a table

Use the Query Table step to extract table values.

Use the optional parameters in the Query Table step to make your query more specific. Otherwise, the entire table content will be returned.

Select table: Specify the table name from which to extract data.
(Optional) Select columns: Choose specific columns to return.
(Optional) Set conditions: Define filter criteria to return rows that match specific column values.
(Optional) Sort results: Select the column to sort by.
(Optional) Set sort order: Choose ascending or descending order.
(Optional) Set limit: Define the number of rows to return (useful for pagination page size).
(Optional) Set offset: Specify the starting row to support pagination.
(Optional) Select integration: Choose a Torq integration to run the step in a different workspace. If not specified, the step runs in the current workspace.
Run step: Execute the step to retrieve the results as an array of JSON objects, where each object represents a table row.

Extract rows that match a condition

To return rows that match a specific condition, use the Query Table step and configure the optional parameters as needed:

(Optional) Select columns: Choose the specific columns to return. Leave this field empty to retrieve complete rows.
(Optional) Set conditions: Define the filter criteria for the rows to return. Combine multiple conditions using AND or OR to create more advanced logic.

Comparison operators vary based on the column’s data type.

The Is in and Is not in operators require a list of comma-separated values to return accurate results. While a Step will still be executed successfully with a JSON array of strings, it will return the wrong results.

Extract a specific value from a table

To extract a specific value from the table use the Query Table step with the following optional parameters.

Select columns: Specify the exact column that contains the value you want to retrieve.
Set limit: Enter 1 to return a single row.
Set offset: Specify the row index of the value you want to retrieve. This can reference the output of a previous step.

To retrieve a specific value, you must define both the column and the target row.

Create and manage table schemas with workspace variables API

The Workspace Variables API allows you to manage table schemas. The API allows you to:

Retrieve existing column definitions.
Create new tables.
Update column structures.

The API supports schema management only and does not provide access to table data.

Define the table schema

Send a POST request using the following format:

curl --request POST \
--url https://api.torq.io/public/v1alpha/workspace_variables \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{"pretty_name":"table_name","table":{"columns":[{"name":"col1","text":{}},{"name":"col2","boolean":{}}]}}'

Update the table schema

Send a PUT request using the following format:

curl --request PUT \
--url https://api.torq.io/public/v1alpha/workspace_variables/table_name \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{ "variable":{"name":"table_name","table":{"columns":[{"name":"col1","text":{}}]}}}'

Table Workspace Variables: Manage Data Efficiently in Torq