Implementation:Helicone Helicone VersionedRequestStore InsertRequestResponseVersioned

Knowledge Sources	Helicone
Domains	LLM Observability, Analytics Storage, OLAP Database
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete method for inserting processed LLM request-response log records into the ClickHouse request_response_rmt table, provided by the VersionedRequestStore class in the Jawn backend.

Description

VersionedRequestStore.insertRequestResponseVersioned is an asynchronous method that takes an array of RequestResponseRMT records and performs a bulk insert into the ClickHouse request_response_rmt table using clickhouseDb.dbInsertClickhouse. The insert uses JSONEachRow format with async_insert=1 and wait_end_of_query=1 settings for reliable cluster-safe ingestion.

The request_response_rmt table is a ReplacingMergeTree table that stores the full denormalized record for each LLM request. It contains 30+ columns including: response ID, timestamps, latency, status, token counts (prompt, completion, cache write, cache read, audio, reasoning), model, request ID, user ID, organization ID, proxy key ID, threat flag, time-to-first-token, provider, country code, target URL, properties (as a Map), scores (as a Map), request/response bodies, cost, assets, cache settings, passthrough billing flag, storage location, and size in bytes.

The VersionedRequestStore is scoped to an organization ID, which is used for subsequent property update queries but not directly in the insert method.

Usage

Call insertRequestResponseVersioned from the LoggingHandler at the end of the handler chain, once all enrichment (authentication, body parsing, cost computation, prompt extraction) has been applied to the log record.

Code Reference

Source Location

• Repository: Helicone
• File: valhalla/jawn/src/lib/stores/request/VersionedRequestStore.ts (lines 22-35)

Signature

async insertRequestResponseVersioned(
  requestResponseLog: RequestResponseRMT[]
): PromiseGenericResult<string>

Import

import { VersionedRequestStore } from "../../lib/stores/request/VersionedRequestStore";
import { RequestResponseRMT } from "../../lib/db/ClickhouseWrapper";

I/O Contract

Inputs

Name	Type	Required	Description
requestResponseLog	RequestResponseRMT[]	Yes	An array of fully denormalized log records to insert. Each RequestResponseRMT contains: request_id (string) -- UUID of the request. response_id (string) -- UUID of the response. request_created_at / response_created_at (string) -- ISO timestamps. latency (number) -- Response latency in milliseconds. status (number) -- HTTP status code. prompt_tokens / completion_tokens (number) -- Token counts. prompt_cache_write_tokens / prompt_cache_read_tokens (number) -- Cache token counts. prompt_audio_tokens / completion_audio_tokens / reasoning_tokens (number) -- Specialized token counts. model (string) -- The model used. organization_id (string) -- The owning organization. provider (string) -- The LLM provider. properties (Record<string, string>) -- Custom properties. scores (Record<string, number>) -- Evaluation scores. request_body / response_body (string) -- Serialized bodies or references. cost (number) -- Computed cost in USD. target_url (string) -- The upstream provider URL. user_id, proxy_key_id, country_code, threat, time_to_first_token, assets, cache_enabled, cache_reference_id, is_passthrough_billing, storage_location, size_bytes, ai_gateway_body_mapping.

Outputs

Name	Type	Description
result	PromiseGenericResult<string>	On success, data contains the ClickHouse query ID string. On failure, error contains a description of the insertion error.

Usage Examples

Basic Usage

import { VersionedRequestStore } from "../../lib/stores/request/VersionedRequestStore";

const store = new VersionedRequestStore(orgId);

const result = await store.insertRequestResponseVersioned([
  {
    request_id: "550e8400-e29b-41d4-a716-446655440000",
    response_id: "550e8400-e29b-41d4-a716-446655440001",
    request_created_at: "2026-02-14T10:00:00.000",
    response_created_at: "2026-02-14T10:00:00.350",
    latency: 350,
    status: 200,
    prompt_tokens: 150,
    completion_tokens: 80,
    prompt_cache_write_tokens: 0,
    prompt_cache_read_tokens: 0,
    prompt_audio_tokens: 0,
    completion_audio_tokens: 0,
    reasoning_tokens: 0,
    model: "gpt-4",
    organization_id: orgId,
    user_id: "user-123",
    proxy_key_id: "",
    threat: false,
    time_to_first_token: 120,
    provider: "OPENAI",
    country_code: "US",
    target_url: "https://api.openai.com/v1/chat/completions",
    properties: { "Helicone-Session-Id": "sess-1" },
    scores: {},
    request_body: "{}",
    response_body: "{}",
    cost: 0.0069,
    assets: [],
    cache_enabled: false,
    is_passthrough_billing: false,
    ai_gateway_body_mapping: "",
    storage_location: "s3",
    size_bytes: 1536,
  },
]);

if (result.error) {
  console.error("Insert failed:", result.error);
}

Related Pages

Implements Principle

• Principle:Helicone_Helicone_Analytics_Storage

Uses Heuristic

• Heuristic:Helicone_Helicone_ClickHouse_ReplacingMergeTree_FINAL