Flows

Using record steps (get/list/upsert)

Use record steps to retrieve, create, update, and search Records in the Runtype Record store. Records hold JSON metadata that your Flows can reference.

For more information about Records, see What are Records?.

Get Record step

Use Get Record when you need one Record. The step returns one object.

Add a Get Record step

To add a Get Record step, follow these steps:

  1. On the Flow editor, click Add Step.
  2. Select Get Record.
  3. Choose one of these lookup methods:
    • Record ID: Look up a 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. For more information, see Filtering and searching records.
  4. Click Save Step.

When multiple Records match, Get Record returns the Record with the newest update time. When no Record matches, the step fails and reports an error that begins with Record not found.

Read the result

After the step runs, read fields from the object stored in its output variable. If the output variable is customer, use these references:

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

List Records step

Use List Records when the lookup can return zero, one, or multiple Records. The step returns an array of Records.

Add a List Records step

To add a List Records step, follow these steps:

  1. On the Flow editor, click Add Step.
  2. Select List Records.
  3. Choose one of these lookup methods:
    • Record type + name: Look up Records by type and name.
    • Record filter: Look up Records with filter conditions.
  4. Set Limit when you need a different result count. The default is 50, and the maximum is 1000. Set On empty to Succeed or Fail. The default is Succeed.
  5. Click Save Step.

List Records orders results by update time, with the newest first. When no Records match, the step returns an empty array and succeeds with the default On empty setting. Set On empty to Fail when no matches must fail the step.

Read the results

List Records always returns an array, even when one Record matches. If the output variable is customers, index the array before you read a field:

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

Use either dot indexing or bracket indexing. The following references return the first Record and the number of matches:

{{customers.0.metadata.tier}}
{{customers[0].metadata.tier}}
{{customers.length}}

Choose between Get Record and List Records

Choose Get Record when you need one object, such as a lookup by ID or a unique name. Choose List Records when the number of matches can vary, such as a lookup for every open ticket for a customer.

Migrating from retrieve-record

The retrieve-record step is deprecated. Replace it with Get Record when you need one object, or replace it with List Records when you need an array. Existing Flows that use retrieve-record continue to run.

At execution time, Runtype resolves an ID lookup as Get Record. It resolves a type, name, or filter lookup as List Records. The List Records alias uses a limit of 1000 and fails when no Record matches, which preserves the legacy query behavior.

When you edit a Flow that uses retrieve-record, replace it with the step that matches the required return shape. For save-time checks, see Flow validation warnings.

Upsert Record step

Use Upsert Record to create a Record or update an existing Record. The step stores the source variable as the Record metadata.

Add an upsert step

To add an Upsert Record step, follow these steps:

  1. On the Flow editor, click Add Step.
  2. Select Upsert Record.
  3. Set the fields that identify the Record and provide its metadata:
    • Name: Enter a descriptive label, such as Save conversation.
    • Record type: Select the Record collection.
    • Source Variable: Enter the outputVariable name from a previous step that contains the metadata object.
    • Record Name: Enter a stable name to select the Record to update.
  4. Click Save Step.

The step uses the recordType and recordName values as the upsert key. If a Record with the same type and name exists, the step updates it. If you omit Record Name, the step generates a name from the Record type and execution time.

Set the source variable

Set sourceVariable to a variable that resolves to a JSON object. The object becomes the Record metadata. If a Prompt step produces the object, set Response Format to JSON.

The following object shows a valid source value:

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

In this example, customerId, summarize_result, and analyze_sentiment refer to values from previous steps. {{_now.iso}} inserts the execution timestamp.

A plain-text source value fails the JSON-object contract unless you set contentField to wrap the text in an object. You can also add a Transform Data step that converts the text to an object. The flow validator reports this issue as UPSERT_RECORD_SOURCE_NOT_JSON.

Vector Search step

Use Vector Search to find Records by semantic similarity. The step searches a connected vector store, such as Weaviate, pgvector, or Vectorize.

Add a Vector Search step

To add a Vector Search step, follow these steps:

  1. On the Flow editor, click Add Step.
  2. Select Vector Search.
  3. Set the search fields:
    • Name: Enter a descriptive label.
    • Query: Enter the text to search for.
    • Vector store: Select a connected vector store.
    • Output Variable: Enter the name for the results.
  4. Click Save Step.

Read search results

Vector Search returns an array of matching Records. If the output variable is search_results, read fields from an indexed result like this:

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

Build a retrieval-augmented generation flow

A retrieval-augmented generation (RAG) flow retrieves relevant Record content and passes it to a prompt. Build the pattern with these steps:

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

Use a prompt like the following to answer a question from search results:

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

This prompt reads the question variable and the first two items in the search_results array. Before you use semantic search, create embeddings for the content with Generate Embedding and store them with Store Vector.

Handle missing results

Choose the step behavior that matches how you handle missing Records:

  • Use Get Record when no match must fail the step.
  • Use List Records with the default On empty value of Succeed when no match is an expected result.
  • Set On empty to Fail when a List Records step must fail on an empty result.

After a List Records step writes to customers, add a Conditional step that checks the array length. Use a condition like this:

Conditional: {{customers.length}} > 0
  If true: Use Record data
  Else: Handle missing Records with default values or an error message

Apply record step practices

Follow these practices when you configure record steps:

  • Index frequently searched fields: Index fields that you query often.
  • Keep metadata concise: Store fields that your Flows use in queries or prompts.
  • Use stable names for upserts: Set a stable Record Name when later runs must update the same Record.
  • Set a List Records limit: Use a Limit that matches the number of Records that the Flow needs. The default is 50, and the maximum is 1000.

Next steps

Continue with these related topics: