Using records in flows | Runtype Documentation

Use Records in Flows to retrieve structured context, personalize responses, and build retrieval-augmented generation (RAG) flows.

Common patterns

Use one of these patterns to add Records to a Flow.

Build a retrieval-augmented generation flow

Build a RAG flow with these steps:

Vector Search: Find Records that match the question by semantic similarity.
Run Code: Extract and format the matching content.
Run Task: Generate an answer from the formatted context.

Use a prompt that limits the answer to the supplied context:

Answer this question using only the provided context.
Question: {{question}}
Context:
{{searchResults[0].metadata.content}}
{{searchResults[1].metadata.content}}
If the context does not contain enough information, say that you do not have enough information to answer.
Answer:

In this example, question contains the incoming question and searchResults contains the Vector Search output.

Personalize responses

Pass customer data to Run Task with these steps:

Get Record: Retrieve the customer Record by ID, type and name, or record filter.
Run Task: Reference the customer metadata when you generate the response.

Use a prompt like this:

Customer message: {{message}}
Customer information:
- Name: {{customer.metadata.name}}
- Tier: {{customer.metadata.tier}}
- Order history: {{customer.metadata.orderCount}} orders
Provide a response that matches the customer's tier.

Set the Get Record output variable to customer so these references resolve.

Cache API results

Cache an API response in a Record with this sequence:

List Records: Check for a matching cached Record with On empty set to Succeed.
Conditional Logic: Call the external API when cachedResults.length is 0.
Upsert Record: Store the API response as Record metadata.

Pass either the cached response or the fresh API response to the next step.

Store conversation history

Store conversation history as Record metadata with these steps:

Get Record or List Records: Retrieve the conversation Record by ID, type and name, or record filter.
Run Task: Generate a response from the conversation history.
Upsert Record: Store the updated history as metadata.

Use List Records with On empty set to Succeed when the first interaction might not have a conversation Record.

Look up Records

Use Get Record when you need one Record. 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 exact or partial metadata conditions.

The step orders matching Records by updatedAt descending and returns the first match. It fails when no Record matches.

Use this Get Record configuration to look up a customer by ID:

Step: Get Record
Record ID: {{customerId}}
Output variable: customer

If no match is expected, use List Records. It returns an array and, with the default On empty value of Succeed, returns [] when no Record matches. The default Limit is 50, and the maximum is 1000.

Set Record filter to an object like this to find a customer by email:

1 {
2   "type": "customers",
3   "where": {
4     "op": "and",
5     "conditions": [
6       {
7         "field": "email",
8         "op": "eq",
9         "value": "{{customerEmail}}"
10       }
11     ]
12   }
13 }

In this example, customerEmail is the Flow variable that contains the email address.

After List Records writes to customerMatches, check the array length with a Conditional Logic step:

Conditional Logic: {{customerMatches.length}} > 0
  If true: Use existing customer data
  Else: Create a customer Record

Retrieve multiple Records

Use List Records for structured queries that return zero or more matches. Use Vector Search for semantic similarity. Both steps return arrays.

Pass the array to Run Code to select fields and build context for Run Task.

Create and update Records

Use Upsert Record to create a Record or update an existing Record. The step uses recordType and recordName as the upsert key and stores the source variable as Record metadata.

Use this configuration to store an analysis object:

Step: Upsert Record
Record type: analytics
Record name: {{eventId}}
Source variable: analysisResult
Output variable: upsertedRecord

In this example, analysisResult must resolve to a JSON object, and eventId identifies the Record. If the source is a string, set contentField to wrap it in an object, or use Run Code to return an object. If a Run Task step produces the source, set Response Format to JSON.

Use mergeStrategy to choose merge or replace when Upsert Record updates an existing Record.

Use Update Record to modify metadata on an existing Record with an updates object. Target the Record by ID, type and name, or record filter, and set mergeStrategy to control how the update applies.

Choose the step that matches the lookup result that you need:

Use Vector Search to find Records by semantic similarity.
Use Get Record to return one Record for an ID or structured lookup.
Use List Records to return an array for a structured lookup with zero or more matches.

Handle missing Records

Handle missing Records according to the step’s result shape:

Use Get Record when no match must fail the step.
Use List Records with On empty set to Succeed when no match is expected.
Set On empty to Fail when no match must fail a List Records step.

After a List Records step writes to recordMatches, use this condition to detect an empty result:

Conditional Logic: {{recordMatches.length}} == 0
  If true: Handle the missing Records
  Else: Continue with the matching Records

Apply record step practices

Apply these practices when you build Flows with Records:

Store only metadata fields that your Flows query or pass to Run Task.
Use stable Record types and names when repeated runs must target the same Record.
Set Limit to the number of Records that the Flow needs.
Set recordType on Vector Search when you need to scope the search to one Record type.
Test semantic search with representative questions and review the returned Records.
Keep historical Records and mark them inactive in metadata when you need historical state.

Example: full RAG flow

Combine Vector Search, Run Code, and Run Task with this flow:

Add a Vector Search step with documentation as Record type, {{userQuestion}} as Query, 3 as Limit, and searchResults as Output variable.

Add a Run Code step and use this script to combine the matching content:

1 const context = searchResults
2   .map((record) => record.metadata?.content)
3   .filter(Boolean)
4   .join('\n\n')
5 
6 return { context }

Set the Run Code output variable to formatContext.

Add a Run Task step and use this prompt:

Answer the question using only this context.
Context:
{{formatContext.context}}
Question:
{{userQuestion}}
If the context does not contain enough information, say that you do not have enough information to answer.
Answer:

Set the Run Task output variable to answerQuestion.

In this flow, searchResults is the Vector Search output, formatContext is the Run Code output, and answerQuestion is the generated answer.

Next steps

Using record steps (get/list/upsert): configure Record steps.
Filtering and searching records: build exact and semantic queries.
Creating and managing records: create and organize Records.
Using prompt steps: generate text or structured data from Record context.