Using record steps (upsert/retrieve)

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.

Retrieve Record step

Fetch a specific Record by ID or unique field.

Add a retrieve step

1. Click Add Step
2. Select Retrieve Record
3. Configure:
   • Name: Descriptive label (e.g., “Get customer data”)
   • Record type: Select the Record collection
   • Lookup field: Field to match (e.g., id, email)
   • Lookup value: Value to search for (e.g., {{customerId}})
4. Click Save Step

The step returns the matching Record or null if not found.

Accessing retrieved data

Reference the step’s outputVariable name directly:

{{customer_data.metadata.customerName}}
{{customer_data.metadata.tier}}
{{customer_data.id}}

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, Pinecone, 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. Retrieve Record 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 missing Records:

Conditional: {{customer_data}} != null
  If true: Use Record data
  Else: Handle missing Record (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
• Limit search results: Don’t retrieve more Records than needed

Next steps

• What are Records? for detailed Record concepts
• Creating and managing records to populate your Record store
• Using records in flows for more advanced patterns
• Using prompt steps to generate answers from retrieved context