Table Task¶
Overview¶
The Table Task fetches and searches data from custom tables in your CRM. Use it to query configuration data, lookup values, retrieve customer preferences, search product catalogs, or access any structured data you've stored in custom tables.
The tables are the ones people see and fill in on a client's Tables tab — see Custom tables. A row this task adds appears there straight away, and to start a workflow when someone adds or changes a row there, use a CRM Trigger.
When to use this task:
- Lookup customer preferences or settings
- Query product catalogs or pricing
- Retrieve configuration values
- Search inventory or stock data
- Access project history
- Fetch support ticket information
- Get custom field mappings
- Retrieve territory assignments
Key Features:
- Fetch single row or all rows
- Search by row ID
- Filter by client ID and column values
- Support for multiple filter conditions
- Returns latest matching row if multiple found
- Handles blank/empty values
- Works with user and users columns, by picking the users
- Structured output by row and column
Quick Start¶
Fetch Single Row:
Fetch by Client + Filters:
1. Add Table task
2. Select Action: Fetch Row
3. Enter Table ID
4. Set Client ID
5. Add column filters (row_col_X)
6. Save
Fetch All Rows:
1. Add Table task
2. Select Action: Fetch All Rows
3. Enter Table ID
4. Set Client ID (optional)
5. Add filters (optional)
6. Save
Configuration¶
Builder fields¶
The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.
| Field | Key | Type | Default | Notes |
|---|---|---|---|---|
| Action | table_action |
select | – | Options: Fetch Row · Fetch All Rows · Add Row · Edit Row · Delete Row |
| Search By | search_by |
select | – | Options: Row ID · Client ID & Column Values. Only shown when table_action is fetch_row |
| Table | table_id |
select | – | Only shown when table_action is fetch_row, fetch_all_rows, add_row, edit_row |
| Client ID | Client ID |
text | – | Only shown when table_action is add_row, fetch_all_rows, fetch_row |
| Row ID | Row ID |
text | – | Only shown when table_action is edit_row, delete_row, fetch_row |
| Return row data | return_row_data |
checkbox | – | Only shown when table_action is fetch_all_rows |
| Columns | _table_columns |
table-task-columns | – | Only shown when table_action is fetch_row, fetch_all_rows, add_row, edit_row |
Action Selection¶
Fetch Single Row:
Returns single matching row.
Fetch All Rows:
Returns the IDs of all matching rows in row_ids.
Return row data (fetch_all_rows only)¶
Off by default. Tick Return row data to also get the values of the matching rows in rows, each
shaped like the table output of Fetch Row, ready for a Loop.
rows holds the first 100 rows only, lowest row ID first. row_ids still lists every match, so
you can tell when there were more than 100. Match to Clients and the
Contact task's Get Contacts have the same box for clients and contacts.
Table ID (Required)¶
The custom table to query. In the task builder, pick it by name from the Table list; the task stores its ID. Tables are set up on a client's Tables tab — see Custom tables.
Row ID (fetch_row only)¶
Direct row lookup by ID. Fastest method if you know the row ID.
When to use:
- Previous task returned row ID
- Direct record access needed
- No filtering required
Client ID¶
Optional for fetch_row with row_id, required for client_id_columns search method.
When to use:
- Fetch customer-specific data
- Filter by client ownership
- Get client preferences/settings
Column Filters (row_col_X)¶
Filter by column values. Column numbers match your table structure.
In the task settings, use + Add filter to add only the columns you want to filter on; with no filters, Fetch Row returns the client's newest row and Fetch All Rows returns all of them. Edit Row works the same way with + Add column: only the listed columns are changed, and a listed column left blank is emptied.
Syntax:
row_col_Xwhere X is column number- Column 1 is first custom column (after default fields)
- Supports exact matching
- Can match an empty cell, or any value, with the column's condition (see below)
Example table structure:
Table 15 - Customer Preferences
Column 1 (row_col_1): Status
Column 2 (row_col_2): Plan Type
Column 3 (row_col_3): Region
Column 4 (row_col_4): Language
Column 5 (row_col_5): Preferences (JSON)
Filter for active enterprise customers in EMEA:
Table ID: 15
Client ID: {{task_15001_match_client_id}}
row_col_1: Active
row_col_2: Enterprise
row_col_3: EMEA
Blank Filters¶
An empty filter is ignored — it does not filter on that column. This is also what happens when a filter is a variable that turned out empty.
Between each filter's column and its value there is a small button reading Matches, so the row reads as a sentence. Click it and it steps to the next way of matching, and round again at the end:
| The button reads | Rows kept |
|---|---|
| Matches | The cell equals the value (blank value = no filter). On a single select column, any of the options you pick |
| Does not match | The cell is anything else, blank included (blank value = no filter). On a single select column, none of the options you pick |
| Contains | The value appears anywhere in the cell. Capital letters make no difference: paid finds Paid in full and Unpaid |
| Does not contain | The value appears nowhere in the cell, blank included |
| Is empty | The cell is blank, never filled in, or a multi-select with nothing picked. No value is needed |
| Has any value | The cell holds something. No value is needed |
Contains and Does not contain are offered on Single-Line Text, Multi-Line Text and Location columns only, so a street or town finds the rows whose address mentions it. Other column types are matched whole, because part of an option, a date or a number would mean nothing.
How each column type reads the filter value:
| Column | Filter with |
|---|---|
| Single select, Multi select | Pick the options. A row holding any of them is kept; with Does not match, only rows holding none of them. In Variable mode give option IDs, comma-separated ([1,3] is read too) |
| User, Users | Pick the users. A row with any of them is kept. In Variable mode give user IDs, comma-separated |
| Checkbox | Yes or No. In Variable mode 1/0, Yes/No and true/false all work. No means not ticked, so it also finds rows where the box is blank or was never saved |
| Currency | An amount, compared as a number: 100 finds 100.00. Spaces and thousands commas are ignored |
| Number | The number, matched whole |
| Date | See Date Fields |
A checkbox filter that is not Yes or No, or a currency filter that is not an amount, stops the task with a message naming the column, as the same value stops Match to Clients and Get Contacts.
The same button, with the same choices and wording, is on Match to Clients and on the Contact task's matching items.
Each filter is stored as two settings: the value under row_col_<column id>, and how it is matched
under match_col_<column id>, holding not_equals, contains, not_contains, empty or
not_empty (blank for Matches).
Checkbox columns don't have a condition — filter them with Yes or No.
Date Fields¶
Filter syntax:
Either format matches. Fetch Row outputs dates as DD/MM/YYYY, so a fetched date can be passed
straight into a later filter. A value that isn't a valid date matches no rows.
User Fields¶
A User or Users column holds user IDs. A filter picks users from a list, or in Variable mode takes their IDs:
The second finds the rows where either user is set, or appears in a Users list.
File Columns¶
On Add Row and Edit Row, a file column (one file or several) takes the files to attach. Name each file in any of these ways:
- A file from an earlier step. Pick the Files task's File ID or File URL, for example
{{task_39001_file_id}}. Files from an email, a form or another table work the same way. - A link to any file online, such as
https://example.com/quotes/Q-1042.pdf. The task downloads it and saves it in BaseCloud, so you don't need a Files task first.
Separate several files with commas. A one-file column takes a single file.
The row keeps its own copy of each file. Deleting the row, or removing the file from the cell, leaves the original where it was, such as in the client's Files tab or on the email it came from. Copying a file that's already in BaseCloud doesn't use extra storage.
On Edit Row, a column that holds several files adds the new files to the ones already there. Choose Replace the files already there under the column to swap them out instead. A one-file column always replaces its file.
The task stops with a message, and changes nothing, when:
- no file with that ID is in this account,
- a link doesn't download (the run tries again later if the website didn't answer),
- a link opens a web page rather than a file, or
- a one-file column is given more than one file.
A run can add up to 20 files to a cell, and each download can be up to 50 MB.
Outputs¶
| Field | Type | Example | Notes |
|---|---|---|---|
table |
array | [{"id":1,…}] |
The rows returned. Iterate with a Loop using action set to array. |
table_row_id |
number | 4471 |
The row acted on, for single-row actions. |
row_ids |
string | 4471,4472 |
Fetch All Rows: comma-separated IDs of every matching row. |
rows |
array | [{"row_id":4471,…}] |
Fetch All Rows with Return row data ticked: the first 100 matching rows, each with table_id, label, client_id, row_id, row (its cells, as in table) and row_link. |
run |
boolean | true |
|
run_text |
string | Table data retrieved. |
Output Structure¶
Single Row Output¶
{
"task_25001_data": {
"12345": {
"row_id": "12345",
"client_id": "67890",
"col_1": "Active",
"col_2": "Enterprise",
"col_3": "EMEA",
"col_4": "English",
"col_5": "{\"email_freq\": \"daily\", \"sms_opt_in\": true}",
"created": "2025-01-15 10:30:00",
"updated": "2026-02-01 14:22:00"
}
}
}
Access fields:
- Row ID:
{{task_25001_data.12345.row_id}} - Column 1:
{{task_25001_data.12345.col_1}} - Column 2:
{{task_25001_data.12345.col_2}} - Created:
{{task_25001_data.12345.created}}
Multiple Rows Output¶
{
"task_25001_data": {
"12345": {
"row_id": "12345",
"client_id": "67890",
"col_1": "Active",
"col_2": "Enterprise"
},
"12346": {
"row_id": "12346",
"client_id": "67890",
"col_1": "Active",
"col_2": "Professional"
}
}
}
Access specific row:
{{task_25001_data.12345.col_1}}{{task_25001_data.12346.col_2}}
Loop through all rows:
Real-World Examples¶
Look up a stored setting for a client¶
CRM Trigger
└─ Table fetch_row by client and column
└─ Email use the value from {{task_25001_table}}
Record a row against a client¶
{{task_25001_table_row_id}} is the row that was written, which you need if a later task edits it.
Attach a signed document to a row¶
Webhook In receives pdf_url, a link to the signed PDF
└─ Table edit_row: Row ID {{task_25001_table_row_id}}, Documents = {{task_30001_pdf_url}}
The Webhook In trigger passes pdf_url on, and the PDF is downloaded
and saved on the row, so it opens from the table like a file uploaded by hand.
To attach a file already saved by a Files task, map {{task_39001_file_id}} instead.
Work through a table's rows¶
Tables hold rows, not answers
The task reads and writes individual rows. It does not total, count or group them — for that, see MySQL Query.
Best Practices¶
Table Design¶
- Use consistent column types - Don't mix data formats in same column
- Index frequently searched columns - Improves performance
- Keep column count reasonable - Max 20 columns per table
- Use descriptive column names - Document in CRM
- Maintain data quality - Regular cleanup and validation
Search Strategy¶
- Use row_id when available - Fastest lookup method
- Combine client_id with columns - Efficient filtering
- Limit filter columns - Only necessary conditions
- Handle missing data - Check for blank values
- Consider fetch_all vs fetch_row - Based on expected results
Performance¶
- Don't fetch unnecessary data - Use filters
- Cache frequently accessed data - Store in variables
- Batch operations - Use loops efficiently
- Monitor table size - Archive old data
- Index key columns - Improves query speed
Data Handling¶
- Validate table output exists - Use If task to check
- Handle multiple row IDs - When using
*wildcard - Parse JSON columns - Use Code task for complex data
- Format dates and numbers - Use formatter tasks
- Provide fallbacks - Use Coalesce for missing data
Troubleshooting¶
No Data Returned¶
Issue: Table task returns empty
Causes:
- Invalid table ID
- No matching rows
- Incorrect filter values
- Wrong column numbers
- Client ID mismatch
Solution:
- Verify table ID in CRM
- Check filter values match exactly (case-sensitive)
- Confirm column numbers (col_1 is first custom column)
- Test with fewer filters
- Use fetch_all_rows to see all data
Wrong Row Returned¶
Issue: Returns unexpected row
Cause: Multiple rows match filters, returns latest
Solution:
- Add more specific filters
- Use unique identifier (row_id) if known
- Check table for duplicate data
- Review column values in CRM
Cannot Access Column Data¶
Issue: {{task_25001_data.*.col_X}} returns empty
Causes:
- Wrong row ID in path
- Column doesn't exist
- Using
*with multiple rows
Solution:
# Single row - use *:
{{task_25001_data.*.col_1}}
# Specific row ID:
{{task_25001_data.12345.col_1}}
# Multiple rows - use Loop task:
Loop over {{task_25001_data}}
Access: {{task_29001_item.value.col_1}}
Blank Value Not Matching¶
Issue: Leaving a filter blank returns rows that have a value in that column
Cause: A blank filter means "don't filter on this column"
Solution: Set the column's condition to Is empty. Cells holding only spaces count as empty.
Performance Slow¶
Issue: Table lookup takes long time
Causes:
- Large table (1000+ rows)
- Complex filters on multiple columns
- Unindexed columns
Solution:
- Use row_id lookup when possible
- Reduce filter complexity
- Archive old data
- Contact admin about indexing
Frequently Asked Questions¶
Can I update table data?¶
Yes. Add Row writes a new row and Edit Row changes the columns you list, file columns included (see File Columns). Delete Row removes a row.
Can I search multiple tables?¶
No, one table per task. Use multiple Table tasks for multiple tables.
What's the maximum table size?¶
Recommended under 10,000 rows. Performance degrades with very large tables.
Can I join tables?¶
No, tables are independent. Fetch from each separately and join in Code task.
How do I handle multiple matching rows?¶
Use fetch_all_rows action and loop through results, or add more filters to get single row.
Can I filter by date range?¶
No direct date range filter. Fetch all rows and filter in Code task.
Do I need exact column value match?¶
Yes, filters are exact match only. Use Code task for partial matching or regex.
Can I sort results?¶
No built-in sorting. Use Code task to sort after fetching.
Related Tasks¶
- Match to Client - Get client ID for table queries
- Files - Save a file, then attach it to a row by its File ID
- MySQL Query - Query database directly for complex needs
- Code - Process and transform table data
- Loop - Iterate through multiple rows
- If Statement - Conditional logic based on table data
- Coalesce - Provide fallback values
- Variable - Store frequently used table values