# How to Use BigQuery ML Capabilities via the Google Skills Framework

> Easily use BigQuery ML capabilities with the google skills framework. Invoke AI functions like AI.FORECAST and AI.SEARCH without boilerplate code using the bigquery-ai-ml skill.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: how-to-guide
- Published: 2026-09-05

---

**The `bigquery-ai-ml` skill wraps BigQuery's native machine-learning and generative-AI functions so you can invoke AI operations like `AI.FORECAST` and `AI.SEARCH` through a standardized Skills API without writing boilerplate BigQuery client code.**

The `google/skills` repository provides a framework for exposing reusable capabilities through a unified API. By leveraging BigQuery ML capabilities via skills, you execute sophisticated ML workloads directly against your BigQuery datasets using simple HTTP requests, CLI commands, or Python clients, while the framework handles authentication, SQL generation, and result parsing.

## Architecture of the bigquery-ai-ml Skill

The skill acts as a thin abstraction layer between the Skills runtime and BigQuery's native AI functions. At its core, the skill definition in [`skills/cloud/bigquery-ai-ml/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/bigquery-ai-ml/SKILL.md) declares all supported functions and their schemas.

When you invoke the skill, the framework:

1. Receives the function name (e.g., `AI.KEY_DRIVERS`) and parameters via the Skills API
2. Generates a BigQuery SQL statement calling the requested AI function
3. Submits the query to BigQuery using your project's credentials
4. Returns the results as a structured JSON payload

Reference documentation for each function lives in the `skills/cloud/bigquery-ai-ml/references/` directory. For example, [`ai_forecast.md`](https://github.com/google/skills/blob/main/ai_forecast.md) details the `AI.FORECAST` syntax, while [`ai_search.md`](https://github.com/google/skills/blob/main/ai_search.md) covers semantic search parameters. These files map directly to BigQuery's native ML capabilities, ensuring you access the full power of functions like `AI.GENERATE`, `AI.DETECT_ANOMALIES`, and `AI.CLASSIFY` through a consistent interface.

## How to Invoke BigQuery ML Functions via Skills

You can trigger BigQuery ML operations through the Skills endpoint using the gcloud CLI, Python, or raw REST calls. All methods require a Google Cloud project with the Skills service enabled.

### Using the gcloud CLI

The gcloud CLI provides the simplest interface for ad-hoc operations. The command packages your function and parameters into a JSON payload, posts it to the Skills endpoint, and streams results back to your terminal.

```bash

# Run the forecasting function on a time-series table

gcloud skills run bigquery-ai-ml \
  --function=AI.FORECAST \
  --project=$PROJECT_ID \
  --params='{
     "table":"my_dataset.sales",
     "timestamp_column":"order_ts",
     "target_column":"revenue",
     "forecast_horizon":30
   }'

```

### Python Implementation with AuthorizedSession

For programmatic access, use `google.auth` to create an authorized session and POST to the Skills endpoint. This approach gives you full control over error handling and response parsing.

```python
import json
from google.auth import default
from google.auth.transport.requests import AuthorizedSession

# Authenticate and build an authorized session

creds, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
authed_session = AuthorizedSession(creds)

# Build the skill-run request

skill_url = (
    "https://skills.googleapis.com/v1/projects/{project}/skills/"
    "bigquery-ai-ml:run".format(project="my-project")
)

payload = {
    "function": "AI.KEY_DRIVERS",
    "params": {
        "model": "my_dataset.sales_forecast_model",
        "features": ["marketing_spend", "seasonality"],
        "target": "revenue"
    }
}

# Call the skill and parse the response

response = authed_session.post(skill_url, json=payload)
response.raise_for_status()
result = response.json()

print(json.dumps(result, indent=2))

```

The response contains a JSON object listing the top-ranking drivers and their contribution scores, extracted directly from BigQuery's ML evaluation.

### Raw REST API with cURL

For integration with shell scripts or non-Python environments, invoke the skill via standard HTTP POST requests.

```bash
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
        "function":"AI.SEARCH",
        "params":{
          "table":"my_dataset.documents",
          "query":"machine learning best practices",
          "top_k":5
        }
      }' \
  "https://skills.googleapis.com/v1/projects/my-project/skills/bigquery-ai-ml:run"

```

This returns the `top_k` most semantically relevant rows from your specified BigQuery table using BigQuery's vector search capabilities.

### High-Level Python Client

Some implementations provide a thin wrapper library that encapsulates the HTTP boilerplate. If available in your environment, this reduces the invocation to a single method call:

```python
from google.skills import SkillsClient

client = SkillsClient()
forecast = client.run(
    skill="bigquery-ai-ml",
    function="AI.FORECAST",
    params=dict(
        table="my_dataset.sales",
        timestamp_column="order_ts",
        target_column="revenue",
        forecast_horizon=30,
    ),
)
print(forecast["rows"])

```

## Supported BigQuery ML Functions

The `bigquery-ai-ml` skill exposes the full suite of BigQuery ML and generative AI functions through dedicated reference files:

- **`AI.FORECAST`** – Time-series forecasting capabilities documented in [`skills/cloud/bigquery-ai-ml/references/ai_forecast.md`](https://github.com/google/skills/blob/main/skills/cloud/bigquery-ai-ml/references/ai_forecast.md)
- **`AI.KEY_DRIVERS`** – Attribution analysis for model explainability, detailed in [`skills/cloud/bigquery-ai-ml/references/ai_key_drivers.md`](https://github.com/google/skills/blob/main/skills/cloud/bigquery-ai-ml/references/ai_key_drivers.md)
- **`AI.CLASSIFY`** – Text classification operations covered in [`skills/cloud/bigquery-ai-ml/references/ai_classify.md`](https://github.com/google/skills/blob/main/skills/cloud/bigquery-ai-ml/references/ai_classify.md)
- **`AI.SEARCH`** – Semantic and vector search functionality found in [`skills/cloud/bigquery-ai-ml/references/ai_search.md`](https://github.com/google/skills/blob/main/skills/cloud/bigquery-ai-ml/references/ai_search.md) and [`skills/cloud/bigquery-ai-ml/references/vector_search.md`](https://github.com/google/skills/blob/main/skills/cloud/bigquery-ai-ml/references/vector_search.md)
- **Remote Models** – Integration with Vertex AI custom models via [`skills/cloud/bigquery-ai-ml/references/remote_models.md`](https://github.com/google/skills/blob/main/skills/cloud/bigquery-ai-ml/references/remote_models.md)

Because the skill is a thin wrapper around BigQuery's sandboxed SQL environment, any client that can call the Skills API—including CLI, Python, REST, or interactive UIs—can leverage these ML capabilities without managing BigQuery client libraries directly.

## Summary

- The **bigquery-ai-ml** skill in the `google/skills` repository wraps BigQuery native ML functions into a reusable API
- **Skill definition** resides in [`skills/cloud/bigquery-ai-ml/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/bigquery-ai-ml/SKILL.md) with function-specific docs in the `references/` subdirectory
- **Invocation methods** include gcloud CLI, Python `AuthorizedSession`, raw REST, and high-level client libraries
- **Supported functions** cover forecasting (`AI.FORECAST`), classification (`AI.CLASSIFY`), semantic search (`AI.SEARCH`), and model interpretation (`AI.KEY_DRIVERS`)
- The framework handles SQL generation, authentication, and JSON serialization, returning structured results directly from BigQuery

## Frequently Asked Questions

### What is the bigquery-ai-ml skill?

The **bigquery-ai-ml** skill is a component in the `google/skills` repository that exposes BigQuery's machine-learning and generative-AI functions through a standardized Skills API. It allows any client capable of HTTP requests to invoke complex ML operations like `AI.FORECAST` or `AI.GENERATE` without importing BigQuery client libraries or writing SQL manually.

### How does authentication work when invoking skills?

Authentication follows standard Google Cloud OAuth 2.0 flows. When using the gcloud CLI, your active credentials are passed automatically. For Python or REST implementations, you must obtain a bearer token via `gcloud auth print-access-token` or use `google.auth.default()` with the `https://www.googleapis.com/auth/cloud-platform` scope to create an authorized session that the Skills service validates before executing BigQuery queries.

### Can I use custom Vertex AI models with this skill?

Yes. The skill supports BigQuery's remote model integration with Vertex AI, documented in [`skills/cloud/bigquery-ai-ml/references/remote_models.md`](https://github.com/google/skills/blob/main/skills/cloud/bigquery-ai-ml/references/remote_models.md). You can invoke custom models deployed on Vertex AI through BigQuery ML functions by referencing the remote model endpoint in your skill parameters, allowing you to combine custom model inference with BigQuery's native capabilities.

### Where are the reference docs for specific AI functions?

Each BigQuery ML function supported by the skill has dedicated documentation in the `skills/cloud/bigquery-ai-ml/references/` directory. Key files include [`ai_forecast.md`](https://github.com/google/skills/blob/main/ai_forecast.md) for time-series forecasting, [`ai_classify.md`](https://github.com/google/skills/blob/main/ai_classify.md) for text classification, [`ai_search.md`](https://github.com/google/skills/blob/main/ai_search.md) for semantic search, and [`vector_search.md`](https://github.com/google/skills/blob/main/vector_search.md) for vector similarity operations. These files define the exact parameter schemas and provide BigQuery-specific syntax examples.