Data QueryingCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: data-querying
description: >-
  General guidance on querying data sources, using existing scripts vs ad-hoc
  queries, filtering patterns, and generating charts for the analytics app.
---

# Data Querying

The analytics app connects to multiple data sources. This skill covers general patterns for querying data effectively.

## Approach

0. **Use retrieved references first** — data questions may start with a small set of relevant data-dictionary entries and saved dashboard panels in `<resource scope="analytics-catalog">`. Treat them as definitions and query examples, never live results. If they do not fit, call `find-data` before querying; use data-source status when provider availability matters.
1. **Route named account health deliberately** — for a customer/org health, QBR, renewal, contract-utilization, risk, or adoption request, read `account-health` before writing SQL. It adds identity-lock and metric-definition checks that an ordinary lookup does not need.
2. **Read the relevant provider skill first** — check `.agents/skills/<provider>/SKILL.md` for table names, column mappings, auth, and gotchas. For BigQuery, read `.agents/skills/bigquery/SKILL.md` and use `search-bigquery-schema` before guessing table or column names.
3. **Clarify if ambiguous** — if the metric definition, date range, or grain is unclear and a wrong guess would change the numbers, use the `ask-question` clarifying tool (multiple-choice) before querying. Ask at most once per turn; skip it when the dictionary or the user already answered.
4. **Use existing actions or connected provider MCP tools** — call the provider action/tool with structured arguments, then filter or aggregate the returned records in your answer
5. **Write ad-hoc scripts** — if no existing script covers the question, create one in `actions/`
6. **Present data in chat** — don't just say "check the dashboard" — actually query, get the data, and present it. Only present numbers you actually retrieved; never report a value you did not query.

For a question naming a dbt metric, call `query-dbt-semantic-metric` with its exact dbt name. Use dbt as the metric-definition and grain source; Sigma and Amplitude are examples or cross-checks. If the metric is not defined or its deployment is not ready, report that state and use a verified warehouse path only when it answers the same definition.

For events recorded by the analytics template itself via its `/track` endpoint, use `pnpm action query-agent-native-analytics --sql "SELECT ... FROM analytics_events ..."`. This includes pageviews, site/app traffic, template usage, app usage, and event counts collected by this analytics app. Pageviews and traffic can also live in GA4, BigQuery/warehouse tables, Mixpanel, PostHog, Amplitude, or another configured provider, so choose the source from the user's wording, connected-source status, existing dashboards, data dictionary, and user/org resources. Ask one concise clarification if multiple configured sources are plausible. Do not use `db-query` for data-source analysis; `db-query` is only for internal app tables and will confuse analytics questions. The shipped `agent-native-templates-first-party` SQL dashboard is the template engagement dashboard for the first-party collector source.

For first-party counts, active-user, and retention questions, prefer the compact
tenant-scoped daily event and user-day rollups. Use `analytics_events` only for a
bounded recent drill-down with an explicit date/time range. For the Builder.io
production organization after the BigQuery cutover, these logical tables are
served by partitioned BigQuery data and views; the source still does not require
an end user's separate warehouse connection.

First-party reads exclude test identities (QA/E2E accounts): ingest never
stores their events or replays, and the read scope filters `user_id` (events,
replays) and `user_key` (user-days). Pass `includeTestIdentities: true` to
`query-agent-native-analytics` only to debug those accounts. Daily event
rollups and BigQuery-source panels that query the raw warehouse table directly
are clean from ingest onward but are not filtered at read time. The one
exception is the legacy `@app_events` table, which keeps a test identity's
`$exception` rows marked `JSON_VALUE(data, '$.test_identity') = 'true'`;
exclude those from any metric over it.

Before a large or historical first-party query, call
`get-first-party-analytics-health`. Keep Neon as the default while its status is
`healthy` or `monitor`; a `recommend_bigquery` result means the app has observed
1M+ events, repeated slow queries, or a timeout/30-second query. Treat that
status as a compatibility name for an external-backend recommendation, not as
a requirement to use BigQuery. The health result lists the supported options:

- BigQuery for warehouse SQL and complete historical analysis.
- Amplitude for product analytics, funnels, and retention.

If a suitable backend is not configured, use its returned setup link or
`data-source-status --key <provider>` to guide the user through the existing
Data Sources walkthrough. Connecting a query backend alone does not move the
collector or copy existing Neon events. For the Builder.io production
organization, the hidden `migrate-first-party-analytics-to-bigquery` action is
the explicit state machine: prepare dual-write, backfill through bounded,
newest-first UTC time shards with per-shard leases, then cut over with
confirmation. The worker excludes `http.response` by default and uses
BigQuery `insertId` values for retry-safe writes. After cutover, `/track`
writes and event queries use BigQuery; public-key metadata, derived exception
issues, and session-replay data remain in SQL.

Example pageviews query for a local calendar day:

```sql
SELECT COUNT(*) AS pageviews
FROM analytics_events
WHERE event_name = 'pageview'
  AND timestamp >= '<start-utc>'
  AND timestamp < '<end-utc>'
```

Convert the user's requested local date/timezone to UTC before que

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (6)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

src: /chart?panel=eyJ0aXRsZSI6IkRhaWx5IHBhZ2V2aWV3cyIsInNxbCI6IlNFTEVDVCBkYXRlX3RydW5jKCdkYXknLCB0aW1lc3RhbXApIEFTIGRheSwgQ09VTlQoKikgQVMgcGFnZXZpZXdzIEZST00gYW5hbHl0aWNzX2V2ZW50cyBXSEVSRSBldmVudF9uYW

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Data Querying](https://modelsatlas.com/skills/builderio/data-querying/badge.svg)](https://modelsatlas.com/skills/builderio/data-querying/)

Not your listing, or something out of date? Claim or update your listing.