BuilderIO/data-querying

Data Querying

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

Approach

1. Read the relevant provider skill first — check .builder/skills/<provider>/SKILL.md for table names, column mappings, auth, and gotchas
2. Use existing scripts — run pnpm action <name> --arg=value with --grep and --fields for filtering
3. Write ad-hoc scripts — if no existing script covers the question, create one in actions/
4. Present data in chat — don't just say "check the dashboard" — actually query, get the data, and present it

Built-in Filtering

All scripts that use output() support universal flags:

# Case-insensitive search across all values
pnpm action hubspot-deals --grep="enterprise"

# Pick specific fields from results
pnpm action hubspot-deals --fields=dealname,amount,stageLabel

# Combine both
pnpm action seo-top-keywords --grep=remix --fields=keyword,rank_absolute,etv

Generating Charts

Use the generate-chart script to create inline charts for chat responses. See .builder/skills/charts/SKILL.md for chart types, styling options, and examples.

Script Patterns

Reusing Existing Scripts

# GitHub PRs
pnpm action github-prs --org=YourOrg --query="is:open label:bug"

# Jira tickets
pnpm action jira-search --jql="summary ~ SSO" --fields=key,summary,status

# HubSpot deals
pnpm action hubspot-deals --fields=dealname,amount,stageLabel

# SEO keywords
pnpm action seo-top-keywords --grep=remix --fields=keyword,rank_absolute,etv

Writing Ad-Hoc Scripts

When no existing script covers the question:

1. Create a new script in actions/ that imports the relevant server lib
2. Run it via pnpm action <name>
3. For one-off queries, you can delete the script after
4. For reusable queries, keep the script

// scripts/my-query.ts
import { runQuery } from "../server/lib/bigquery.js";
import { output } from "./helpers.js";

export default async function main(args: string[]) {
  const results = await runQuery("SELECT ...");
  output(results);
}

Cross-Referencing Sources

For complete answers, combine data from multiple sources:

• BigQuery for analytics events, signups, pageviews
• HubSpot for CRM data — deals, contacts, revenue
• Jira for engineering metrics — tickets, sprints
• GitHub for code metrics — PRs, reviews
• Sentry for error rates and trends
• Grafana for infrastructure metrics

Important Notes

• Always query real data — never guess or approximate
• Use --grep and --fields to narrow output, don't pipe through grep
• Update the relevant .builder/skills/<provider>/SKILL.md when you discover new patterns
• For BigQuery queries, check .builder/skills/bigquery/SKILL.md for table schemas first