improvement(table): document that a column selection matching no column returns empty row data (#9915)

Author: waleedlatif1

apps/docs/content/docs/integrations/table.mdx

@@ -217,7 +217,7 @@ Query rows with a typed predicate filter and cursor pagination. A single filter
 | --------- | ---- | -------- | ----------- |
 | `tableId` | string | Yes | Table ID in the execution workspace. In a workflow, the table must belong to the same workspace as the workflow. |
 | `filter` | json | No | Predicate condition, e.g. `\{"field":"wins","op":"gte","value":10\}`. Use `all` or `any` for multiple conditions; omit to match all rows. |
-| `columns` | array | No | Stable column IDs or table column names to include in each row data object. Omit or pass an empty array to return all columns. A reference that matches no column is ignored. |
+| `columns` | array | No | Stable column IDs or table column names to include in each row data object. Omit or pass an empty array to return all columns. A reference that matches no column is ignored; if none match, each row's data is empty. |
 | `order` | json | No | Sort spec, e.g. `\[\{"field":"wins","direction":"desc"\}\]`. |
 | `limit` | number | No | Maximum rows per page. Omit to return the entire matching result — fails if it exceeds the fixed 5 MiB row-data budget. With a limit, pages may byte-cut early and set nextCursor when more remain. |
 | `cursor` | string | No | Opaque pagination cursor returned by a prior query. Omit for the first page. |

apps/sim/lib/api/contracts/tables.ts

@@ -797,7 +797,7 @@ const rowColumnSelectionSchema = z
   )
   .optional()
   .describe(
-    'Stable column identifiers or column names to include. Omit or pass an empty array for all columns; a reference that matches no column is ignored.'
+    "Stable column identifiers or column names to include. Omit or pass an empty array for all columns; a reference that matches no column is ignored, and if none match, each row's data is empty."
   )
 
 /** Unrefined base so v1 contracts can `.extend()` — consumers use {@link tableRowsQuerySchema}. */

apps/sim/tools/generated/tool-metadata.ts

@@ -7,3 +7,13 @@ export const TABLE_ID_PARAM = {
     'Table ID in the execution workspace. In a workflow, the table must belong to the same workspace as the workflow.',
   visibility: 'user-only',
 } satisfies ToolConfig['params'][string]
+
+/** Column projection for the row-query tools; shared so both query tools describe it identically. */
+export const TABLE_COLUMNS_PARAM = {
+  type: 'array',
+  required: false,
+  items: { type: 'string' },
+  description:
+    "Stable column IDs or table column names to include in each row data object. Omit or pass an empty array to return all columns. A reference that matches no column is ignored; if none match, each row's data is empty.",
+  visibility: 'user-or-llm',
+} satisfies ToolConfig['params'][string]

apps/sim/tools/table/params.ts

@@ -1,5 +1,5 @@
 import { enrichTableToolSchema } from '@/tools/schema-enrichers'
-import { TABLE_ID_PARAM } from '@/tools/table/params'
+import { TABLE_COLUMNS_PARAM, TABLE_ID_PARAM } from '@/tools/table/params'
 import { tableSuccess } from '@/tools/table/response'
 import type { TableQueryResponse, TableRowQueryParams } from '@/tools/table/types'
 import type { InternalToolConfig } from '@/tools/types'
@@ -31,14 +31,7 @@ export const tableQueryRowsTool: InternalToolConfig<TableRowQueryParams, TableQu
       description: 'Sort order as {field: "asc"|"desc"}',
       visibility: 'user-or-llm',
     },
-    columns: {
-      type: 'array',
-      required: false,
-      items: { type: 'string' },
-      description:
-        'Stable column IDs or table column names to include in each row data object. Omit or pass an empty array to return all columns. A reference that matches no column is ignored.',
-      visibility: 'user-or-llm',
-    },
+    columns: TABLE_COLUMNS_PARAM,
     limit: {
       type: 'number',
       required: false,

apps/sim/tools/table/query_rows.ts

@@ -1,7 +1,7 @@
 import { normalizeTablePredicate } from '@/lib/table/query-builder/predicate'
 import { validatePredicateShape } from '@/lib/table/query-builder/validate'
 import { enrichTableToolSchema } from '@/tools/schema-enrichers'
-import { TABLE_ID_PARAM } from '@/tools/table/params'
+import { TABLE_COLUMNS_PARAM, TABLE_ID_PARAM } from '@/tools/table/params'
 import { tableSuccess } from '@/tools/table/response'
 import type { TableQueryV2Response, TableRowQueryV2Params } from '@/tools/table/types'
 import type { InternalToolConfig } from '@/tools/types'
@@ -44,14 +44,7 @@ export const tableQueryRowsV2Tool: InternalToolConfig<TableRowQueryV2Params, Tab
           'Predicate condition, e.g. `{"field":"wins","op":"gte","value":10}`. Use `all` or `any` for multiple conditions; omit to match all rows.',
         visibility: 'user-or-llm',
       },
-      columns: {
-        type: 'array',
-        required: false,
-        items: { type: 'string' },
-        description:
-          'Stable column IDs or table column names to include in each row data object. Omit or pass an empty array to return all columns. A reference that matches no column is ignored.',
-        visibility: 'user-or-llm',
-      },
+      columns: TABLE_COLUMNS_PARAM,
       order: {
         type: 'json',
         required: false,