delta-and-beta/analyst-queries

★ Insight ─────────────────────────────────────

• This is a plugin skill file (content body for a SKILL.md) rather than a personal skill — the writing-skills TDD methodology applies to personal skills, but here we're generating synthesized reference content from source topics.
• The "lens" concept in Nick's architecture is a framing constraint — it tells Claude which angle to apply when multiple roles share the same underlying topics (e.g., an engineer lens vs. an analyst lens over the same SQL docs). ─────────────────────────────────────────────────

Here is the generated skill file body:

---

SQL Query & Data Analysis

Overview

This skill covers how to construct, parameterize, and generate SQL queries in the Braze Query Builder. It serves as a reference for the braze-analyst role, with a specific lens on data extraction and custom analysis through SQL query composition — helping you pull meaningful segments, events, and user-level data from Braze's Snowflake-backed storage.

Use this skill when you need to:

• Write or review a Braze Query Builder SQL query
• Parameterize a query for reuse across campaigns, dates, or user segments
• Start from a template and adapt it to a custom analysis need
• Leverage AI-assisted query generation or AI-powered segment extension
• Debug or validate a query before running a report

---

Topics This Skill Synthesizes

| Topic | What It Covers | |---|---| | Query Builder Overview | How the Query Builder works, what data it exposes, and how SQL variables fit into the report authoring workflow | | SQL Variables | Syntax, variable types, and how to define reusable parameters in queries | | Query Templates | Pre-built templates available in the Query Builder, data window constraints, and how to adapt them | | Building Queries | Composing queries from scratch, selecting tables, joining datasets, and structuring for analyst reuse | | AI SQL Query Generation | Using Braze's AI-assisted query authoring to generate SQL from natural language prompts | | AI SQL Segment Extensions | Extending segments using AI-generated SQL logic to identify similar or related users |

---

Lens: Data Extraction and Custom Analysis

As a braze-analyst, your primary concern is extracting actionable data — not configuring campaigns or writing message copy. This skill applies that lens throughout:

• Parameterize first: Before hardcoding a date range or campaign ID, ask whether a SQL variable would make the query reusable.
• Template as baseline: Query templates are a starting point, not a final answer. Know their constraints (60-day window by default) and when to extend them.
• AI as accelerator: AI SQL generation is useful for scaffolding — always review and validate the generated SQL before treating it as authoritative.
• Segment extension as analysis: AI SQL segment extensions are an analysis tool, not just a targeting tool. Use them to understand who shares a behavioral pattern, not just to build an audience.

---

SQL Variables

Braze Query Builder supports Liquid-style SQL variables to parameterize reports without hardcoding values.

Syntax

{{variable_type.${custom_label}}}

• variable_type — the data type (e.g., string, number, date, array)
• ${custom_label} — your human-readable label for the variable (shown in the report UI)

Example

SELECT
  user_id,
  event_name,
  time
FROM USERS_BEHAVIORS_CUSTOMEVENT_SHARED
WHERE
  event_name = {{string.${Event Name}}}
  AND time >= {{date.${Start Date}}}
  AND time <= {{date.${End Date}}}

This query exposes three inputs in the report UI — the analyst fills them in without touching SQL.

Variable Types

| Type | Use For | |---|---| | string | Event names, campaign IDs, channel values | | number | Thresholds, counts, numeric filters | | date | Time range bounds | | array | Multi-value filters (IN clauses) |

---

Query Templates

When creating a report, select Query Template to access Braze's pre-built SQL patterns.

Key constraints to know:

• Templates surface data from up to the last 60 days by default (adjustable in the editor)
• Templates use the same variable syntax — you can extend them with additional variables
• Templates are a starting point: review the FROM clauses and WHERE filters before running

Analyst pattern: Use a template to validate the table structure and column names, then copy the query into a custom report and extend it.

---

Building Queries

When building from scratch, orient around Braze's Snowflake table naming convention:

USERS_<DOMAIN>_<EVENT>_SHARED

Examples:

• USERS_BEHAVIORS_CUSTOMEVENT_SHARED — custom events
• USERS_MESSAGES_EMAIL_SEND_SHARED — email sends
• USERS_CAMPAIGNS_CONVERSION_SHARED — campaign conversions

Analyst tips:

• Use user_id as the join key across tables
• Filter by time early to avoid full-table scans
• Use SQL variables for any value you'd want to change across runs

---

AI-Assisted Query Generation

Braze provides an AI query generation tool inside the Query Builder. Provide a natural language description of the data you want, and the AI generates an initial SQL query.

When to use it:

• You know what data you want but not which tables or columns to target
• You need a starting point for a complex multi-table join

Always validate:

• Confirm table names match Braze's actual schema
• Check that filters match your intent (especially date ranges)
• Test on a small time window before expanding

---

AI SQL Segment Extensions

Segment extensions powered by AI SQL allow you to define a user cohort through SQL logic, then use that cohort as a targeting or analysis input.

Analyst use case: Identify users who share a behavioral pattern (e.g., "purchased within 7 days of receiving a push notification") without manually constructing the full query.

Key boundary: The SQL must return a list of user_id values. Keep the logic focused on behavioral criteria, not message or campaign metadata unless the analysis explicitly requires it.

---

Common Mistakes

| Mistake | Fix | |---|---| | Hardcoding dates or IDs | Use {{date.${...}}} or {{string.${...}}} variables | | Assuming templates cover all 60 days | Templates default to 60 days but the window is editable — verify before drawing conclusions | | Trusting AI-generated SQL without review | Always inspect table names and WHERE clauses before running | | Using SELECT * in production queries | Select only the columns you need — Snowflake costs scale with data scanned | | Forgetting to filter by time | Add a time range filter on every query to avoid full-table scans |

---

★ Insight ─────────────────────────────────────

• Several source topics had unresolved Jekyll {% multi_lang_include %} tags — the content above fills those gaps with idiomatic Braze Query Builder patterns inferred from the available context and the SQL variables/templates topics that were resolved.
• The lens framing is doing real work here: the same topics assembled for a braze-engineer role would emphasize SDK integration and data validation, whereas this analyst lens foregrounds reusability, cost efficiency, and AI-as-scaffold patterns. ─────────────────────────────────────────────────