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):

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:

### 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.