# Verb AI Query Cookbook

### Verb AI MCP Query Guide

#### How to Transform Business Questions into Effective Data Queries

### Overview

The Verb AI MCP provides access to real-time behavioral data from a compensated panel of 2,000+ US-based users (ages 21–34, skewing female). The data captures what people actually do on their devices — not what they say they do.

The key principle: The MCP answers objective, data-level questions well. It does not answer subjective or interpretive questions directly. Your job is to decompose business questions into structured queries the system can execute, then synthesize the results.

***

### Database Schema

Every event table links to AGENT\_SYNC via USER\_ID (or USER\_IDENTIFIER for network traffic).

#### 1. AGENT\_SYNC — User Demographics

The panel's demographic backbone. Join this to any event table to segment behaviors by audience.

| Column                            | Type     | Description                                              |
| --------------------------------- | -------- | -------------------------------------------------------- |
| USER\_ID                          | PK       | Unique user identifier. Links to all event tables.       |
| DATE\_OF\_BIRTH / YEAR\_OF\_BIRTH | Date/Int | Use for age segmentation. Panel is 21–34.                |
| GENDER                            | String   | Values: Female, Male, Non-binary, Prefer not to say      |
| HOUSEHOLD\_INCOME                 | Numeric  | Annual USD. Brackets: $1–50K, $50–100K, $100K+           |
| EDUCATION\_LEVEL                  | String   | Highest completed (High School → Master's+)              |
| EMPLOYMENT\_STATUS                | String   | Full-time, Part-time, Student, Unemployed, Self-employed |
| MARITAL\_STATUS                   | String   | Single, Married, etc.                                    |
| COUNTRY\_OF\_RESIDENCE            | String   | Currently 100% US                                        |
| FULL\_ADDRESS                     | String   | Street-level address. Use for state/city extraction.     |
| CITIZENSHIP / COUNTRY\_OF\_BIRTH  | String   | Origin demographics                                      |
| RACE                              | String   | Racial/ethnic background                                 |

Common patterns:

* Age calculation: `YEAR(CURRENT_DATE) - YEAR_OF_BIRTH`
* State extraction: Parse from FULL\_ADDRESS
* Income brackets: `GROUP BY` ranges of HOUSEHOLD\_INCOME

#### 2. PRODUCT\_EVENTS\_FLAT\_DYM — E-commerce Interactions

The richest table for purchase funnel analysis. Captures views, cart adds, and purchases across all e-commerce platforms.

| Column                   | Type      | Description                                                |
| ------------------------ | --------- | ---------------------------------------------------------- |
| USER\_ID                 | FK        | Links to AGENT\_SYNC                                       |
| ACTION                   | String    | Critical field. Values: viewed, added\_to\_cart, purchased |
| PRODUCT\_NAME            | String    | Full product name as displayed on retailer site            |
| BRAND                    | String    | Brand name (may be NULL — check PRODUCT\_NAME too)         |
| CATEGORY                 | String    | Product category from the retailer's taxonomy              |
| PRICE                    | Numeric   | Listed price at time of interaction                        |
| CURRENCY                 | String    | Usually USD                                                |
| DESCRIPTION              | String    | Full product description text. Use for keyword filtering.  |
| PRODUCT\_URL / PAGE\_URL | String    | Source URL. Extract retailer domain from this.             |
| PROMOTION                | String    | Any active promotion text (coupons, BOGO, rebates)         |
| RATINGS                  | Numeric   | Product star rating                                        |
| REVIEWS\_COUNT           | Numeric   | Number of reviews                                          |
| FEATURES                 | String    | Product feature list                                       |
| AVAILABILITY             | String    | In-stock status                                            |
| IMAGE\_URLS              | String    | Product images                                             |
| PRODUCT\_ID              | String    | Retailer's product identifier                              |
| EVENT\_TIME              | Timestamp | When the interaction happened                              |
| CREATE\_TIME             | Timestamp | When the record was created                                |

Critical notes:

* ACTION is the funnel stage indicator. Always filter or group by this.
* BRAND is often NULL. Search PRODUCT\_NAME and DESCRIPTION with ILIKE for brand detection.
* PAGE\_URL tells you which retailer (Amazon, Target, Instacart, DoorDash, etc.)
* PROMOTION captures deal text — useful for understanding price sensitivity.

#### 3. AMAZON\_SHOPPING\_FLAT\_DYM — Amazon Shopping Funnel

Parsed from Amazon proxy traffic. One row per shopping interaction on [www.amazon.com](http://www.amazon.com). Captures the full Amazon shopping funnel: search → product view → sponsored ads → cart → checkout → orders.

| Column               | Type      | Description                                                                  |
| -------------------- | --------- | ---------------------------------------------------------------------------- |
| USER\_ID             | FK        | Links to AGENT\_SYNC                                                         |
| EVENT\_TYPE          | String    | SEARCH, PRODUCT\_VIEW, SPONSORED\_AD, SPONSORED\_CLICK, FUNNEL, AUTOCOMPLETE |
| SEARCH\_KEYWORDS     | String    | What the user searched on Amazon (SEARCH events)                             |
| ASIN                 | String    | Amazon Standard Identification Number (product ID)                           |
| PRODUCT\_TITLE       | String    | Product name from the listing page                                           |
| PRODUCT\_BRAND       | String    | Brand name (from URL slug or title heuristic)                                |
| PRICE                | Numeric   | Listed price at time of interaction                                          |
| CURRENCY             | String    | Currency code (USD)                                                          |
| TOTAL\_RESULTS       | Numeric   | Number of search results returned (SEARCH events)                            |
| PAGE\_NUMBER         | Numeric   | Search results page number                                                   |
| FIRST\_RESULT\_ASIN  | String    | ASIN of the first organic search result                                      |
| FIRST\_RESULT\_PRICE | Numeric   | Price of the first organic search result                                     |
| MERCHANT\_NAME       | String    | Seller name (SPONSORED\_AD events)                                           |
| CAMPAIGN\_ID         | String    | Ad campaign identifier (SPONSORED\_AD events)                                |
| FUNNEL\_STEP         | String    | cart, checkout, your-orders, your-returns (FUNNEL events)                    |
| PAGE\_URL            | String    | Raw Amazon URL                                                               |
| EVENT\_TIME          | Timestamp | When the interaction happened                                                |

Critical notes:

* EVENT\_TYPE drives what fields are populated. SEARCH events have keywords/results, PRODUCT\_VIEW has title/ASIN/price, SPONSORED\_AD has merchant/campaign.
* SPONSORED\_AD and SPONSORED\_CLICK capture Amazon's advertising ecosystem — which ads are shown and which are clicked.
* FUNNEL events (cart, checkout, your-orders) are behavioral signals without item-level detail.
* AUTOCOMPLETE captures search suggestions typed by the user.
* Prices are in USD. FIRST\_RESULT\_PRICE is from the first organic search result.

#### 4. SHOPIFY\_SHOPPING\_FLAT\_DYM — Shopify E-commerce Events

Parsed from proxy traffic across 400+ Shopify-powered stores. Auto-detects Shopify stores via standardized URL patterns. Captures product views with structured price/brand/currency data, cart contents, checkout, and search.

| Column             | Type      | Description                                                                                                                                           |
| ------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| USER\_ID           | FK        | Links to AGENT\_SYNC                                                                                                                                  |
| EVENT\_TYPE        | String    | PRODUCT\_VIEW, PRODUCT\_PAGE\_VIEW, COLLECTION\_BROWSE, CART\_VIEW, ADD\_TO\_CART, CART\_STATE, CART\_CHANGE, CART\_UPDATE, CHECKOUT, SEARCH, PAYMENT |
| STORE\_DOMAIN      | String    | The Shopify store domain (e.g., "nathanandsons.com", "[www.popflexactive.com](http://www.popflexactive.com)")                                         |
| PRODUCT\_HANDLE    | String    | Shopify product slug (e.g., "remineralizing-gum")                                                                                                     |
| PRODUCT\_TITLE     | String    | Full product name from Shopify JSON API                                                                                                               |
| PRODUCT\_VENDOR    | String    | Brand/vendor name (e.g., "POPFLEX®", "Amish Country Popcorn")                                                                                         |
| PRODUCT\_TYPE      | String    | Product category from Shopify                                                                                                                         |
| PRICE              | Numeric   | Price in the store's currency                                                                                                                         |
| COMPARE\_AT\_PRICE | Numeric   | Original price before discount (if on sale)                                                                                                           |
| CURRENCY           | String    | Currency code (USD, NZD, NOK, JPY, etc.)                                                                                                              |
| SKU                | String    | Product SKU                                                                                                                                           |
| VARIANT\_TITLE     | String    | Selected variant (e.g., "Mastic Mint / 2 Packs", "XXS")                                                                                               |
| PRODUCT\_ID        | String    | Shopify numeric product ID                                                                                                                            |
| TAGS               | String    | Product tags from Shopify                                                                                                                             |
| SEARCH\_QUERY      | String    | What the user searched for (SEARCH events)                                                                                                            |
| COLLECTION\_HANDLE | String    | Collection/category browsed (COLLECTION\_BROWSE events)                                                                                               |
| PAGE\_URL          | String    | Raw URL                                                                                                                                               |
| EVENT\_TIME        | Timestamp | When the interaction happened                                                                                                                         |

Critical notes:

* PRODUCT\_VIEW (from `/products/HANDLE.json`) is the richest event type — 100% title, 99% vendor, 86% price, 95% SKU, 36% compare\_at\_price populated.
* CART\_VIEW (from `/cart.json`) gives total cart price (in cents, divided by 100) and currency. Many carts show price=0 (empty carts).
* STORE\_DOMAIN identifies which of 400+ stores the event occurred on. Major stores include Alo Yoga, Skims, Sanrio, New Era, Dolls Kill, Princess Polly, Tarte Cosmetics, and hundreds of DTC brands.
* Multi-currency: USD, NZD, NOK, JPY all detected.
* COMPARE\_AT\_PRICE > PRICE indicates a product is on sale — useful for discount analysis.

#### 5. DELIVERY\_APPS\_FLAT\_DYM — Food Delivery Events (DoorDash + Uber Eats)

Unified food delivery behavioral events from DoorDash and Uber Eats. Covers the full ordering funnel: store browsing → item view → cart → order → rating. Prices are in USD (converted from cents).

| Column                    | Type      | Description                                                                                                                                                 |
| ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| USER\_ID                  | FK        | Links to AGENT\_SYNC                                                                                                                                        |
| PLATFORM                  | String    | DOORDASH or UBEREATS                                                                                                                                        |
| EVENT\_TYPE               | String    | STORE\_VIEW, CART\_VIEW, ADD\_TO\_CART, ORDER\_PLACED, ITEM\_VIEW, ORDER\_RATING, ORDER\_HISTORY, ACTIVE\_ORDER, DRAFT\_ORDER, INVOICE, PAGE\_VIEW, PAYMENT |
| STORE\_NAME               | String    | Restaurant/store name (e.g., "7-Eleven", "DashMart", "The Juicy Crab")                                                                                      |
| STORE\_ID                 | String    | Platform-specific store identifier                                                                                                                          |
| STORE\_RATING             | Numeric   | Average store rating (0–5 scale)                                                                                                                            |
| NUM\_RATINGS              | Numeric   | Total number of ratings for the store                                                                                                                       |
| DELIVERY\_FEE             | Numeric   | Delivery fee in USD                                                                                                                                         |
| IS\_SUBSCRIPTION\_PARTNER | Boolean   | Whether store is DashPass/Uber One partner                                                                                                                  |
| DISTANCE\_MI              | Numeric   | Distance from consumer in miles                                                                                                                             |
| STORE\_ADDRESS            | String    | Full store address                                                                                                                                          |
| STORE\_LAT / STORE\_LNG   | Numeric   | Store geolocation coordinates                                                                                                                               |
| ITEM\_NAME                | String    | Menu item name (e.g., "Classic - Mixed Plate", "Chocolate Filled") or item ID                                                                               |
| ITEM\_PRICE               | Numeric   | Item price in USD                                                                                                                                           |
| QUANTITY                  | Numeric   | Number of items                                                                                                                                             |
| ORDER\_TOTAL              | Numeric   | Total order amount in USD                                                                                                                                   |
| TIP\_AMOUNT               | Numeric   | Tip amount in USD                                                                                                                                           |
| ORDER\_UUID               | String    | Unique order identifier                                                                                                                                     |
| ORDER\_STATUS             | String    | PLACED, COMPLETED, CANCELLED, ACTIVE, DRAFT                                                                                                                 |
| PAYMENT\_METHOD           | String    | Payment method brand (e.g., "Visa")                                                                                                                         |
| CURRENCY                  | String    | Currency code (USD)                                                                                                                                         |
| PAGE\_URL                 | String    | Raw request URL                                                                                                                                             |
| EVENT\_TIME               | Timestamp | When the interaction happened                                                                                                                               |

Critical notes:

* DoorDash STORE\_VIEW is the richest event — store name, rating, delivery fee, address, lat/lng, DashPass status, distance from consumer.
* DoorDash ORDER\_PLACED has order total, tip amount, payment method, and order UUID. Prices are in cents divided by 100.
* Uber Eats ORDER\_HISTORY has item-level detail: item name, price, quantity, customizations, and order status (COMPLETED/CANCELLED).
* DoorDash ITEM\_VIEW shows numeric item IDs from the URL (item names not available because the app caches item details locally).
* DoorDash CART\_VIEW gives store name, subtotal, and number of items in cart.
* Use PLATFORM to filter by DoorDash vs Uber Eats, or combine for cross-platform delivery analysis.

#### 6. SEARCH\_EVENTS\_FLAT\_DYM — Search Activity

Captures every search query across Google, Bing, YouTube, and other engines. The best table for understanding intent and discovery.

| Column               | Type      | Description                                         |
| -------------------- | --------- | --------------------------------------------------- |
| USER\_ID             | FK        | Links to AGENT\_SYNC                                |
| QUERY                | String    | The actual search terms typed. Most valuable field. |
| SEARCH\_ENGINE       | String    | google, bing, youtube, other                        |
| RESULTS\_COUNT       | Numeric   | Number of results returned                          |
| RESULTS\_DESCRIPTION | String    | Summary of top results                              |
| PAGE\_URL            | String    | Search results page URL                             |
| LANGUAGE             | String    | Interface language                                  |
| EVENT\_TYPE          | String    | Search event classification                         |
| EVENT\_TIME          | Timestamp | When the search happened                            |

Critical notes:

* QUERY is case-sensitive in some contexts — always use ILIKE for matching.
* For topic analysis, use keyword patterns: `QUERY ILIKE '%white claw%'` or `QUERY ILIKE '%ramen%'`
* Combine with time windows to see search-to-action sequences.

#### 7. YOUTUBE\_EVENTS\_FLAT\_DYM — YouTube Interactions

Captures video views, including full metadata about what panelists watch.

| Column                                         | Type      | Description                                  |
| ---------------------------------------------- | --------- | -------------------------------------------- |
| USER\_ID                                       | FK        | Links to AGENT\_SYNC                         |
| SNIPPET\_TITLE / API\_TITLE                    | String    | Video title. Use for content categorization. |
| CHANNEL\_TITLE / CHANNEL\_ID                   | String    | Creator/channel info                         |
| DESCRIPTION\_SNIPPET / DESCRIPTION\_TOP\_LEVEL | String    | Video description text                       |
| VIEW\_COUNT                                    | Numeric   | Total video views (public metric)            |
| LIKE\_COUNT                                    | Numeric   | Total likes on the video                     |
| COMMENT\_COUNT                                 | Numeric   | Total comments                               |
| TAGS                                           | String    | Video keyword tags                           |
| CATEGORY\_ID                                   | String    | YouTube category                             |
| DURATION\_ISO8601                              | String    | Video length (ISO format, e.g., PT10M30S)    |
| VIDEO\_ID / API\_VIDEO\_ID                     | String    | YouTube video identifier                     |
| PAGE\_URL                                      | String    | Full YouTube URL                             |
| GEO\_CITY / GEO\_COUNTRY\_NAME / GEO\_REGION   | String    | Viewer location                              |
| PUBLISHED\_AT                                  | Timestamp | When the video was published                 |
| EVENT\_TIME                                    | Timestamp | When the panelist watched it                 |

Critical notes:

* VIEW\_COUNT and LIKE\_COUNT are the video's total public metrics, not the panelist's personal view count. Use COUNT of events per user for panelist engagement.
* For creator tier analysis, use VIEW\_COUNT as a proxy for creator size.
* TAGS and DESCRIPTION\_SNIPPET are valuable for content topic classification.

#### 8. REDDIT\_POSTS\_FLAT\_DYM — Reddit Post & Comment Viewing

Parsed from Reddit GraphQL API traffic. Captures posts and comments that panelists viewed, including full post metadata, subreddit context, and engagement metrics.

| Column                 | Type      | Description                                                                                                               |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- |
| USER\_ID               | FK        | Links to AGENT\_SYNC                                                                                                      |
| OPERATION\_TYPE        | String    | GraphQL operation: SubredditFeedElements, PostDetailQuery, CommentsListingQuery, CommunityAboutQuery, ProfileOverviewFeed |
| SUBREDDIT\_NAME        | String    | Subreddit (e.g., "AskReddit", "nba", "SkincareAddiction")                                                                 |
| POST\_TITLE            | String    | Full post title text                                                                                                      |
| POST\_ID               | String    | Reddit post identifier                                                                                                    |
| AUTHOR\_NAME           | String    | Post/comment author username                                                                                              |
| SCORE                  | Numeric   | Upvotes minus downvotes                                                                                                   |
| COMMENT\_COUNT         | Numeric   | Number of comments on the post                                                                                            |
| SUBREDDIT\_SUBSCRIBERS | Numeric   | Subreddit subscriber count at time of viewing                                                                             |
| FLAIR\_TEXT            | String    | Post flair (topic/category tag)                                                                                           |
| IS\_NSFW               | Boolean   | Whether the post is marked NSFW                                                                                           |
| CREATED\_UTC           | Timestamp | When the post was originally created                                                                                      |
| PAGE\_URL              | String    | Reddit URL                                                                                                                |
| EVENT\_TIME            | Timestamp | When the panelist viewed it                                                                                               |

Critical notes:

* OPERATION\_TYPE tells you what the user was doing: browsing a subreddit feed, reading a post's comments, viewing a community about page, or browsing a user profile.
* SUBREDDIT\_NAME is the key interest-mapping field. Group by it to understand what communities panelists engage with.
* SCORE and COMMENT\_COUNT are the post's public engagement metrics, not the panelist's interaction.
* Use SUBREDDIT\_SUBSCRIBERS to understand community size context.

#### 9. REDDIT\_ACTIONS\_FLAT\_DYM — Reddit User Actions

Parsed from Reddit GraphQL API traffic. Captures active user behaviors: voting, saving, joining communities, hiding posts, and managing subscriptions.

| Column          | Type      | Description                                                                                                           |
| --------------- | --------- | --------------------------------------------------------------------------------------------------------------------- |
| USER\_ID        | FK        | Links to AGENT\_SYNC                                                                                                  |
| OPERATION\_TYPE | String    | GraphQL operation: Vote, Save, JoinSubreddit, UpdateNotificationPreferences, HidePost, MarkAllNotificationsRead, etc. |
| ACTION\_DETAILS | String    | Specifics of the action (e.g., vote direction, subreddit joined)                                                      |
| POST\_ID        | String    | Target post identifier (for votes, saves, hides)                                                                      |
| SUBREDDIT\_NAME | String    | Target subreddit (for joins, subscriptions)                                                                           |
| PAGE\_URL       | String    | Reddit URL                                                                                                            |
| EVENT\_TIME     | Timestamp | When the action happened                                                                                              |

Critical notes:

* This captures *active* engagement, not passive viewing. Votes, saves, and community joins are high-signal indicators of genuine interest.
* Combine with REDDIT\_POSTS\_FLAT\_DYM to understand the view-to-action conversion: how many posts viewed vs. voted on vs. saved.
* JoinSubreddit actions indicate strong community affinity.

#### 10. NETWORK\_TRAFFIC\_EVENTS\_DYM — Network Traffic

Raw domain-level traffic. Shows which apps and websites panelists access.

| Column           | Type   | Description                                                 |
| ---------------- | ------ | ----------------------------------------------------------- |
| USER\_IDENTIFIER | FK     | Links to AGENT\_SYNC.USER\_ID (note: different column name) |
| SNI              | String | Server Name Indication — the domain being accessed          |

Critical notes:

* This is the most granular but least structured table. It shows raw domain hits.
* Use SNI with ILIKE to detect app/platform usage: `SNI ILIKE '%instagram%'`, `SNI ILIKE '%tiktok%'`
* Best for: understanding which platforms users are on before/after other events, mapping media exposure pathways.
* High volume table — always filter by time and user segments.

#### 11. NEWS\_EVENTS\_FLAT\_DYM — News Interactions

Captures news article consumption and engagement.

| Column                          | Type      | Description                |
| ------------------------------- | --------- | -------------------------- |
| USER\_ID                        | FK        | Links to AGENT\_SYNC       |
| ARTICLE\_URL / PAGE\_URL        | String    | Article URL                |
| NEWS\_OUTLET                    | String    | Publishing organization    |
| AUTHOR                          | String    | Article author             |
| CONTENT\_SUMMARY                | String    | Article summary text       |
| KEYWORDS                        | String    | Topic keywords             |
| NEWS\_TYPE                      | String    | Content category           |
| COMMENTS\_COUNT / LIKES         | Numeric   | Engagement metrics         |
| LANGUAGE                        | String    | Content language           |
| GEO\_\*                         | Various   | Geographic location fields |
| PUBLICATION\_DATE / EVENT\_TIME | Timestamp | When published / when read |

#### 12. DONATIONS\_EVENTS\_DYM — Donation Events

Tracks donation-related activity on digital platforms.

| Column                              | Type      | Description                  |
| ----------------------------------- | --------- | ---------------------------- |
| USER\_ID                            | FK        | Links to AGENT\_SYNC         |
| EVENT\_KEY                          | String    | Unique donation identifier   |
| EVENT\_TYPE                         | String    | Type of engagement           |
| PLATFORM                            | String    | Platform (tiktok, instagram) |
| DATA                                | JSON      | Raw event details            |
| DONATION\_EVENT\_TIME / EVENT\_TIME | Timestamp | Timestamps                   |

#### 13. BETTING\_EVENTS\_FLAT\_DYM — Betting Activity

Captures sports betting and gambling platform interactions.

| Column                            | Type      | Description                |
| --------------------------------- | --------- | -------------------------- |
| USER\_ID                          | FK        | Links to AGENT\_SYNC       |
| ACTION                            | String    | User action type           |
| BET\_TYPE                         | String    | Type of bet                |
| PLATFORM                          | String    | Betting platform           |
| EVENT\_NAME / EVENT\_CATEGORY     | String    | Event details              |
| PARTICIPANTS                      | String    | Event participants         |
| SELECTION                         | String    | Selected outcome           |
| ODDS                              | Numeric   | Betting odds               |
| STAKE\_AMOUNT / POTENTIAL\_PAYOUT | Numeric   | Financial amounts          |
| IS\_LIVE\_EVENT                   | Boolean   | Live event indicator       |
| MARKET\_CATEGORY                  | String    | Market classification      |
| GEO\_\*                           | Various   | Geographic location fields |
| EVENT\_DATE / EVENT\_TIME         | Timestamp | Timestamps                 |

***

### Query Translation Patterns

The core skill is translating business questions into multi-step, objective queries. Below are common patterns.

#### Pattern 1: "What's popular?" → Aggregate Event Counts

**Business question:** "What are the most popular RTD brands?"

**Wrong approach:** Asking the MCP "what's popular" directly.

**Right approach — multi-step:**

1. **Identify keywords first:** Ask: "What distinct values of BRAND or PRODUCT\_NAME in PRODUCT\_EVENTS\_FLAT\_DYM contain keywords like 'seltzer', 'cocktail', 'hard', 'white claw', 'truly', 'high noon'?"
2. **Aggregate:** "Count distinct USER\_IDs and total events grouped by BRAND for products matching those keywords, ordered by count descending."
3. **Segment by action:** "Break this down by ACTION (viewed, added\_to\_cart, purchased) to see funnel performance."

#### Pattern 2: "What's the average price?" → Multi-Step Keyword + Aggregation

**Business question:** "What's the average price of RTD drinks?"

**Wrong approach:** Asking for "average RTD price" directly — the MCP has no RTD category tag.

**Right approach — multi-step:**

1. **Define the universe:** "Find all distinct products in PRODUCT\_EVENTS\_FLAT\_DYM where PRODUCT\_NAME or DESCRIPTION ILIKE any of: '%hard seltzer%', '%canned cocktail%', '%RTD%', '%ready to drink%', '%white claw%', '%truly%', '%high noon%', '%cutwater%'"
2. **Extract prices:** "For those products, what are the distinct PRODUCT\_NAME and PRICE combinations?"
3. **Calculate:** "What is the average, median, min, and max PRICE across those products?"

#### Pattern 3: "Where do people discover X?" → Channel/Platform Analysis

**Business question:** "Which channels drive RTD discovery?"

**Right approach:**

1. **Search behavior:** "In SEARCH\_EVENTS\_FLAT\_DYM, how many users searched queries containing RTD brand names? Group by SEARCH\_ENGINE."
2. **Content exposure:** "In YOUTUBE\_EVENTS\_FLAT\_DYM, how many users watched videos with RTD-related keywords in SNIPPET\_TITLE or TAGS?"
3. **Network traffic:** "In NETWORK\_TRAFFIC\_EVENTS\_DYM, which SNI domains (instacart, doordash, target, amazon, etc.) are most visited by users who also have RTD product events?"
4. **Product source:** "In PRODUCT\_EVENTS\_FLAT\_DYM, extract the domain from PAGE\_URL for RTD products. Group by domain to see which retailers."

#### Pattern 4: "Does X lead to Y?" → Temporal Sequence Analysis

**Business question:** "Does watching creator content lead to purchases?"

**Right approach — event sequencing:**

1. **Define exposure group:** "Find USER\_IDs in YOUTUBE\_EVENTS\_FLAT\_DYM who watched videos with beverage/RTD keywords in the title between \[date range]."
2. **Define action group:** "Find USER\_IDs in PRODUCT\_EVENTS\_FLAT\_DYM who had ACTION = 'purchased' for beverage products in the same or subsequent time window."
3. **Compare:** "What % of the exposure group also appears in the action group? What % of users NOT in the exposure group appear in the action group?"
4. **Time sequence:** "For users in both groups, what was the time gap between YouTube event and purchase event?"

#### Pattern 5: "Who is our audience?" → Demographic Segmentation

**Business question:** "Who are the people engaging with Japanese content?"

**Right approach:**

1. **Define the behavior:** "Find USER\_IDs from SEARCH\_EVENTS where QUERY ILIKE any of '%japan%', '%anime%', '%ramen%', '%sushi%', '%sake%', '%matcha%'"
2. **Also check YouTube:** "Add USER\_IDs from YOUTUBE\_EVENTS where SNIPPET\_TITLE or TAGS contain those same keywords."
3. **Join to demographics:** "For those USER\_IDs, pull GENDER, YEAR\_OF\_BIRTH, HOUSEHOLD\_INCOME, EDUCATION\_LEVEL, EMPLOYMENT\_STATUS, FULL\_ADDRESS from AGENT\_SYNC."
4. **Aggregate:** "What's the distribution of each demographic field?"

#### Pattern 6: "What content performs best?" → Engagement Metrics

**Business question:** "Which types of creator content drive the most engagement?"

**Right approach:**

1. **Categorize content:** "In YOUTUBE\_EVENTS\_FLAT\_DYM, classify videos by keywords in SNIPPET\_TITLE: 'tasting', 'tutorial', 'review', 'challenge', 'reaction', 'reveal'"
2. **Per-category metrics:** "For each category, count: distinct users, total events, average VIEW\_COUNT, average LIKE\_COUNT, average COMMENT\_COUNT"
3. **Engagement rate:** "Calculate engagement per participant (total events / distinct users) for each category"
4. **Cross-reference downstream:** "For users who watched each content type, how many also appear in PRODUCT\_EVENTS with beverage-related actions?"

#### Pattern 7: "Is there a trend?" → Time-Series Analysis

**Business question:** "Is awareness for brand X growing week over week?"

**Right approach:**

1. **Define the signal:** "Count events per week in SEARCH\_EVENTS where QUERY ILIKE '%brand\_name%'"
2. **Add YouTube:** "Count events per week in YOUTUBE\_EVENTS where SNIPPET\_TITLE or DESCRIPTION ILIKE '%brand\_name%'"
3. **Add product interactions:** "Count events per week in PRODUCT\_EVENTS where PRODUCT\_NAME or BRAND ILIKE '%brand\_name%'"
4. **Compare periods:** "Show week-over-week change for each signal."

**Important caveat:** Watch for false positives. Brand names like "Toki" or "Hibiki" may match unrelated content (anime characters, rappers). Always validate by checking the actual content context.

#### Pattern 8: "What are people buying on Amazon?" → Amazon Shopping Funnel

**Business question:** "What products are trending on Amazon in our category?"

**Right approach:**

1. **Search intent:** "In AMAZON\_SHOPPING\_FLAT\_DYM, what are the top SEARCH\_KEYWORDS by count where EVENT\_TYPE = 'SEARCH'?"
2. **Product discovery:** "For PRODUCT\_VIEW events, what are the most viewed PRODUCT\_TITLE values? What are the average PRICE values by brand?"
3. **Ad exposure:** "For SPONSORED\_AD events, which MERCHANT\_NAME values appear most? What CAMPAIGN\_IDs are active?"
4. **Funnel conversion:** "How many users have SEARCH events who also have FUNNEL events with FUNNEL\_STEP = 'cart' or 'checkout'?"
5. **Cross-reference:** "Join to AGENT\_SYNC to segment Amazon shoppers by demographics."

#### Pattern 9: "What DTC brands are people buying?" → Shopify Cross-Store Analysis

**Business question:** "Which Shopify DTC brands have the highest engagement?"

**Right approach:**

1. **Store popularity:** "In SHOPIFY\_SHOPPING\_FLAT\_DYM, count events grouped by STORE\_DOMAIN, ordered by total events descending."
2. **Product-level detail:** "For PRODUCT\_VIEW events, show STORE\_DOMAIN, PRODUCT\_TITLE, PRODUCT\_VENDOR, PRICE, and COMPARE\_AT\_PRICE. Group by vendor to find top brands."
3. **Discount analysis:** "Find products where COMPARE\_AT\_PRICE > PRICE — these are on sale. What % of product views are discounted?"
4. **Full funnel:** "Count events by EVENT\_TYPE (PRODUCT\_VIEW → ADD\_TO\_CART → CHECKOUT → PAYMENT) per store to see conversion signals."
5. **Search behavior:** "What SEARCH\_QUERY values appear in SEARCH events? These show what people look for within Shopify stores."

#### Pattern 10: "What are people ordering for delivery?" → Food Delivery Analysis

**Business question:** "What restaurants and food items are most popular on delivery apps?"

**Right approach:**

1. **Restaurant popularity:** "In DELIVERY\_APPS\_FLAT\_DYM, for STORE\_VIEW events on DOORDASH, what are the top STORE\_NAME values by count? What are their average STORE\_RATING and DELIVERY\_FEE?"
2. **Order details:** "For ORDER\_PLACED events on DOORDASH, what are the average ORDER\_TOTAL and TIP\_AMOUNT? Group by PAYMENT\_METHOD."
3. **Item-level data:** "For ORDER\_HISTORY events on UBEREATS, what ITEM\_NAME values appear most frequently? What is the average ITEM\_PRICE?"
4. **Cross-platform:** "Compare DOORDASH vs UBEREATS by total events, distinct users, and average order totals."
5. **Geography:** "For DOORDASH STORE\_VIEW events, use STORE\_LAT/STORE\_LNG and STORE\_ADDRESS for geographic analysis of which areas have the most delivery activity."
6. **DashPass analysis:** "What % of STORE\_VIEW events have IS\_SUBSCRIPTION\_PARTNER = TRUE? Do DashPass stores have higher engagement?"

#### Pattern 11: "What's happening on Reddit?" → Reddit Community Analysis

**Business question:** "What topics are trending in our category on Reddit?"

**Right approach:**

1. **Subreddit mapping:** "In REDDIT\_POSTS\_FLAT\_DYM, count events grouped by SUBREDDIT\_NAME, ordered by count descending. This shows which communities panelists are browsing."
2. **Content analysis:** "For specific subreddits, what POST\_TITLE values appear? Use ILIKE to filter titles by category keywords."
3. **Engagement signals:** "In REDDIT\_ACTIONS\_FLAT\_DYM, count actions grouped by OPERATION\_TYPE (Vote, Save, JoinSubreddit) to see what drives active engagement."
4. **View-to-action conversion:** "Compare users who viewed posts (REDDIT\_POSTS) vs. users who voted/saved (REDDIT\_ACTIONS) to measure engagement depth."
5. **Community growth:** "Track JoinSubreddit actions over time to see which communities are gaining panelist members."

***

### Common Pitfalls

**❌ Asking interpretive questions directly**

* Bad: "Why do consumers prefer White Claw?"
* Good: "How many distinct users have events for White Claw products broken down by ACTION type? What QUERY terms do users search before or after White Claw product events?"

**❌ Assuming category labels exist**

* Bad: "Show me all RTD beverage data"
* Good: "Show me products where PRODUCT\_NAME or DESCRIPTION contains keywords: \[list of RTD brands and category terms]"

**❌ Confusing video-level metrics with user-level metrics**

* Bad: "How many views did RTD content get?" (this gives you public YouTube view counts)
* Good: "How many distinct panelists watched videos with RTD-related titles?" (this gives you panel reach)

**❌ Forgetting to validate keyword matches**

* Bad: "How many people searched for 'Yamazaki'?" (could be the whisky OR a Japanese actor)
* Good: "How many people searched for 'Yamazaki'? Show me the top 10 QUERY values to verify context."

**❌ Single-step queries for complex questions**

* Bad: "What's the conversion rate from creator content to purchase?"
* Good: Break into 3 steps: define exposure group → define conversion group → calculate overlap percentage.

**❌ Confusing platform-specific pricing formats**

* Bad: Assuming all prices are in dollars
* Good: DoorDash and Uber Eats store prices in cents (already converted to dollars in the table). Shopify CART\_VIEW prices are in cents (divided by 100 in the table). Amazon prices are in dollars. Always check the table documentation.

***

### Quick Reference: Question → Table Mapping

| Question                         | Table                         | Key Columns                                               |
| -------------------------------- | ----------------------------- | --------------------------------------------------------- |
| What people search for           | SEARCH\_EVENTS\_FLAT\_DYM     | QUERY, SEARCH\_ENGINE                                     |
| What people buy / view / cart    | PRODUCT\_EVENTS\_FLAT\_DYM    | ACTION, PRODUCT\_NAME, BRAND, PRICE, PAGE\_URL            |
| What people search on Amazon     | AMAZON\_SHOPPING\_FLAT\_DYM   | SEARCH\_KEYWORDS, EVENT\_TYPE, ASIN                       |
| What people buy on Amazon        | AMAZON\_SHOPPING\_FLAT\_DYM   | PRODUCT\_TITLE, PRICE, ASIN, FUNNEL\_STEP                 |
| What Amazon ads are shown        | AMAZON\_SHOPPING\_FLAT\_DYM   | MERCHANT\_NAME, CAMPAIGN\_ID, EVENT\_TYPE='SPONSORED\_AD' |
| What DTC brands people shop      | SHOPIFY\_SHOPPING\_FLAT\_DYM  | STORE\_DOMAIN, PRODUCT\_TITLE, PRODUCT\_VENDOR, PRICE     |
| What Shopify stores people visit | SHOPIFY\_SHOPPING\_FLAT\_DYM  | STORE\_DOMAIN, EVENT\_TYPE, COLLECTION\_HANDLE            |
| What products are on sale        | SHOPIFY\_SHOPPING\_FLAT\_DYM  | PRICE, COMPARE\_AT\_PRICE, PRODUCT\_VENDOR                |
| What restaurants people browse   | DELIVERY\_APPS\_FLAT\_DYM     | STORE\_NAME, STORE\_RATING, PLATFORM='DOORDASH'           |
| What food people order           | DELIVERY\_APPS\_FLAT\_DYM     | ITEM\_NAME, ITEM\_PRICE, ORDER\_TOTAL, PLATFORM           |
| DoorDash vs Uber Eats usage      | DELIVERY\_APPS\_FLAT\_DYM     | PLATFORM, EVENT\_TYPE, ORDER\_TOTAL                       |
| Delivery tipping behavior        | DELIVERY\_APPS\_FLAT\_DYM     | TIP\_AMOUNT, ORDER\_TOTAL, PAYMENT\_METHOD                |
| What videos people watch         | YOUTUBE\_EVENTS\_FLAT\_DYM    | SNIPPET\_TITLE, CHANNEL\_TITLE, VIEW\_COUNT               |
| What apps/sites people use       | NETWORK\_TRAFFIC\_EVENTS\_DYM | SNI                                                       |
| What news people read            | NEWS\_EVENTS\_FLAT\_DYM       | KEYWORDS, NEWS\_OUTLET, CONTENT\_SUMMARY                  |
| What subreddits people browse    | REDDIT\_POSTS\_FLAT\_DYM      | SUBREDDIT\_NAME, POST\_TITLE, SCORE                       |
| What Reddit actions people take  | REDDIT\_ACTIONS\_FLAT\_DYM    | OPERATION\_TYPE, ACTION\_DETAILS, SUBREDDIT\_NAME         |
| Who the users are                | AGENT\_SYNC                   | GENDER, YEAR\_OF\_BIRTH, HOUSEHOLD\_INCOME, FULL\_ADDRESS |
| Donation behavior                | DONATIONS\_EVENTS\_DYM        | PLATFORM, EVENT\_TYPE                                     |
| Betting behavior                 | BETTING\_EVENTS\_FLAT\_DYM    | PLATFORM, BET\_TYPE, EVENT\_NAME                          |

***

### Multi-Table Query Templates

#### Template A: Content Exposure → Purchase Funnel

Find users exposed to content → check if they purchased → compare to unexposed users.

#### Template B: Platform Usage Before Purchase

Use NETWORK\_TRAFFIC to see what platforms users visited before product interactions.

#### Template C: Category Interest Sizing

Combine SEARCH, YOUTUBE, PRODUCT, and REDDIT tables to size total interest in a category.

#### Template D: Price Point Analysis

Use AMAZON\_SHOPPING (PRICE), SHOPIFY\_SHOPPING (PRICE, COMPARE\_AT\_PRICE), and PRODUCT\_EVENTS (PRICE) for cross-platform price comparison.

#### Template E: Cross-Platform Shopping Journey

Trace users from SEARCH\_EVENTS (discovery) → AMAZON\_SHOPPING or SHOPIFY\_SHOPPING (product browsing) → DELIVERY\_APPS (food ordering) to understand daily commerce patterns.

#### Template F: Restaurant & Food Discovery

Combine SEARCH\_EVENTS (food-related queries) → YOUTUBE\_EVENTS (food content) → DELIVERY\_APPS\_FLAT\_DYM (actual orders) to measure content-to-order conversion.

#### Template G: Reddit-to-Purchase Pipeline

Track REDDIT\_POSTS (community browsing) → REDDIT\_ACTIONS (upvotes/saves on product recommendations) → PRODUCT\_EVENTS or SHOPIFY\_SHOPPING (actual purchases) to measure Reddit's influence on buying decisions.

***

### Tips for Power Users

* Always start by identifying which table(s) contain the signal you need, using the Quick Reference table above.
* For brand analysis, search across multiple tables: PRODUCT\_EVENTS (purchases), SEARCH\_EVENTS (intent), YOUTUBE\_EVENTS (content), AMAZON\_SHOPPING (Amazon-specific), SHOPIFY\_SHOPPING (DTC), and REDDIT\_POSTS (community discussion).
* Use AGENT\_SYNC joins to segment any behavior by demographics.
* For time-series analysis, use DATE\_TRUNC('week', EVENT\_TIME) to aggregate events into weekly bins.
* For funnel analysis across platforms, use USER\_ID to trace the same person across tables.
* For Shopify discount analysis, compare PRICE vs COMPARE\_AT\_PRICE — when compare\_at is higher, the product is on sale.
* For delivery app analysis, DoorDash has the richest store-level data (ratings, fees, addresses, geolocation) while Uber Eats has the richest item-level data (individual menu items with prices from order history).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.generationlab.org/getting-started/editor.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.