Skip to content
Telemetry
Telemetry SQL Cookbook

Learn SQL across one connected SaaS telemetry database

Follow an account from signup to activation, model usage, background work, billing, API failures, and database operations. Every lesson runs locally against the same synthetic tables, so joins, release comparisons, and business definitions stay visible.

Reviewed by the Telemetry product team on . Synthetic data contract, join grain, read-only SQL, expected results, and interpretation boundaries. Review standards and ownership

15

connected tables

10953

deterministic synthetic rows

18

guided SQL lessons

Dataset contract

Fifteen tables, explicit business join keys

The synthetic account_id connects commercial context to product, reliability, AI, job, and billing outcomes. More specific identifiers connect deployments and declared incidents while preserving the grain inside each workflow. No customer records, prompts, payloads, or credentials are included.

accounts6 rows

One synthetic SaaS account with the dimensions and recurring revenue needed for customer-impact analysis.

One row per account.

account_id
View 5 fields
account_id Utf8
Stable synthetic account identifier.
plan Utf8
Commercial plan at the end of the sample window.
region Utf8
Coarse hosting or customer region.
signup_at Timestamp
When the account entered the sample cohort.
monthly_revenue_usd Float64
Synthetic normalized monthly recurring revenue.
product_events21 rows

Durable account and user milestones for activation, adoption, and journey analysis.

One completed product milestone.

account_iduser_idsession_id
View 9 fields
timestamp_utc Timestamp
When the milestone completed.
event_id Utf8
Stable identifier for deduplication.
account_id Utf8
Joins the event to the synthetic account.
user_id Utf8
Synthetic actor identifier.
session_id Utf8
Groups ordered events within a visit.
event_name Utf8
Stable product milestone name.
feature Utf8
Product surface responsible for the event.
status Utf8
Final milestone outcome.
release Utf8
Application release that produced the event.
api_requests10 rows

Completed API request events with stable route, release, latency, and customer context.

One completed API request.

account_idrequest_id
View 7 fields
timestamp_utc Timestamp
When the request completed.
request_id Utf8
Stable request correlation identifier.
account_id Utf8
Joins the request to the synthetic account.
route_template Utf8
Bounded route shape without raw identifiers.
status_code Int64
Final HTTP response status.
latency_ms Float64
End-to-end request duration.
release Utf8
Application release serving the request.
llm_requests11 rows

Normalized provider usage, estimated cost, retry, and reviewed product-outcome fields.

One completed model request, including provider retries as separate rows.

account_idrequest_id
View 12 fields
timestamp_utc Timestamp
When the provider request completed.
request_id Utf8
Stable model request identifier.
account_id Utf8
Joins model usage to the synthetic account.
feature Utf8
Product workflow using the model.
provider Utf8
Normalized model provider.
model Utf8
Provider model identifier captured at request time.
input_tokens Int64
Provider-reported input-token count.
output_tokens Int64
Provider-reported output-token count.
estimated_cost_usd Float64
Estimated request cost under a versioned pricing rule.
status Utf8
Final provider request outcome.
retry_count Int64
Automatic provider retry count for this logical operation.
accepted Boolean
Whether the user accepted or saved the resulting output.
job_runs7 rows

Attempt-level background-job outcomes with queue and execution timing.

One attempt of a logical background job.

account_idjob_id
View 9 fields
timestamp_utc Timestamp
When the attempt reached a terminal outcome.
job_id Utf8
Logical job identifier shared by retries.
account_id Utf8
Joins job impact to the synthetic account.
job_name Utf8
Bounded worker operation name.
status Utf8
Attempt outcome.
attempt Int64
One-indexed attempt number.
queue_wait_ms Float64
Time waiting before execution.
duration_ms Float64
Worker execution time.
error_type Utf8
Controlled failure category or null on success.
billing_events5 rows

Synthetic subscription outcomes for connecting product behavior and reliability to commercial context.

One completed billing lifecycle event.

account_idevent_id
View 6 fields
timestamp_utc Timestamp
When the billing event completed.
event_id Utf8
Stable provider-event identifier.
account_id Utf8
Joins the event to the synthetic account.
event_name Utf8
Normalized billing lifecycle outcome.
amount_usd Float64
Synthetic normalized amount.
status Utf8
Final billing-event outcome.
users24 rows

Synthetic users for role, lifecycle, and adoption analysis without personal data.

One row per synthetic user.

user_idaccount_id
View 5 fields
user_id Utf8
Stable synthetic user identifier.
account_id Utf8
Account that owns the synthetic user.
role Utf8
Coarse product role used for segmentation.
created_at Timestamp
When the synthetic user joined the account.
is_admin Boolean
Whether the user can administer the account.
releases12 rows

A deployment dimension for comparing service behavior before and after releases.

One row per service release.

releaseservice
View 5 fields
release Utf8
Version emitted by service events.
service Utf8
Service receiving the deployment.
deployed_at Timestamp
UTC deployment time.
owner_team Utf8
Synthetic team responsible for the service.
change_type Utf8
Coarse release classification.
incidents2 rows

Declared incident windows for measuring affected accounts, error volume, and recovery.

One row per declared incident.

incident_idservice
View 6 fields
incident_id Utf8
Stable synthetic incident identifier.
service Utf8
Primary affected service.
started_at Timestamp
Start of the declared impact window.
resolved_at Timestamp
End of the declared impact window.
severity Utf8
Synthetic operational severity.
root_cause_category Utf8
Coarse, non-sensitive cause classification.
service_events10800 rows

A 30-day service-event fact table for realistic trend, percentile, release, and incident analysis.

One completed request or background job.

account_idreleaseserviceincident_id
View 11 fields
timestamp_utc Timestamp
UTC completion timestamp.
event_id Utf8
Stable event identifier for deduplication.
account_id Utf8
Synthetic customer account affected by the operation.
service Utf8
Service that completed the operation.
event_name Utf8
Stable event name at operation completion.
status Utf8
Final success or error outcome.
latency_ms Int64
End-to-end operation latency in milliseconds.
release Utf8
Service release active for the operation.
incident_id Utf8
Declared incident when the event is in an impact window.
region Utf8
Coarse synthetic account region.
error_type Utf8
Low-cardinality failure category, or null on success.
database_operations16 rows

Normalized database operations with query fingerprints, releases, latency, and SQLSTATE outcomes.

One completed database operation.

account_idservicerelease
View 12 fields
timestamp_utc Timestamp
Operation completion time in UTC.
operation_id Utf8
Stable operation identifier.
account_id Utf8
Account that initiated the operation.
service Utf8
Application service issuing the query.
database_name Utf8
Logical database name.
query_fingerprint Utf8
Normalized query family.
operation Utf8
SQL operation type.
status Utf8
Operation outcome.
duration_ms Int64
End-to-end duration in milliseconds.
rows_affected Int64
Rows returned or changed.
release Utf8
Application release.
sqlstate Utf8
SQLSTATE code when the operation failed.
database_pool_samples12 rows

Point-in-time connection-pool pressure, wait time, and acquisition timeouts.

One connection-pool sample.

servicedatabase_namerelease
View 11 fields
timestamp_utc Timestamp
Sample time in UTC.
service Utf8
Application service.
pool_name Utf8
Connection-pool name.
database_name Utf8
Target database.
active_connections Int64
Checked-out connections.
idle_connections Int64
Available idle connections.
max_connections Int64
Pool connection limit.
acquire_wait_ms Int64
Connection acquisition wait.
timed_out Boolean
Whether acquisition timed out.
region Utf8
Deployment region.
release Utf8
Application release.
database_lock_events6 rows

Resolved lock waits and deadlocks with blocked and blocking operation families.

One observed database lock wait.

servicedatabase_namerelease
View 11 fields
timestamp_utc Timestamp
Wait observation time in UTC.
database_name Utf8
Affected database.
service Utf8
Blocked application service.
blocked_operation Utf8
Blocked query family.
blocking_operation Utf8
Blocking query family.
lock_type Utf8
Database lock class.
wait_ms Int64
Observed lock wait.
resolved Boolean
Whether the wait resolved.
deadlock Boolean
Whether the wait became a deadlock.
transaction_id Utf8
Blocked transaction identifier.
release Utf8
Application release.
replication_samples12 rows

Replica and downstream consumer lag for operational databases, CDC, and search.

One replication-consumer sample.

consumer_namerelease
View 8 fields
timestamp_utc Timestamp
Sample time in UTC.
consumer_name Utf8
Replica or downstream consumer.
source_type Utf8
Replication mechanism.
region Utf8
Consumer region.
lag_seconds Int64
Observed replication lag.
backlog_bytes Int64
Unapplied backlog in bytes.
status Utf8
Consumer health classification.
release Utf8
Application release.
migration_runs9 rows

Application database migration executions, including failures and rollbacks.

One migration execution.

servicedatabase_namerelease
View 8 fields
timestamp_utc Timestamp
Migration completion time in UTC.
migration_id Utf8
Migration identifier.
service Utf8
Owning service.
database_name Utf8
Target database.
release Utf8
Application release.
status Utf8
Migration outcome.
duration_ms Int64
Migration duration.
error_type Utf8
Failure class, when present.

Reduce before joining

Collapse requests, attempts, or milestones to the business grain before adding account and revenue context.

Synthetic by construction

The dataset is deterministic, versioned, and large enough for trends and percentiles. It demonstrates logic rather than customer benchmarks.

Interpretation is part of the lesson

Every query names the denominator, business decisions, and claims the result cannot support.

SQL dialect compatibility

Prototype in DuckDB, ship with DataFusion-tested syntax

The browser lab uses DuckDB so the data never leaves the page. Telemetry production queries use Apache DataFusion. The lessons intentionally stay inside their shared SQL surface; when a function differs, use the production form below before saving a dashboard or alert.

Use caseBrowser labTelemetry / DataFusionGuidance
Time bucketsdate_trunc('day', timestamp_utc)date_trunc('day', timestamp_utc)Shared syntax; keep buckets in UTC.
Conditional countsSUM(CASE WHEN … THEN 1 ELSE 0 END)SUM(CASE WHEN … THEN 1 ELSE 0 END)Shared syntax and explicit denominator.
Approximate p95approx_quantile(latency_ms, 0.95)approx_percentile_cont(latency_ms, 0.95)Function name differs between engines.
Safe divisionvalue / NULLIF(total, 0)value / NULLIF(total, 0)Shared syntax; cast when integer division matters.
FoundationsBeginner

Summarize daily product activity

Which milestones are users completing on each day?

Start with one event table, group durable product milestones into UTC days, and keep successful volume separate from all attempts.

The dataset and query remain in this browser.

Published expected result

Daily successful product milestones

activity_dayeventssuccessful_eventsactive_accounts
2026-07-01221
2026-07-02442
2026-07-03322
2026-07-04441
2026-07-05332
2026-07-06221
2026-07-08111
2026-07-09111
2026-07-12111

How to read the query

  • The UTC day is derived from the event timestamp instead of a client-supplied date label.
  • Event volume and distinct active accounts answer different questions, so both remain visible.
  • The status condition prevents a failed integration attempt from being counted as a completed milestone.

Decisions the SQL cannot make

  1. 1Decide whether retries and repeated milestones should remain visible.
  2. 2Exclude internal, test, or bot accounts before treating this as adoption.
  3. 3Use complete time buckets when comparing recent days.

Continue from this lesson

Move from the lab to your own event contract

Keep the analysis grain and join logic, then replace the synthetic tables with your own stable event names and privacy-approved identifiers. Validate thresholds and commercial definitions with the team that owns them before promoting a query to a dashboard or alert.

Dataset use and provenance

Telemetry created this deterministic synthetic dataset for learning, testing, internal evaluation, and examples. You may copy and adapt the rows, schema, and lesson SQL for those purposes. Attribution is appreciated but not required. The dataset contains no customer records and is provided without a performance or business-outcome warranty.