Tinybird

@voltro/plugin-tinybird is the hosted-ClickHouse AnalyticsSink — it ingests via Tinybird's Events API and reads via Pipes (saved SQL endpoints), so you get ClickHouse-grade OLAP on a pay-as-you-go service instead of operating a cluster yourself. It's for teams that ALREADY have a Tinybird workspace; if you want a zero-setup external OLAP sink that owns its own schema, use @voltro/plugin-clickhouse instead. For the shared AnalyticsSink API and the useAnalytics() read methods, see Analytics & warehouse sinks.

#Install

pnpm add @voltro/plugin-tinybird

#Wiring

// app.config.ts
import { tinybirdAnalytics } from '@voltro/plugin-tinybird'

export default {
  type:      'api' as const,
  name:      'myApi',
  store:     'postgres' as const,
  analytics: tinybirdAnalytics({
    token:      process.env.TINYBIRD_TOKEN!,
    region:     'eu',                 // 'eu' | 'us-east' | 'us-west' | 'asia-southeast'
    datasource: 'voltro_events',
  }),
}

track() POSTs events to the Datasource via the Events API; aggregate / timeseries / topN call your Pipes. There's no boot-time initialize — the Datasource is auto-created on the first event, and the Pipes must already exist. The trade-off is deferred failure: a bad token or missing Pipe boots clean and surfaces as a typed AnalyticsError on the first call.

#Required Pipes

The plugin EXPECTS three canonical Pipes to exist in your workspace (create them once via the tb CLI or the UI). It does NOT synthesize them — Tinybird's .pipe DSL is too rich to generate from a generic spec:

• events_aggregate — params: event, from, to, metric_expr, filter_sql
• events_timeseries — same + bucket_fn
• events_topn — same + group_expr, limit

#Options

tinybirdAnalytics(options):

Option	Type	Default	Notes
token	string	— (required)	Tinybird workspace token.
region	string	'eu'	'eu' / 'us-east' / 'us-west' / 'asia-southeast'. Selects the API base URL.
apiUrl	string	derived from region	Custom API base URL — overrides region (self-hosted Tinybird or preview envs).
datasource	string	'voltro_events'	The plugin POSTs events to /v0/events?name=<datasource>.
pipes	{ aggregate?, timeseries?, topN? }	the three canonical names	Override Pipe names if your team uses a different convention.

datasource + the Pipe names are validated as identifiers at boot (they're interpolated into request URLs), so a path-traversal name fails loudly rather than building a bad URL.

Connection details come from options, not env. The plugin reads no TINYBIRD_* variables itself — the example wires process.env into the options. Use @voltro/env's defineEnv to declare the token as a secret.

#Provider escape hatch

For direct Pipe access beyond the cross-provider contract, import the Tinybird Tag and yield* it for the configured client. Using the Tag binds your handler to Tinybird — stay on useAnalytics() for provider-portable code.

#See also

• Analytics & warehouse sinks — the shared AnalyticsSink contract, the useAnalytics() read API, and composeAnalytics.