How to Use BigQuery ML Capabilities via the Google Skills Framework

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 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 details the AI.FORECAST syntax, while 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.

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

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.

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:

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
• AI.KEY_DRIVERS – Attribution analysis for model explainability, detailed in 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
• AI.SEARCH – Semantic and vector search functionality found in skills/cloud/bigquery-ai-ml/references/ai_search.md and 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

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 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. 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 for time-series forecasting, ai_classify.md for text classification, ai_search.md for semantic search, and vector_search.md for vector similarity operations. These files define the exact parameter schemas and provide BigQuery-specific syntax examples.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}