Columns
Columns enrich and judge rows in a worksheet.
A column answers one declared question for every row in a worksheet. Use columns after a row source has landed a sample, whether the answer comes from source data, a formula, AI judgment, a tool, or enrichment. In Workbooks at /dashboard/workbooks, columns make each qualification decision inspectable before the work reaches a Record or an execution workflow.
Architect uses the list-building skill to turn the user’s criteria into bounded questions. It reads source fields and existing columns first, then adds only the evidence needed to decide who qualifies. Read cells and provenance after each run because creating a column saves a definition, while a run is what settles its cells.
Make one question per column
A column must state the value it will hold, what produces it, and which rows are worth spending on. One question per column keeps a failure legible. For example, one evidence column can answer whether a company has the requested operations signal and include the exact supporting text, while a later contact enrichment answers a different question: how to reach a person who passed that signal.
Every required criterion gets a yes-or-no column. Set configuration.qualification_requirement to required when creating that column. A false result or failed cell disqualifies the row, while an empty cell remains unknown. Nice-to-have criteria do not receive that setting. These checks describe worksheet criteria. Eligibility for outreach depends on the selected sequence’s explicit enrollment rules; a passing check or fit score alone does not establish eligibility.
Do not use a manual eligible flag in place of a qualification column. Manual text columns are appropriate only when the user explicitly wants a field they will type themselves, with behavior: "manual". A gate needs a settled, inspectable result so it can prevent paid work on rows that failed earlier evidence.
Build columns in cost order
Order is cost control. Start with identity and profile fields, then derived facts and evidence for each named signal, then an optional score, and finally contact data. Each gate should read a column that has already settled. A gate that reads an unrun column lets no useful decision through, while a paid column placed before its gate spends on rows the gate would have skipped.
| Order | Column work | Why it comes now |
|---|---|---|
1 | Identity and source fields | Expose what the source already returned. |
2 | Derived facts and evidence | Test each qualification signal cheaply. |
3 | Score | Rank only after evidence values have settled. |
4 | Contact data | Spend only on rows that passed the gate. |
A score is an ordinary column, not a replacement for evidence. It reads the evidence columns after they all have values, returns a value from 0 to 100 with reasons, and is useful when several criteria need one ranking. Treat missing evidence as unsure. Do not add a score when a simpler required gate is enough to decide whether to contact the row.
Signals the source cannot filter become evidence columns. Those columns should return a short verdict and the exact text that proves it, or unsure. Contact data is never proof of a different signal. The most selective and least expensive evidence should settle before a provider-backed lookup is allowed to run.
Bind real row fields
Reference source fields and upstream columns exactly as the worksheet returns them. Do not guess a field name from a label, provider, or another worksheet, and do not add a copy column merely to reach a source field. Source output fields arrive from source attachment, not from workbook creation.
After the source lands, use tables.findable_catalog.list with the worksheet table_id to find available enrichment needs. The default list is compact. Pass definition_id when you need one definition's inputs. Choose the returned enrichment by data need, not provider name. Use the returned add_call unchanged because its binding_spec.input_bindings names existing column keys. Check maintained enrichment presets before writing a new prompt because a named template can already contain bindings, inputs, conditions, and an estimate.
tables.columns.add creates a manual, formula, AI, tool, or enrichment column. A general AI column binds row fields into its prompt and states what it should judge, such as interest, intent, hiring, fit, score, category, evidence, or another signal. A provider-backed enrichment uses binding_spec and maps provider inputs from sibling columns. Adding the binding is free, internally reversible, and does not compute cell values.
Before adding a related column, call tables.columns.list. It is a free, read-only listing of the columns actually present, their bindings, and editable state. The response has no dependency edges, so use the column graph when you need those edges. Read the binding state again before changing a column so an edit does not overwrite someone else’s newer work.
| List response | What to inspect |
|---|---|
column | Column record and definition. |
binding | Configured source, AI, tool, formula, or enrichment binding. |
editable_state | Configuration, run condition, output fields, cost, revision, and last run. |
binding_read_warnings | Warnings returned while reading the binding. |
Run a bounded sample
tables.columns.run queues one column over a frozen row selection. It can call the provider named by the binding, has dynamic credit cost, and can spend real credits when a worker executes it. The operation is external and returns as soon as the run is enqueued, so no cell is filled merely because the queue response arrived.
The result includes run_id, status, state and authority versions and digests, outer-run identifiers, selection_snapshot_id, replay state, the effective maximum rows, and trial-cap fields. It runs one column rather than the full worksheet. Existing results follow the column’s existing-result policy unless force is true; force still preserves manual overrides and respects run_if and missing-dependency rules.
Use a one-row dry run first. Read its binding_preview for resolved real-row inputs, provider route, and credit estimate. Then make a live run with an explicit execution-envelope max_credits ceiling. The capability has a generic clamp of 25 credits per call, but the bound provider and volume determine actual cost.
Read the run and cells
Use runs.column_get to read counters for one canonical enrichment run. It is free and read-only. Its result contains the API run id and status plus total, processed, succeeded, failed, and skipped row counts, charged credits, and structured error data. Follow the run to a finished state, then inspect the cells that it wrote.
| Run field | What it tells you |
|---|---|
total_rows | Rows in the canonical enrichment run. |
processed_rows | Rows the run has processed. |
succeeded_rows | Rows whose work succeeded. |
failed_rows | Rows with failed work. |
skipped_rows | Rows the run skipped. |
charged_credits | Credits charged by the run. |
error_json | Structured error data for diagnosis. |
Check values, empty cells, failed cells, and the current run state. Empty, failed, and answered are distinct outcomes. A run that is still queued, pending, paced, capped, or unknown is not automatically a failure and is not zero. A completed queue request is not evidence that a row’s column value supports the qualification rule.
Read every sample row against the named criteria before scaling. If a value is empty, failed, or unrelated, locate the missing input, incorrect field reference, or wrong setting. Correct that specific cause and rerun only the affected scope. Do not hide a defect with a manual cell edit or a different provider, because the worksheet needs a traceable answer.
When a column does not produce the expected value
Start with the cell the user sees, its column binding, and the run that attempted to settle it. A column empty on every row can mean its gate reads a column that has not settled, or that it was added after rows landed and was never run on them. A score can be waiting on evidence that failed or is still running.
When a column is refused, read the reason and fix that input rather than changing column kind. When credits are higher than expected, inspect finished runs and charged credits: a repeated sample, contact data before a fit gate, or an expensive column before a cheap selective one are real causes. A cell blocked by a daily limit is workspace pacing, not a product defect.
Use the diagnostics skill to answer one question with the least evidence that settles it. Read first and change second. It classifies the object as still working, paced, waiting on an upstream column, missing a connection, receiving an empty provider answer, failed with an error, or likely defective. A retry that spends credits should be scoped to failed rows or the failed node and followed to a final result.