ACTION_ID: lookup_another_floqer_workflow_row
NAME: Lookup Row from a Floqer Table
CATEGORY: Data Operations
CREDITS: 0

Look up a row in another Floqer table by matching a column value.
Returns the matched row(s) plus a count of matches.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

table_to_search (string, required) — Target Table
  The destination sheet to search. Pass a `sheet_id` (UUID) for any
  sheet the caller's org owns — typically the master sheet that
  already holds the rows you want to find (e.g. "All Companies",
  "All Contacts").

  Discovering the value:
    1. GET /api/v1/workflows                                 -> pick the workflow.
    2. GET /api/v1/workflows/{workflow_id}/sheets            -> pick the sheet.
       Pass the sheet's `sheet_id` here. For the main sheet,
       `sheet_id` equals the workflow's own ID, so step 2 is
       optional — the workflow_id from step 1 works as a
       sheet_id directly.

  Example: "table_to_search": "7dca51c6-1308-4501-81a0-8d655c3bfd2a"

target_column (string, required) — Target Column
  Identifier of the column on `table_to_search` to match on. This
  is a UUID — get it via Get Action Field Options:

    POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/
         {action_instance_id}/options/target_column
    Body: { "context": { "target_table": "<sheet_id from above>" } }

  The response is `{ options: [{ value, label }, ...] }` where
  each `value` is the column's id and `label` is the
  column's display name (e.g. "Email", "Domain"). Pass the chosen
  `value` straight into Configure Action — there's no separate
  lookup; the column id is what storage and the engine use.

  Note on naming: the options-call context key is `target_table`
  (NOT `table_to_search`). This is the only place where the two
  names diverge — everywhere else in the Configure Action body the
  field is `table_to_search`.

operator (string, required) — Operator
  Match operator. Allowed values:
    "eq"        exact match.
    "contains"  substring match. Slower; prone to false positives.
                Use only when an exact key isn't available.

value (string, required) — Target Value
  The value to search for. Can be a variable reference (e.g.
  `{{input.email}}`) or a static string. References resolve
  per-row at run time.

find_all (boolean, optional) — Find All Rows
  Match one vs. match all. Default `false`.
    false  returns the first match as a single object.
    true   matches every row that satisfies the operator, returned
           as an array of objects.
  This flag also changes the shape of the `record` output — see
  section 2.

================================================================================
2. OUTPUTS
================================================================================

record (object) — the matched row(s).
  - When `find_all: false` (default): an object containing the
    matched row's fields keyed by their display names, or an empty
    object `{}` when nothing matched.
  - When `find_all: true`: an array of objects — one per matching
    row — or an empty array `[]` when nothing matched.

  The fields inside each object are whatever inputs the target
  sheet has (e.g. `email`, `domain`, `company_name`). Reference
  individual fields downstream as
  `{{<this_action_instance_id>.record.<field>}}` for the single
  case, or shape the array with
  `format_data_using_js_expression` for the multi case.

total (number) — total number of records that matched. `0` means
  no match. Always populated regardless of `find_all`.

================================================================================
3. HOW TO CONFIGURE
================================================================================

Discovery flow (resolves the target sheet and column id before
Configure Action):

  1. Add the action.
       POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/add
       Body: { "action_id": "lookup_another_floqer_workflow_row" }
     Returns the new `action_instance_id`.

  2. Pick the target sheet via List Workflows + List Sheets.
       GET /api/v1/workflows
       GET /api/v1/workflows/{target_workflow_id}/sheets
     Take the chosen sheet's `sheet_id`. For the workflow's main
     sheet, `sheet_id === workflow_id` so step 2 is optional.

  3. Resolve `target_column` via Get Action Field Options.
       POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/
            actions/{action_instance_id}/options/target_column
       Body: { "context": { "target_table": "<target_sheet_id>" } }
     Pick the chosen option's `value` (a UUID) for the column you
     want to match on. The options call works without first PATCHing
     anything on the action — pass `target_table` inline in the
     context.

  4. Configure the action with all five fields in a single PATCH.
       PATCH /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/
             actions/{action_instance_id}
       Body:
       {
         "inputs": {
           "table_to_search": "<target_sheet_id>",
           "target_column":   "<value from step 3>",
           "operator":        "eq",
           "value":           "{{input.email}}",
           "find_all":        false
         }
       }

Field-by-field:
  - table_to_search  `sheet_id` (UUID) of the destination sheet.
  - target_column    id (UUID) of the column to match on (from
                     Get Action Field Options).
  - operator         `"eq"` or `"contains"`.
  - value            String literal or `{{...}}` reference.
  - find_all         Boolean. `false` (default) returns one match;
                     `true` returns all matches as an array.

================================================================================
4. KEY NOTES
================================================================================

- Always branch on `total` before reading fields off `record` —
  `total === 0` means the lookup found nothing.
- `record` shape depends on `find_all`: object when `false`, array
  of objects when `true`. Downstream actions that read individual
  fields work for the single-match case; for multi-match, use
  `format_data_using_js_expression` to iterate.
- `target_column` is the column's id (UUID), NOT the column's
  snake_case name. Always pass the `value` returned by Get Action
  Field Options — typing a column name directly (e.g. `"email"`)
  will fail at run time.
- Get Options for `target_column` requires the target sheet id in
  the context, passed under the key `target_table` (NOT
  `table_to_search`). This is the one place the legacy and new
  names diverge: PATCH uses `table_to_search`; the options-call
  context uses `target_table`. Either pass it inline in the
  `context` body (recommended), or PATCH `table_to_search` first
  and then call options.
- Free to run (0 credits).

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

UPSTREAM — what feeds the lookup
  The current row carries the key (email, domain, etc.) you want
  to match against the destination table. The key reaches this
  action via {{input.<field>}} — populated by an inbound trigger,
  webhook, list ingest, or an upstream enrichment step.

THIS ACTION
  Searches `table_to_search` for rows where `target_column` matches
  `value` under `operator`. Returns `record` + `total`.

DOWNSTREAM — typical chains
  Branch on found:
    this -> filter (total > 0) -> reuse data from `record`
                                  (enrichment, outreach, update).
  Branch on not found:
    this -> filter (total == 0) -> enrichment / create-row path.
  Cross-table consolidation:
    this -> push_data_to_sheet or google_sheet_upsert_row to merge
            the looked-up record into the current sheet.

================================================================================
6. WHEN TO USE
================================================================================

Use lookup_another_floqer_workflow_row to reuse data that already
lives in another Floqer table.

Common patterns:
  - You run multiple use cases against the same list. Centralize
    the list in one master sheet, then look it up from each
    downstream workflow so enrichments aren't re-run.
  - You want to skip work that's already been done. Look the row
    up before paying for an enrichment or outreach step.
  - You need to read context from a master table onto a row in a
    campaign sheet.

================================================================================
7. WHEN NOT TO USE
================================================================================

Need to send rows to another sheet or Floq, not read from one
  -> push_data_to_sheet
     (https://floqer.com/docs/action-detail/push_data_to_sheet.txt)
  -> push_data_to_another_floqer_workflow
     (https://floqer.com/docs/action-detail/push_data_to_another_floqer_workflow.txt)

================================================================================

This file is maintained manually. Last updated: 2026-05-13.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt