Flows

Using record steps (get/list/upsert)

Record steps let Flows interact with Runtype’s Record store to retrieve data, save results, or search for relevant information.

What are Records?

Records are structured data entries with JSON metadata. Use them to store customer data, knowledge bases, Product catalogs, or any information your Flows need to reference.

See What are Records? for a full overview.

Get Record step

Fetch a single Record. Use this when your Flow needs exactly one record.

Add a Get Record step

  1. Click Add Step
  2. Select Get Record
  3. Configure a lookup:
    • Record ID: Look up a specific Record by its ID
    • Record type + name: Look up a Record by its type and name
    • Record filter: Look up a Record with filter conditions (see Filtering and searching records)
  4. Click Save Step

If more than one Record matches a type/name/filter lookup, Get Record returns the most recently updated one. If no Record matches, the step fails with “Record not found” — what happens next depends on the step’s error handling setting.

Accessing the result

Get Record always returns a single object, so reference fields directly:

{{customer.metadata.tier}}
{{customer.metadata.customerName}}
{{customer.id}}

List Records step

Fetch every Record matching a lookup, as an array. Use this when your Flow may need zero, one, or many records.

Add a List Records step

  1. Click Add Step
  2. Select List Records
  3. Configure a lookup:
  4. Optionally set Limit (defaults to 50, maximum 1000) and On empty (Succeed or Fail, defaults to Succeed)
  5. Click Save Step

Results are ordered most recently updated first. When no Records match, List Records returns an empty array and the step succeeds. Set On empty to Fail if the Flow should stop when there are no matches instead.

Accessing the results

List Records always returns an array, even when only one Record matches. Index into it before reading a field:

{{customers.0.metadata.tier}}
{{customers.0.metadata.customerName}}
{{customers.0.id}}

Both dot-index ({{customers.0.metadata.tier}}) and bracket-index ({{customers[0].metadata.tier}}) work. Use {{customers.length}} to check how many Records matched.

Choosing between Get Record and List Records

Use Get Record when you expect exactly one match, such as looking up a customer by ID or a unique record name. Use List Records when the number of matches can vary, such as pulling every open ticket for a customer.

Migrating from retrieve-record

The older Retrieve Another Record step (retrieve-record) is deprecated in favor of Get Record and List Records, but existing Flows that use it keep working without changes. At execution, Runtype resolves a retrieve-record step automatically: an ID-based lookup behaves exactly like Get Record, and a type/name/filter lookup behaves exactly like List Records, preserving the old behavior of failing when nothing matches.

When you next edit a Flow that still uses retrieve-record, replace it with Get Record if you expect a single match, or List Records if you expect several. See Flow validation warnings for the save-time checks that flag both the deprecated step type and return-shape mistakes.

Upsert Record step

Create a new Record or update an existing one.

Add an upsert step

  1. Click Add Step
  2. Select Upsert Record
  3. Configure:
    • Name: Descriptive label (e.g., “Save conversation”)
    • Record type: Select the Record collection
    • Source Variable: The outputVariable name from a prior step that contains a JSON object
    • Record Name: Optional name to match for updates
  4. Click Save Step

Source variable

The sourceVariable must point to a JSON object from a previous step. For example, if a prompt step outputs JSON to analysis_result, use analysis_result as the source variable.

1{
2  "customerId": "{{customerId}}",
3  "conversationSummary": "{{summarize_result}}",
4  "sentiment": "{{analyze_sentiment.label}}",
5  "timestamp": "{{_now.iso}}"
6}

If the unique field matches an existing Record, it is updated. Otherwise, a new Record is created.

Important: The sourceVariable must reference a JSON object, not a plain text string. If using a prompt step to produce the data, set responseFormat to json.

Vector Search step

Find Records by semantic similarity using vector embeddings. This works with your connected vector store (Weaviate, pgvector, or Cloudflare Vectorize).

Add a vector search step

  1. Click Add Step
  2. Select Vector Search
  3. Configure:
    • Name: Descriptive label
    • Query: The text to search for
    • Vector store: Select your connected store
    • Output Variable: Name for the results
  4. Click Save Step

Accessing search results

Vector search returns an array of matching Records:

{{search_results[0].metadata.answer}}
{{search_results[1].metadata.content}}

RAG pattern

Common workflow for question answering with Records:

  1. Get Record, List Records, or Vector Search: Find relevant documents for the user question
  2. Transform Data: Extract and format retrieved context
  3. Prompt: Generate answer using retrieved context

Example prompt:

Answer this question using only the provided context.
Question: {{question}}
Context:
{{search_results[0].metadata.content}}
{{search_results[1].metadata.content}}
Answer:

For semantic search, Records must have embeddings. Use the Generate Embedding and Store Vector steps to index content.

Error handling

Handle a Get Record step that finds no match. By default the step fails; set its error handling to continue on error if you want the Flow to proceed with null instead:

Conditional: {{customer_data}} != null
  If true: Use Record data
  Else: Handle missing Record (default values, error message, etc.)

Handle a List Records step that returns no matches by checking the array length, which works with the default (non-failing) empty-result behavior:

Conditional: {{customers.length}} > 0
  If true: Use Record data
  Else: Handle missing Records (default values, error message, etc.)

Best practices

  • Index frequently searched fields: Improves query performance
  • Keep metadata concise: Only store data you’ll actually use
  • Use unique fields for upserts: Prevents duplicate Records
  • Set a limit on List Records: Lower the default 50 (or raise it, up to 1000) to match what your Flow actually needs

Next steps