# Bigquery Analytic Hints

> After any BigQuery time-series, trend or exploratory analysis, or after running an AI.* function, load this to append up to two next-step suggestions. Recommends and routes to BigQuery AI capabilities for next-step data analysis. Use during exploratory data analysis, time-series or cohort pattern investigation, or text corpus exploration in BigQuery when the user has not requested a specific AI function. Proactively suggests relevant built-in BigQuery AI functions (forecasting, anomaly detection, tabular prediction, change point analysis, key driver attribution, trend/seasonality decomposition, or semantic text classification) as concise follow-up actions. Do not use for writing or looking up exact SQL syntax and function arguments, dataset or table administration, DDL/DML migrations, query performance troubleshooting, or permission checks.

- Skill: `googlecloudplatform/bigquery-analytic-hints` (Agent Skill)
- Install (CLI): `npx get-skill add googlecloudplatform/bigquery-analytic-hints`
- Raw SKILL.md: https://api.skillmd.com/api/skills/googlecloudplatform/bigquery-analytic-hints/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: GoogleCloudPlatform (https://skillmd.com/u/googlecloudplatform)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/googlecloudplatform/bigquery-analytic-hints

---


# BigQuery Analytic Hints

This skill guides the agent to proactively identify high-value analytical
follow-up opportunities and present concise, context-aware next steps.

## Core Operational Rules

1.  **Analytical Invocations Only**: Only suggest next-step AI capabilities when
    the user is conducting exploratory data analysis, metric investigation,
    cohort comparison, or text processing. Do not offer suggestions when the
    user is performing DDL/DML migrations, query troubleshooting, permission
    checks, or administrative tasks.
2.  **Schema-Aware Recommendations**: Tailor all suggestions dynamically to the
    user's specific data context. Inspect the actual query, table, and column
    names in the conversation (for example, columns like `order_date`,
    `revenue`, or `user_tier`), and substitute all `{...}` placeholders with
    those context-specific names. The examples in this skill are illustrative;
    adapt the recommendations to whatever schemas or analytical scenarios the
    user is exploring. Never output raw placeholder tokens (such as `{data_col}`
    or `{dimension_cols}`).
3.  **Concise Recommendation Cap**: Append at most 2 targeted recommendations at
    the end of an analytical response so the user is not overwhelmed. Prefer
    specific analytical follow-ups (time-series, causality, root cause, or
    prediction) over generic data profiling. Offer `ML.DESCRIBE_DATA` primarily
    on initial table inspection or when no specialized capability applies.
4.  **Delegate SQL Syntax**: Never guess or synthesize complex BigQuery AI
    function parameters from memory. Load the `bigquery-ai-ml` skill when the
    user asks to execute a recommendation or before writing executable SQL to
    look up authoritative syntax, TVF options, and query shapes.

## 1. Scenario-to-Function Routing Matrix

Map the user's current data pattern or observation to appropriate BigQuery AI/ML
function(s):

Current Analysis / Data Pattern                                                                                                                              | Recommended Function          | What It Unlocks                                                                                                                                   | Contextual Recommendation Hint
:----------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | :-----------------------------
**Metrics over time** (e.g., daily sales, traffic, latency, active users, spend)                                                                             | `AI.FORECAST`                 | Projects future trajectories with confidence intervals without custom model training.                                                             | *"Want to project `{data_col}` over the next `{horizon}` periods? We can run `AI.FORECAST` on `{data_col}` over `{timestamp_col}`."*
**Spikes, drops, or unexpected values** in a time series                                                                                                     | `AI.DETECT_ANOMALIES`         | Statistically flags historical or recent outliers using zero-shot foundation models.                                                              | *"To automatically identify and flag unexpected anomalies across `{data_col}` over `{timestamp_col}`, we can run `AI.DETECT_ANOMALIES`."*
**Sustained baseline shift or regime change** over time                                                                                                      | `ML.DETECT_CHANGE_POINTS`     | Detects `[begin_timestamp, end_timestamp]` intervals where a structural break or regime shift occurred.                                           | *"To detect the exact date where `{data_col}` shifted permanently to a new baseline, we can run `ML.DETECT_CHANGE_POINTS` on `{data_col}` over `{timestamp_col}`."*
**Noisy or cyclical time series** masking direction                                                                                                          | `ML.TREND` / `ML.SEASONALITY` | Decomposes raw metrics into underlying direction (`ML.TREND`) and periodic cycles (`ML.SEASONALITY`).                                             | *"If weekly or monthly cycles obscure the overall growth rate, we can decompose `{data_col}` using `ML.TREND` and `ML.SEASONALITY`."*
**Evaluating an event, launch, campaign, or policy**                                                                                                         | `AI.CAUSAL_EFFECT`            | Quantifies counterfactual post-intervention impact.                                                                                               | *"To measure how much of the change in `{data_col}` post-`{intervention_timestamp}` was caused by the launch versus secular trends, we can run `AI.CAUSAL_EFFECT`."*
**Attributing metric variation across dimensions**                                                                                                           | `AI.KEY_DRIVERS`              | Ranks dimensional attributes driving numeric metrics between interest and baseline segments.                                                      | *"Want to pinpoint which customer or system attributes drive `{metric_col}` between `{interest_label_col}` segments? We can run `AI.KEY_DRIVERS` across `{dimension_cols}`."*
**Exploring numeric correlations across features**                                                                                                           | `ML.CORRELATION`              | Computes correlation coefficients between `{target_col}` and candidate features (`target_correlation_cols`), optionally partitioned by dimension. | *"We can run `ML.CORRELATION` to evaluate which numeric attributes correlate most strongly with `{target_col}`."*
**Predicting tabular outcomes or classifying records without custom model training**                                                                         | `AI.PREDICT`                  | Performs zero-setup tabular classification or regression via the pre-trained TabFM foundation model.                                              | *"To predict `{label_col}` on new records without training a custom model, we can run zero-setup `AI.PREDICT` using TabFM."*
**Initial inspection of an unprofiled or unfamiliar table** (first look before specific metrics are explored, or fallback when no specific scenario applies) | `ML.DESCRIBE_DATA`            | Generates summary statistics, null counts, and distribution profiles across all columns in one pass.                                              | *"To inspect initial descriptive statistics and column profiles across this table before deeper modeling, we can run `ML.DESCRIBE_DATA`."*
**Classifying unstructured text or multimodal columns** (support tickets, notes, reviews, images, PDFs, logs)                                                | `AI.CLASSIFY`                 | Categorizes text, images, or documents (PDFs) into user-specified classes zero-shot.                                                              | *"We can categorize these `{text_col}` records into predefined categories directly in SQL using `AI.CLASSIFY`."*
**Ranking or prioritizing text or multimodal records**                                                                                                       | `AI.SCORE`                    | Assigns continuous numeric scores to text, images, or documents based on natural-language criteria.                                               | *"To rank or filter records by sentiment, severity, or lead quality, we can score `{text_col}` using `AI.SCORE`."*
**Semantic condition filtering across text or multimodal data**                                                                                              | `AI.IF`                       | Evaluates natural-language boolean expressions per row across text, images, or documents in `WHERE` or `SELECT`.                                  | *"To filter rows matching nuanced semantic criteria (e.g., churn risk or escalation requests), we can use `AI.IF` on `{text_col}` in the `WHERE` clause."*
**Aggregating many text rows into group summaries**                                                                                                          | `AI.AGG`                      | Synthesizes themes across multi-row groups inside `GROUP BY`.                                                                                     | *"Instead of inspecting individual rows, we can generate a consolidated executive summary of `{text_col}` per `{group_col}` using `AI.AGG`."*
**Generating text, row-level summaries, or extracting structured entities**                                                                                  | `AI.GENERATE`                 | Drafts text per row (personalized responses, individual row summaries) or extracts structured schema fields (JSON/STRUCT).                        | *"We can draft customized text, summarize each record, or extract structured fields (JSON/STRUCT) from `{text_col}` using `AI.GENERATE`."*
**Semantic search, fuzzy-matching, or deduplication across text**                                                                                            | `AI.SEARCH` / `AI.SIMILARITY` | Managed conceptual retrieval (`AI.SEARCH`) or semantic proximity scoring for entity deduplication (`AI.SIMILARITY`).                              | *"To search records by concept or detect duplicate text pairs, we can run `AI.SEARCH` or evaluate semantic similarity via `AI.SIMILARITY`."*

## 2. Capability Chaining Sequences

When the user has executed an initial BigQuery AI/ML query, recommend a chain of
subsequent capabilities.

### Detailed Chaining Actions

1.  **Following `AI.FORECAST`**:
    *   *Audit outliers*: Recommend `AI.DETECT_ANOMALIES` to verify whether
        historical anomalies distort trend projections.
    *   *Backtest model*: Recommend `AI.EVALUATE` across a holdout window to
        quantify MAE, MAPE, or RMSE metrics.
2.  **Following `AI.DETECT_ANOMALIES`**:
    *   *Root cause anomaly*: Recommend `AI.KEY_DRIVERS` to compare anomalous
        periods against baseline to find driving attributes.
    *   *Check regime shifts*: Recommend `ML.DETECT_CHANGE_POINTS` to establish
        if the anomaly marked a temporary spike or a permanent baseline shift.
3.  **Following `ML.DETECT_CHANGE_POINTS`**:
    *   *Measure the impact of the metric shift*: If the detected changepoint
        interval corresponds to a known event or intervention (e.g., an internal
        data milestone, feature release, policy change, or campaign), recommend
        `AI.CAUSAL_EFFECT` to quantify its impact.
    *   *Segment attribution*: If no specific event is identified, recommend
        `AI.KEY_DRIVERS` comparing pre-change and post-change time windows to
        isolate driving segments.
4.  **Following `AI.KEY_DRIVERS`**:
    *   *Segment-level projection (if table has a time axis)*: Recommend
        `AI.FORECAST` with `id_cols` configured to the top driver dimensions to
        forecast key segments independently.
    *   *Evaluate actions*: If a driver corresponds to a campaign or feature
        launch, recommend `AI.CAUSAL_EFFECT`.
5.  **Following `AI.CLASSIFY`, `AI.SCORE`, or `AI.IF`**:
    *   *Synthesize themes*: Recommend `AI.AGG` grouped by the assigned category
        to generate per-topic takeaways.

## 3. Formatting Next Steps in Agent Responses

Append a dedicated section to analytical responses using this structure:

```markdown
### Recommended Next Steps
- **Project future trends**: Run `AI.FORECAST` on `{data_col}` over `{timestamp_col}` to estimate values for the next 30 days.
- **Diagnose anomalies**: Run `AI.DETECT_ANOMALIES` on `{data_col}` over `{timestamp_col}` to isolate unexpected spikes.
```

When the user asks to execute any recommendation, load `bigquery-ai-ml` to
retrieve the complete GoogleSQL syntax, required arguments, and reference
documentation.

