Documentation Index
Fetch the complete documentation index at: https://docs.hipocap.com/llms.txt
Use this file to discover all available pages before exploring further.
Query all your Laminar data directly with SQL. Find patterns, debug issues, and answer questions the dashboard doesn’t anticipate.
What You Can Query
| Table | Contains |
|---|
| spans | Individual spans (LLM/tool/custom/eval spans) |
| traces | Trace-level aggregates derived from spans |
| events | Custom events you’ve sent |
| tags | Tags attached to spans |
| dataset_datapoints | Dataset datapoints (latest version per datapoint) |
| dataset_datapoint_versions | Dataset datapoints (all versions/history) |
| evaluation_datapoints | Evaluation datapoints incl. scores (JSON map), executor output, and dataset links |
SELECT queries are allowed.
Getting Started
Open the SQL Editor from the sidebar. Write a query:
SELECT name, input, output, start_time
FROM spans
WHERE start_time > now() - INTERVAL 3 DAY
/v1/sql/query—authenticate with your project API key and pass { "query": "..." }.
Writing Queries
Laminar uses ClickHouse, a columnar analytics database. The basics work like standard SQL (SELECT, FROM, WHERE, GROUP BY, ORDER BY, LIMIT), with a few differences.
Always filter by time
Spans are ordered by start_time. Adding a time filter dramatically speeds up queries and prevents memory issues:
-- Slow: scans everything
SELECT * FROM spans WHERE trace_id = 'abc-123'
-- Fast: scans only relevant time range
SELECT * FROM spans
WHERE trace_id = 'abc-123'
AND start_time > now() - INTERVAL 1 DAY
Avoid joins
ClickHouse isn’t optimized for joins. Instead, run two queries and combine results in your application:
-- First: find the spans you care about
SELECT trace_id, name, input, output
FROM spans
WHERE span_type = 'LLM' AND start_time > now() - INTERVAL 1 DAY
-- Second: get trace-level data for those trace_ids
SELECT id, duration
FROM traces
WHERE id IN ('id1', 'id2', 'id3')
Working with dates
Truncate timestamps for grouping with toStartOfInterval:
-- Spans per day over the last month
SELECT
toStartOfInterval(start_time, INTERVAL 1 DAY) AS day,
count(*) AS span_count
FROM spans
WHERE start_time > now() - INTERVAL 1 MONTH
GROUP BY day
ORDER BY day
INTERVAL 15 MINUTE, INTERVAL 1 HOUR, etc.
Shortcuts exist for common intervals: toStartOfDay(value), toStartOfHour(value), toStartOfWeek(value).
Working with JSON
Many columns (like attributes) store JSON as strings. Use simpleJSONExtract* functions for fast extraction:
-- Extract token counts from LLM spans
SELECT
name,
simpleJSONExtractInt(attributes, 'gen_ai.usage.input_tokens') AS input_tokens,
simpleJSONExtractInt(attributes, 'gen_ai.usage.output_tokens') AS output_tokens
FROM spans
WHERE span_type = 'LLM' AND start_time > now() - INTERVAL 1 DAY
simpleJSONHas:
SELECT count(*)
FROM spans
WHERE simpleJSONHas(attributes, 'gen_ai.request.structured_output_schema')
JSONExtract* functions—more flexible but slower.
Data types
| Type | Used for |
|---|
UUID | Most ID columns (trace_id, span_id, id) |
DateTime64(9, 'UTC') | Timestamps (always UTC) |
String | Text, JSON stored as strings, and enum-like columns (span_type, trace_type, status, tags.source) |
LowCardinality(String) | Low-cardinality enums (for example, events.source) |
Float64 | Floating point numbers |
Int64 | Counts, token numbers |
UInt64 | Indexes and counters (evaluation_datapoints.index) |
Bool | Flags like has_browser_session |
Array(String) | Tag lists and other string arrays |
CAST(value AS Type) or toDateTime64('2025-01-01 00:00:00', 9, 'UTC').
Table Schemas
These are the logical tables exposed in the SQL Editor. The schemas below reflect the columns available for queries.
spans
| Column | Type | Example value |
|---|
span_id | UUID | "00000000-0000-0000-1234-426614174000" |
name | String | "openai.chat" |
span_type | String | "LLM" |
start_time | DateTime64(9, 'UTC') | "2021-01-01 00:00:00" |
end_time | DateTime64(9, 'UTC') | "2021-01-01 00:00:00" |
duration | Float64 | 1.23 |
input_cost | Float64 | 0.5667 |
output_cost | Float64 | 0.123 |
total_cost | Float64 | 0.6897 |
input_tokens | Int64 | 150 |
output_tokens | Int64 | 100 |
total_tokens | Int64 | 250 |
request_model | String | "gpt-4.1-mini" |
response_model | String | "gpt-4.1-mini-2025-04-14" |
model | String | "gpt-4.1-mini-2025-04-14" |
trace_id | UUID | "12345678-90ab-cdef-1234-426614174000" |
provider | String | "openai" |
path | String | "workflow.process.step1.openai.chat" |
input | String | "[{\"role\": \"user\", \"content\": \"Hello\"}]" |
output | String | "[{\"role\": \"assistant\", \"content\": \"Hi\"}]" |
status | String | "success" |
parent_span_id | UUID | "00000000-0000-0000-a456-abcd5667ef09" |
attributes | String | "{\"gen_ai.system\": \"openai\", \"gen_ai.model\": \"gpt-4o\"}" |
tags | Array(String) | ["needs-review", "tool-call"] |
Path
Laminar span path is stored as an array of span names in span attributes. However, in SQL queries, it is stored as a string with items joined by a dot.
For example, if the span path is ["outer", "inner"], the path column will be "outer.inner".
If needed, you can still access the array value by reading attributes with simpleJSONExtractRaw(attributes, 'lmnr.span.path').
Parent span ID
If the current span is the top span of the trace, the parent_span_id will be a 0 UUID, i.e. "00000000-0000-0000-0000-000000000000".
Span type
Here are the values of the span_type column and their meanings:
DEFAULT
LLM
EXECUTOR
EVALUATOR
EVALUATION
TOOL
HUMAN_EVALUATOR
EVENT
UNKNOWN
Status
Status is normalized to "success" or "error".
The input and output columns are stored as either raw strings or stringified JSON. The best way to parse them is to try to parse them as JSON, and if it fails, use the raw string. You can also use isValidJSON function right in the query to test for this.
input and output columns are also indexed on content, so you can use them in WHERE conditions. Use ILIKE instead of LIKE, because the index is case-insensitive.
Attributes
The attributes column is stored as a string in JSON format. That is, you can safely JSON.parse / json.loads them. In addition, you can use JSON* and simpleJSON* functions on them right in the queries. Attributes are guaranteed to be a valid JSON object.
Model
The model column is set to the response model if present, otherwise it is set to the request model.
Total tokens and total cost
Usually, total_tokens = input_tokens + output_tokens and total_cost = input_cost + output_cost.
However, you can manually report these values using the relevant attributes. In this case, totals may not be equal to the sum of the input and output tokens and costs.
traces
| Column | Type | Example value |
|---|
id | UUID | "01234567-1234-cdef-1234-426614174000" |
start_time | DateTime64(9, 'UTC') | "2021-01-01 00:00:00" |
end_time | DateTime64(9, 'UTC') | "2021-01-01 00:00:00" |
input_tokens | Int64 | 150 |
output_tokens | Int64 | 100 |
total_tokens | Int64 | 250 |
input_cost | Float64 | 0.5667 |
output_cost | Float64 | 0.123 |
total_cost | Float64 | 0.6897 |
duration | Float64 | 1.23 |
metadata | String | "{\"key\": \"value\"}" |
session_id | String | "session_123" |
user_id | String | "user_123" |
status | String | "success" |
top_span_id | UUID | "00000000-0000-0000-1234-426614174000" |
top_span_name | String | "run" |
top_span_type | String | "DEFAULT" |
trace_type | String | "DEFAULT" |
tags | Array(String) | ["needs-review", "production"] |
has_browser_session | Bool | true |
id is the trace ID; join to spans with spans.trace_id = traces.id.
Trace type
Here are the values of the trace_type column and their meanings:
DEFAULT
EVALUATION
PLAYGROUND
Duration
The duration is in seconds, and is calculated as end_time - start_time.
Status
Status is set to error if any span in the trace has status error, otherwise it is success.
Metadata is stored as a string in JSON format. That is, you can safely JSON.parse / json.loads it. In addition, you can use JSON* and simpleJSON* functions on it right in the queries. Metadata is guaranteed to be a valid JSON object.
events
| Column | Type | Example value |
|---|
id | UUID | "01234567-89ab-4def-1234-426614174000" |
span_id | UUID | "00000000-0000-0000-1234-426614174000" |
name | String | "My custom event" |
timestamp | DateTime64(9, 'UTC') | "2021-01-01 00:00:00" |
attributes | String | "{\"key\": \"value\"}" |
user_id | String | "user_123" |
session_id | String | "session_123" |
trace_id | UUID | "01234567-1234-cdef-1234-426614174000" |
source | LowCardinality(String) | "CODE" |
Attributes
The attributes column is stored as a string in JSON format. That is, you can safely JSON.parse / json.loads it. In addition, you can use JSON* and simpleJSON* functions on it right in the queries. Attributes are guaranteed to be a valid JSON object.
Source
source is either "CODE" or "SEMANTIC".
| Column | Type | Example value |
|---|
id | UUID | "01234567-89ab-4def-1234-426614174000" |
span_id | UUID | "00000000-0000-0000-1234-426614174000" |
name | String | "needs-review" |
created_at | DateTime64(9, 'UTC') | "2021-01-01 00:00:00" |
source | String | "HUMAN" |
Source
source is "HUMAN" (set in the Laminar UI), "CODE" (attached from code), or "UNKNOWN".
evaluation_datapoints
| Column | Type | Example value |
|---|
id | UUID | "01234567-89ab-4def-1234-426614174000" |
evaluation_id | UUID | "98765432-1098-4654-3210-987654321098" |
data | String | "{\"key\": \"value\"}" |
target | String | "{\"key\": \"value\"}" |
metadata | String | "{\"key\": \"value\"}" |
executor_output | String | "{\"key\": \"value\"}" |
index | UInt64 | 0 |
trace_id | UUID | "01234567-1234-cdef-1234-426614174000" |
group_id | String | "group_a" |
scores | String | "{\"score1\": 0.85}" |
created_at | DateTime64(9, 'UTC') | "2021-01-01 00:00:00" |
dataset_id | UUID | "00000000-0000-0000-0000-000000000000" |
dataset_datapoint_id | UUID | "00000000-0000-0000-0000-000000000000" |
dataset_datapoint_created_at | DateTime64(9, 'UTC') | "1970-01-01 00:00:00" |
data, target, metadata, executor_output, and scores are JSON stored as strings. scores is a JSON object of string keys to numeric values.
When the datapoint is not sourced from a dataset, dataset_id and dataset_datapoint_id are a nil UUID (all zeroes) and dataset_datapoint_created_at is the Unix epoch.
dataset_datapoints
| Column | Type | Example value |
|---|
id | UUID | "01234567-89ab-4def-1234-426614174000" |
created_at | DateTime64(9, 'UTC') | "2021-01-01 00:00:00" |
dataset_id | UUID | "11111111-2222-3333-4444-555555555555" |
data | String | "{\"query\": \"What is 2+2?\"}" |
target | String | "{\"answer\": \"4\"}" |
metadata | String | "{\"source\": \"prod\"}" |
data, target, and metadata are JSON stored as strings.
dataset_datapoint_versions
Same schema as dataset_datapoints, but includes all versions and history for each datapoint.
Example Queries
Cost breakdown by model:
SELECT
model,
sum(total_cost) AS total_cost,
count(*) AS call_count
FROM spans
WHERE span_type = 'LLM' AND start_time > now() - INTERVAL 7 DAY
GROUP BY model
ORDER BY total_cost DESC
SELECT name, avg(end_time - start_time) AS avg_duration_ms
FROM spans
WHERE start_time > now() - INTERVAL 1 DAY
GROUP BY name
ORDER BY avg_duration_ms DESC
LIMIT 10
SELECT
name,
countIf(status = 'error') AS errors,
count(*) AS total,
round(errors / total * 100, 2) AS error_rate
FROM spans
WHERE start_time > now() - INTERVAL 1 DAY
GROUP BY name
HAVING total > 10
ORDER BY error_rate DESC
Exporting Results
Select results and click “Export to Dataset.” Map columns to dataset fields (data, target, metadata). Use this to build evaluation datasets from query results.
Full Reference
For complete ClickHouse SQL syntax, see the ClickHouse documentation.