Bigquery Observability
GoogleOfficialPublished by Google
- Skill
- Tool integration
- Data and AI
- Apache-2.0
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
BigQuery Observability offers a structured approach to monitoring and analyzing BigQuery performance and resource usage. It guides users in selecting the right telemetry tools—ranging from INFORMATION_SCHEMA for historical analysis to the REST API for real-time job lookups—and provides optimized SQL templates for auditing compute, storage, and capacity. The skill emphasizes efficient data retrieval, least-privilege access, and performance guardrails to ensure accurate telemetry without unnecessary overhead.
What it does
- Provides SQL query templates for INFORMATION_SCHEMA views.
- Offers guidance on choosing between INFORMATION_SCHEMA, Cloud Monitoring, and REST APIs.
- Includes best practices for performant telemetry retrieval and cost management.
- Details schema dictionaries for compute, storage, and capacity metrics.
- Defines workflows for diagnosing job bottlenecks and resource contention.
- Enforces usage attribution for all Google Cloud CLI and API interactions.
When to use it
- When you need to audit billable compute or storage resource usage.
- When investigating job performance bottlenecks or slot contention.
- When analyzing reservation capacity, utilization, or autoscaling saturation.
- When you need to perform historical analysis or cohort comparisons of jobs.
- When selecting the appropriate telemetry tool for real-time vs. historical monitoring.
Advantages
- Reduces query overhead by providing optimized, partition-filtered SQL patterns.
- Ensures least-privilege access by recommending specific view variants.
- Standardizes diagnostic workflows across single-job and system-level issues.
- Provides clear guidance on avoiding common pitfalls like full metadata scans.
Usage examples
- “How do I check for slot contention in my BigQuery project?”
- The agent provides a query template using the JOBS_TIMELINE view, filtered by the relevant time window, to identify periods of high slot usage and queue latency.
- “I need to audit my on-demand compute spend for the last 30 days.”
- The agent provides a structured SQL query using INFORMATION_SCHEMA.JOBS, including logic to deduplicate script wrappers and calculate billable bytes.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/google/bigquery-observability/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip bigquery-observability.zip -d .agents/skills
Documentation by Google
BigQuery Observability
Attribution
MUST READ: Before executing any gcloud, REST API, or MCP command, you
MUST read Usage Attribution. For commands executed
directly in the terminal (never in generated scripts, Terraform, or user code),
prefix gcloud with
CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:bigquery-observability)"
and append agent-skills/1.0 (skill:bigquery-observability) to User-Agent headers.
Tool Selection
<!-- mdformat off -->
| Tool | Primary Use Cases | Strengths & Capabilities | When to Avoid / Limitations |
|---|---|---|---|
INFORMATION_SCHEMA (I_S) | Historical analysis, cohort comparison (normalized_literals), discovery of fast/slow windows, reservation/project timelines, multi-job aggregates, cost/billing tracing. | Flexible SQL querying across JOBS, JOBS_TIMELINE, and RESERVATIONS; supports custom time windows and grouping. | Avoid for high-frequency real-time polling or single-job point-lookups (can consume slots and take seconds to execute). |
REST API (jobs.api / reservation.api) | Single-job point-lookup, real-time stage bottleneck diagnosis, automated pipeline status checks, reservation/capacity commitment configuration inspection (reservations.get, reservations.list). | Zero-SQL overhead, fast REST/CLI point-lookups (bq show -j, bq show --reservation), instant access to performanceInsights, queryPlan, and structural metadata. | Avoid for aggregate analysis across thousands of jobs, cross-project historical comparison, or system timeline aggregations. |
Cloud Monitoring (Metrics Explorer / Charts) | Real-time alerting, fleet-wide dashboards, continuous slot utilization tracking, high-level SLA/SLO monitoring. | Out-of-the-box charts for slot utilization, query throughput, PENDING queue depth, and execution latency; low-latency alerting without running queries. | Avoid for SQL-level debugging, individual query text inspection, or stage-level execution detail. |
<!-- mdformat on -->
Prerequisites & Environment Setup
Before retrieving telemetry or running observability queries, ensure the Google Cloud environment and project are configured:
Google Cloud SDK: Ensure the Google Cloud SDK is installed and configured.
Project Selection: Set the active Google Cloud project:
gcloud config set project {project_id}API Enablement: Ensure the BigQuery and Cloud Monitoring APIs are enabled:
gcloud services enable bigquery.googleapis.com monitoring.googleapis.comAuthentication: Authenticate the environment:
CLI queries and
bqcommands:gcloud auth loginSDKs and automated client tools:
gcloud auth application-default loginService accounts: Set
GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
Billing & IAM Roles:
Verify an active Google Cloud Billing account is attached to
{project_id}.Ensure appropriate IAM roles:
roles/bigquery.jobUser: Running telemetry queries.roles/bigquery.resourceViewerorroles/bigquery.admin: Organization-level jobs and reservation telemetry.roles/monitoring.viewer: Cloud Monitoring metrics.
Companion Skills Installation: This skill is part of a 3-pillar operations suite (
bigquery-observability,bigquery-optimization,bigquery-troubleshooting). If any companion skill is not yet installed in your environment, install the full suite:npx skills add google/skills --skill bigquery-observability --skill bigquery-optimization --skill bigquery-troubleshooting
Workflow
Single-Job Point-Lookup (Zero-SQL Overhead): For single-job slowness or inspection, always prioritize the REST API or CLI (
bq show -j) first. It provides zero-SQL overhead and fast point-lookups for internal stage bottlenecks (performanceInsights,queryPlan, shuffle spill).bq show --location={location} -j {project_id}:{job_id}Diagnostic Transition Logic: If no job-level issues are found (e.g. no clear internal bottlenecks), the investigation should transition to system-level
INFORMATION_SCHEMAqueries (such asJOBS_TIMELINEorRESERVATIONS_TIMELINE) to check for broader issues like slot contention, queueing delay, or noisy neighbors.
Best Practices for Writing INFORMATION_SCHEMA Queries
Every query against a BigQuery INFORMATION_SCHEMA view must be qualified with
either a region qualifier or a dataset qualifier, optionally prefixed by
a project qualifier.
Qualification Syntax & Scope Matching
Region-Qualified Syntax:
`{project_id}`.`region-{region}`.INFORMATION_SCHEMA.{view}Example:
`my-project`.`region-us`.INFORMATION_SCHEMA.JOBSApplies to: Regional telemetry views (
JOBS*,JOBS_TIMELINE*,RESERVATIONS*,CAPACITY_COMMITMENTS*,TABLE_STORAGE*,STREAMING_TIMELINE*). The client query execution location MUST match theregion-{region}qualifier (or BigQuery throws:Not found: Table {project_id}:region-{region}.INFORMATION_SCHEMA.{view} was not found in location {location}).Dataset-Qualified Syntax:
`{project_id}`.`{dataset_id}`.INFORMATION_SCHEMA.{view}Example:
`my-project`.`analytics`.INFORMATION_SCHEMA.TABLESApplies to: Dataset-scoped views (
PARTITIONS,SEARCH_INDEXES*,ROW_ACCESS_POLICIES). Never useregion-with dataset views.Dual-Scoped Views: Views like
TABLES,COLUMNS,COLUMN_FIELD_PATHS,VIEWS,ROUTINES, andVECTOR_INDEXEScan be qualified with either{dataset_id}orregion-{region}depending on whether dataset or region-wide analysis is required.Project Qualifier (
{project_id}): Optional. If omitted, queries default to the project in which the query is executing. Specifying a project qualifier on organization-level views (e.g.JOBS_BY_ORGANIZATION) has no impact on results.
Principle of Least Privilege & Scope Selection
When constructing INFORMATION_SCHEMA queries, always select the scope and
view variant with the least IAM permission requirement that satisfies the
analytical need:
User-Level over Project-Level (
_BY_USER): When diagnosing queries or sessions executed by the current user, use_BY_USER(e.g.JOBS_BY_USER,SESSIONS_BY_USER). This requires onlybigquery.jobs.list(granted viaroles/bigquery.userorroles/bigquery.jobUser), avoiding the need forbigquery.jobs.listAllorroles/bigquery.admin.Dataset-Level over Region/Project-Level: When querying table metadata, columns, or views for a specific dataset, qualify with
{dataset_id}rather thanregion-{region}when project-level metadata access is restricted. Dataset-scoped queries require permissions only on that target dataset.Project-Level over Org/Folder-Level (
_BY_PROJECT): Always start with project-scoped views before escalating to_BY_FOLDERor_BY_ORGANIZATION. Folder and organization queries require broad folder/org IAM permissions (bigquery.jobs.listAllorbigquery.tables.listat the Org/Folder node).Metadata Roles over Data Roles: For table and storage introspection, prefer
roles/bigquery.metadataViewer(which providesbigquery.tables.getandbigquery.tables.list) overroles/bigquery.dataViewerorroles/bigquery.dataOwnerwhen data read access (bigquery.tables.getData) is not needed. (Note:INFORMATION_SCHEMA.PARTITIONSuniquely requiresbigquery.tables.getData).
Execution Guardrails & Query Invariants
Mandatory Partition & Time Filtering: Always filter on
creation_time(e.g.,creation_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 3 DAY)) orusage_dateto avoid full metadata table scans.Script Wrapper Exclusion: Add
AND (statement_type != 'SCRIPT' OR statement_type IS NULL)when aggregating compute spend to avoid double-counting parent scripts and child jobs.Column Pruning: Never use
SELECT *againstINFORMATION_SCHEMA; only project required columns.Dry Run & Cost Estimation: Use a dry run (
bq query --dry_run --use_legacy_sql=false "{query}"or APIdryRun=true) before executing complex queries, multi-view joins, or large scans to validate syntax and estimatetotalBytesProcessedat zero cost.Empty Regional Scope (0 Rows): If the execution location matches the qualifier, but the project has no datasets or jobs in that region, the query succeeds and returns 0 rows. Never assume 0 rows means 0 usage—always verify the target dataset locations.
Non-Hierarchical Region Scope: Region qualifiers are not hierarchical. Multi-regions do not encompass single regions (e.g.
region-usreturns only multi-regionUSmetadata and does not include single regions likeregion-us-central1).No Multi-Region Aggregation in SQL: Region qualifiers cannot be joined cross-region in a single query (e.g.
region-uscannot joinregion-eu).Uncached Execution & Minimum Scan Size:
INFORMATION_SCHEMAquery results are never cached. On-demand queries incur a minimum of 10 MB of data processing charges per execution.
Domain References & SQL Queries
Telemetry Query Guides
On-Demand Compute: Billed Bytes (
references/compute_ondemand_billable.md): Authoritative Golden CTE (bytes_billed_cte), timezone-aligned billing date extraction (PST8PDT), BQML CREATE_MODEL 50x multiplier rules, script wrapper deduplication, and row-level security (RLS) masking checks.Capacity Compute: Billable Slots & Commitments (
references/compute_capacity_billable.md): Query templates for auditing billable capacity hours across 1-Year/3-Year commitments, uncovered baseline PAYG slots, and dynamic autoscaling hours.Storage Footprints & Usage (Bytes Stored) (
references/storage_footprints.md): Storage snapshot queries, compression ratio calculations, Time Travel / Fail-Safe churn, daily average GiB time-integrals, billing model evaluation, and search index coverage.
Performance & Troubleshooting Guides
Job Performance Queries (
references/job_performance_queries.md): Queries for evaluating individual and aggregate job performance, stage bottleneck flags, comparable jobs via normalized literals (query_info.query_hashes.normalized_literals), BI Engine acceleration, metadata cache (cmeta) acceleration, search index usage, materialized view rewrite usage, and execution variance outliers.Resource Contention Queries (
references/resource_contention_queries.md): Queries for diagnosing slot contention, queue latency, per-minute concurrency/queue timelines, and 1-second reservation slot saturation.Capacity & Configuration Queries (
references/capacity_and_configuration_queries.md): Queries for evaluating second-by-second baseline/max capacity ceilings, autoscaling saturation timelines, and auditing configuration changes (RESERVATION_CHANGES_BY_PROJECT,ASSIGNMENT_CHANGES_BY_PROJECT).
Schema Dictionaries (Column Definitions & Units)
Compute & Capacity Schema Dictionary (
references/schema_compute.md): Complete column dictionary, physical units, and least-privilege IAM roles for all compute, job, session, reservation, capacity commitment, and assignment views (JOBS*,JOBS_TIMELINE*,SESSIONS_BY_USER,SESSIONS_BY_PROJECT,RESERVATIONS*,RESERVATION_CHANGES*,RESERVATIONS_TIMELINE*,CAPACITY_COMMITMENTS*,CAPACITY_COMMITMENT_CHANGES_BY_PROJECT,ASSIGNMENTS*,ASSIGNMENT_CHANGES_BY_PROJECT).Storage & Data Catalog Schema Dictionary (
references/schema_storage.md): Complete column dictionary, physical units, and least-privilege IAM roles for all table storage, partition, column, snapshot, dataset, constraint, and replication views (TABLE_STORAGE*,TABLE_STORAGE_USAGE_TIMELINE*,TABLES*,TABLE_OPTIONS,COLUMNS,COLUMN_FIELD_PATHS,PARTITIONS,VIEWS,MATERIALIZED_VIEWS,TABLE_SNAPSHOTS*,TABLE_CONSTRAINTS,KEY_COLUMN_USAGE,SCHEMATA*,SCHEMATA_OPTIONS,SCHEMATA_REPLICAS*,SCHEMATA_LINKS,SHARED_DATASET_USAGE).Platform, Governance & Ingestion Schema Dictionary (
references/schema_others.md): Complete column dictionary, physical units, and least-privilege IAM roles for all remaining views including Access Control (OBJECT_PRIVILEGES,ROW_ACCESS_POLICIES,ROW_ACCESS_POLICY_OPTIONS), Streaming Ingestion (STREAMING_TIMELINE_BY_PROJECT*,WRITE_API_TIMELINE_BY_PROJECT*), Configuration Options (PROJECT_OPTIONS*,EFFECTIVE_PROJECT_OPTIONS,ORGANIZATION_OPTIONS*,ORGANIZATION_OPTIONS_CHANGES), Insights & Recommendations (RECOMMENDATIONS*,INSIGHTS), and Indexes/BI Engine/Routines (SEARCH_INDEXES*,SEARCH_INDEX_COLUMNS,SEARCH_INDEX_OPTIONS,VECTOR_INDEXES*,VECTOR_INDEX_COLUMNS,VECTOR_INDEX_OPTIONS,BI_CAPACITIES,BI_CAPACITY_CHANGES,ROUTINES*,ROUTINE_OPTIONS,PARAMETERS).
Files
- ATTRIBUTION.mdAdded by AutoGineer862 B
- LICENSELicence file added by AutoGineer11.1 KiB
- SKILL.md14.3 KiB
- references/attribution.md1.9 KiB
- references/capacity_and_configuration_queries.md6.6 KiB
- references/compute_capacity_billable.md6.2 KiB
- references/compute_ondemand_billable.md5.7 KiB
- references/job_performance_queries.md11.1 KiB
- references/resource_contention_queries.md9.3 KiB
- references/schema_compute.md40.4 KiB
- references/schema_others.md32.0 KiB
- references/schema_storage.md34.3 KiB
- references/storage_footprints.md10.1 KiB
references/schema_others.md
BigQuery Platform, Governance & Ingestion INFORMATION_SCHEMA Reference
A comprehensive dictionary, column definition guide, and physical unit
specification for all remaining BigQuery INFORMATION_SCHEMA views, covering BI
Engine Acceleration, Security, Streaming Ingestion, Routines, Search/Vector
Indexes, Configurations, and Recommendations.
Table of Contents
View Scoping & Qualification Matrix (Lines 61-79)
5. Routines, Functions, Stored Procedures & ML Views (Lines 80-179)
INFORMATION_SCHEMA.ROUTINES(Lines 82-120)INFORMATION_SCHEMA.PARAMETERS(Lines 121-151)INFORMATION_SCHEMA.ROUTINE_OPTIONS(Lines 152-179)
6. Streaming & Ingestion Views (Lines 180-249)
INFORMATION_SCHEMA.STREAMING_TIMELINE_BY_PROJECT(and_BY_ORGANIZATION,_BY_FOLDER) (Lines 182-214)INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT(and_BY_ORGANIZATION,_BY_FOLDER) (Lines 215-249)
7. Search, Vector, AI Indexes & BI Engine Views (Lines 250-405)
INFORMATION_SCHEMA.SEARCH_INDEXES(and_OPTIONS) (Lines 252-290)INFORMATION_SCHEMA.SEARCH_INDEX_COLUMNS(Lines 291-316)INFORMATION_SCHEMA.VECTOR_INDEXES(and_OPTIONS) (Lines 317-354)INFORMATION_SCHEMA.VECTOR_INDEX_COLUMNS(Lines 355-380)INFORMATION_SCHEMA.BI_CAPACITIES&BI_CAPACITY_CHANGES(Lines 381-405)
8. Security, Access Control, Governance & Policy Views (Lines 406-459)
INFORMATION_SCHEMA.OBJECT_PRIVILEGES(Lines 408-433)INFORMATION_SCHEMA.ROW_ACCESS_POLICIES&ROW_ACCESS_POLICY_OPTIONS(Lines 434-459)
9. Recommendations & Insights Views (Lines 460-536)
INFORMATION_SCHEMA.RECOMMENDATIONS(and_BY_PROJECT,_BY_ORGANIZATION) (Lines 462-498)INFORMATION_SCHEMA.INSIGHTS(and_BY_PROJECT) (Lines 499-536)
10. Project & Organization Configuration Views (Lines 537-633)
INFORMATION_SCHEMA.PROJECT_OPTIONS(Lines 539-565)INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS(Lines 566-591)INFORMATION_SCHEMA.ORGANIZATION_OPTIONS(Lines 592-613)INFORMATION_SCHEMA.ORGANIZATION_OPTIONS_CHANGES(Lines 614-633)
View Scoping & Qualification Matrix
Platform, acceleration, and governance views fall into Dual-Scoped, Region-Only, and Dataset-Only qualification categories:
<!-- mdformat off -->
| View Family | INFORMATION_SCHEMA View(s) | Qualification Scope | Syntax Pattern & Scoping Rules |
|---|---|---|---|
| BI Engine Acceleration | BI_CAPACITIES, BI_CAPACITY_CHANGES | Region-Only | `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.BI_CAPACITIES*<br>• In-memory RAM capacity and allocation modification logs. |
| Search Indexes | SEARCH_INDEXES, SEARCH_INDEX_COLUMNS, SEARCH_INDEX_OPTIONS, SEARCH_INDEX_COLUMN_OPTIONS<br><br>SEARCH_INDEXES_BY_ORGANIZATION | Dataset-Only<br><br><br>Region-Only | • Dataset views require {dataset_id}.<br>• Org view requires region-{region}. |
| Vector Indexes | VECTOR_INDEXES, VECTOR_INDEX_COLUMNS, VECTOR_INDEX_OPTIONS | Dual-Scoped | `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.VECTOR_INDEXES*<br>OR<br> `{project_id}`.`{dataset_id}`.INFORMATION_SCHEMA.VECTOR_INDEXES* |
| Access Control | OBJECT_PRIVILEGES | Region-Only | `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.OBJECT_PRIVILEGES<br>• IAM permissions on datasets, tables, views, and routines. |
| Row-Level Security | ROW_ACCESS_POLICIES, ROW_ACCESS_POLICY_OPTIONS | Dataset-Only | `{project_id}`.`{dataset_id}`.INFORMATION_SCHEMA.ROW_ACCESS_POLICIES*<br>• Row access filter expressions and predicate definitions. |
| Streaming Ingestion | STREAMING_TIMELINE_BY_PROJECT*, WRITE_API_TIMELINE_BY_PROJECT* | Region-Only | `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.{view_name}<br>• Streaming buffer and Storage Write API append throughput. |
| Configurations | PROJECT_OPTIONS*, EFFECTIVE_PROJECT_OPTIONS, ORGANIZATION_OPTIONS* | Region-Only | `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.{view_name}<br>• Default option settings and audit history. |
| Insights & Recommendations | RECOMMENDATIONS*, INSIGHTS | Region-Only | `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.{view_name}<br>• Slot rightsizing and partitioning recommendations. |
| Routines & Parameters | ROUTINES, PARAMETERS, ROUTINE_OPTIONS | Dual-Scoped | `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.ROUTINES*<br>OR<br> `{project_id}`.`{dataset_id}`.INFORMATION_SCHEMA.ROUTINES* |
<!-- mdformat on -->
5. Routines, Functions, Stored Procedures & ML Views
INFORMATION_SCHEMA.ROUTINES
High-Level Description
Defines user-defined functions (UDFs), stored procedures, remote functions, table functions (TVFs), parameter signatures, return types, determinism, and Cloud Function connection endpoints.
Required IAM Permissions & Predefined Roles
Requires
bigquery.routines.getandbigquery.routines.liston the target dataset or project.Predefined Roles: BigQuery Metadata Viewer (
roles/bigquery.metadataViewer- Least Privilege), BigQuery Data Viewer (roles/bigquery.dataViewer), or BigQuery Admin (roles/bigquery.admin).
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
specific_catalog | STRING | Project ID | Project name. |
specific_schema | STRING | Dataset ID | Dataset name. |
specific_name | STRING | Routine ID | Unique routine identifier. |
routine_catalog | STRING | Project ID | Catalog name. |
routine_schema | STRING | Dataset ID | Schema name. |
routine_name | STRING | Name | Function/procedure name. |
routine_type | STRING | Enum | 'FUNCTION', 'PROCEDURE', 'TABLE FUNCTION'. |
data_type | STRING | SQL Type | Return data type (or NULL for procedures). |
routine_body | STRING | Enum | 'SQL' or 'EXTERNAL'. |
routine_definition | STRING | SQL Code | Routine body expression or JavaScript/Python function text. |
external_language | STRING | Enum | 'JAVASCRIPT', 'PYTHON', 'SQL'. |
is_deterministic | STRING | 'YES' / 'NO' | Indicates whether identical inputs always return identical results. |
security_type | STRING | Enum | Execution security context: 'DEFINER' or 'INVOKER'. |
created | TIMESTAMP | UTC Timestamp | Creation timestamp. |
last_altered | TIMESTAMP | UTC Timestamp | Last modification timestamp. |
ddl | STRING | SQL String | DDL statement to recreate the routine. |
connection | STRING | Resource Path | Cloud Resource connection path for BigQuery Remote Functions. |
<!-- mdformat on -->
INFORMATION_SCHEMA.PARAMETERS
High-Level Description
Defines parameter signatures, modes, positions, and defaults for BigQuery routines.
Required IAM Permissions & Predefined Roles
Requires
bigquery.routines.getandbigquery.routines.liston the target dataset or project.Predefined Roles: BigQuery Metadata Viewer (
roles/bigquery.metadataViewer- Least Privilege), BigQuery Data Viewer (roles/bigquery.dataViewer), or BigQuery Admin (roles/bigquery.admin).
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
specific_catalog | STRING | Project ID | Project name. |
specific_schema | STRING | Dataset ID | Dataset name. |
specific_name | STRING | Routine ID | Unique routine identifier. |
ordinal_position | INT64 | Position | 1-indexed parameter position (0 = return value). |
parameter_mode | STRING | Enum | 'IN', 'OUT', 'INOUT'. |
is_result | STRING | 'YES' / 'NO' | 'YES' if row represents function return value. |
parameter_name | STRING | Param Name | Parameter identifier. |
data_type | STRING | SQL Type | GoogleSQL data type of parameter. |
parameter_default | STRING | SQL Literal | Default value expression. |
is_aggregate | STRING | 'YES' / 'NO' | Indicates aggregate parameter status. |
<!-- mdformat on -->
INFORMATION_SCHEMA.ROUTINE_OPTIONS
High-Level Description
Lists routine-level configuration options defined in OPTIONS(...) clauses.
Required IAM Permissions & Predefined Roles
Requires
bigquery.routines.getandbigquery.routines.liston the target dataset or project.Predefined Roles: BigQuery Metadata Viewer (
roles/bigquery.metadataViewer- Least Privilege), BigQuery Data Viewer (roles/bigquery.dataViewer), or BigQuery Admin (roles/bigquery.admin).
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
specific_catalog | STRING | Project ID | Project name. |
specific_schema | STRING | Dataset ID | Dataset name. |
specific_name | STRING | Routine ID | Unique routine identifier. |
option_name | STRING | Option Name | Option key. |
option_type | STRING | SQL Type | GoogleSQL type of option. |
option_value | STRING | Option Value | Configured option value. |
<!-- mdformat on -->
<a id="sec-streaming"></a>
6. Streaming & Ingestion Views
INFORMATION_SCHEMA.STREAMING_TIMELINE_BY_PROJECT (and _BY_ORGANIZATION, _BY_FOLDER)
High-Level Description
Provides 1-minute discrete telemetry for real-time data ingestion via BigQuery Storage Write API and legacy streaming. Tracks ingested payloads, row counts, and streaming error rates.
Required IAM Permissions & Predefined Roles
Project-Level (Least Privilege): Requires
bigquery.tables.liston the project. Granted by BigQuery Metadata Viewer (roles/bigquery.metadataViewer), BigQuery Data Viewer (roles/bigquery.dataViewer), or BigQuery Admin (roles/bigquery.admin)._BY_FOLDER: Requiresbigquery.tables.liston the parent folder._BY_ORGANIZATION: Requiresbigquery.tables.liston the organization.
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description & Conversion Formula |
|---|---|---|---|
dataset_id | STRING | Dataset ID | Target dataset. |
error_code | STRING | Error Code | Ingestion error classification code. |
folder_numbers | ARRAY<INT64> | Array | Folder hierarchy IDs containing the project (only in _BY_FOLDER). |
project_id | STRING | Project ID | Project receiving streamed rows. |
project_number | INT64 | Numeric ID | Numeric project identifier. |
start_timestamp | TIMESTAMP | UTC Timestamp | 1-minute discrete interval timestamp. |
table_id | STRING | Table ID | Target table. |
total_input_bytes | INT64 | Bytes | Raw ingested byte payload. |
total_requests | INT64 | Count | Number of streaming append requests. |
total_rows | INT64 | Count | Total records ingested. |
<!-- mdformat on -->
INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT (and _BY_ORGANIZATION, _BY_FOLDER)
High-Level Description
Monitors BigQuery Storage Write API traffic, throughput, and committed vs. default stream modes.
Required IAM Permissions & Predefined Roles
Project-Level (Least Privilege): Requires
bigquery.tables.liston the project. Granted by BigQuery Metadata Viewer (roles/bigquery.metadataViewer), BigQuery Data Viewer (roles/bigquery.dataViewer), or BigQuery Admin (roles/bigquery.admin)._BY_FOLDER: Requiresbigquery.tables.liston the parent folder._BY_ORGANIZATION: Requiresbigquery.tables.liston the organization.
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
dataset_id | STRING | Dataset ID | Target dataset ID. |
error_code | STRING | Error Code | Write API error code. |
folder_numbers | ARRAY<INT64> | Array | Folder hierarchy IDs containing the project (only in _BY_FOLDER). |
project_id | STRING | Project ID | Project containing the target tables. |
project_number | INT64 | Numeric ID | Numeric project identifier. |
start_timestamp | TIMESTAMP | UTC Timestamp | 1-minute discrete interval timestamp. |
stream_type | STRING | Enum | 'COMMITTED', 'PENDING', 'BUFFERED', 'DEFAULT'. |
table_id | STRING | Table ID | Target table ID. |
total_input_bytes | INT64 | Bytes | Total bytes processed by the Storage Write API. |
total_requests | INT64 | Count | Number of append requests. |
total_rows | INT64 | Count | Total rows appended. |
<!-- mdformat on -->
<a id="sec-indexes"></a>
7. Search, Vector, AI Indexes & BI Engine Views
INFORMATION_SCHEMA.SEARCH_INDEXES (and _OPTIONS)
High-Level Description
Monitors BigQuery text Search Indexes, indexing coverage percentages, storage footprints, text analyzers, and unindexed row backlogs.
Required IAM Permissions & Predefined Roles
Dataset/Project Scope (Least Privilege): Requires
bigquery.tables.getandbigquery.tables.liston the dataset or project. Granted by BigQuery Metadata Viewer (roles/bigquery.metadataViewer), BigQuery Data Viewer (roles/bigquery.dataViewer), or BigQuery Admin (roles/bigquery.admin)._BY_ORGANIZATION: Requiresbigquery.tables.getandbigquery.tables.liston the organization.
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
analyzer | STRING | Enum | Text analyzer: 'LOG_ANALYZER', 'NO_OP_ANALYZER', 'TEXT_ANALYZER'. |
coverage_percentage | INT64 | Percent | Percentage of base table data currently indexed (0–100). |
creation_time | TIMESTAMP | UTC Timestamp | Timestamp when index was created. |
ddl | STRING | SQL String | DDL statement to recreate search index. |
disable_reason | STRING | Reason String | Reason index was disabled. |
disable_time | TIMESTAMP | UTC Timestamp | Timestamp when index was disabled. |
index_catalog | STRING | Project ID | Project name. |
index_name | STRING | Index Name | Search index name. |
index_schema | STRING | Dataset ID | Dataset name. |
index_status | STRING | Enum | 'ACTIVE', 'PENDING', 'STALE', 'DISABLED'. |
last_index_alteration_info | RECORD | Alteration Struct | Details of latest user-triggered index alteration (status, message, new_coverage_percentage, start_time, end_time, ddl). |
last_modification_time | TIMESTAMP | UTC Timestamp | Last index modification timestamp. |
last_refresh_time | TIMESTAMP | UTC Timestamp | Last completed index build timestamp. |
table_name | STRING | Table ID | Base table identifier. |
total_logical_bytes | INT64 | Bytes | Logical storage consumed by search index structures. |
total_storage_bytes | INT64 | Bytes | Physical storage consumed by search index structures. |
unindexed_row_count | INT64 | Count | Number of base table rows not yet indexed. |
<!-- mdformat on -->
INFORMATION_SCHEMA.SEARCH_INDEX_COLUMNS
High-Level Description
Defines columns participating in BigQuery text Search Indexes.
Required IAM Permissions & Predefined Roles
Requires
bigquery.tables.getandbigquery.tables.liston the dataset or project.Predefined Roles: BigQuery Metadata Viewer (
roles/bigquery.metadataViewer- Least Privilege), BigQuery Data Viewer (roles/bigquery.dataViewer), or BigQuery Admin (roles/bigquery.admin).
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
index_catalog | STRING | Project ID | Project name. |
index_schema | STRING | Dataset ID | Dataset name. |
table_name | STRING | Table ID | Table name. |
index_name | STRING | Index Name | Search index name. |
index_column_name | STRING | Column Name | Name of indexed column. |
index_field_path | STRING | Field Path | Field path for struct columns. |
<!-- mdformat on -->
INFORMATION_SCHEMA.VECTOR_INDEXES (and _OPTIONS)
High-Level Description
Monitors Vector Indexes (e.g. IVF, HNSW, Tree-AH) for vector similarity search
and embedding lookups (VECTOR_SEARCH).
Required IAM Permissions & Predefined Roles
Requires
bigquery.tables.getandbigquery.tables.liston the target dataset or project.Predefined Roles: BigQuery Metadata Viewer (
roles/bigquery.metadataViewer- Least Privilege), BigQuery Data Viewer (roles/bigquery.dataViewer), or BigQuery Admin (roles/bigquery.admin).
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
coverage_percentage | INT64 | Percent | Base table vector data indexing coverage percentage (0–100). |
creation_time | TIMESTAMP | UTC Timestamp | Timestamp when vector index was created. |
ddl | STRING | SQL String | DDL statement to recreate vector index. |
disable_reason | STRING | Reason String | Reason index was disabled. |
disable_time | TIMESTAMP | UTC Timestamp | Timestamp when index was disabled. |
index_catalog | STRING | Project ID | Project name. |
index_name | STRING | Index Name | Vector index name. |
index_schema | STRING | Dataset ID | Dataset name. |
index_status | STRING | Enum | 'ACTIVE', 'PENDING DISABLEMENT', 'TEMPORARILY DISABLED', 'PERMANENTLY DISABLED'. |
last_index_alteration_info | RECORD | Alteration Struct | Details of latest user-triggered index alteration (status, message, new_coverage_percentage, start_time, end_time, ddl). |
last_model_build_time | TIMESTAMP | UTC Timestamp | Timestamp when index model build was initiated. |
last_modification_time | TIMESTAMP | UTC Timestamp | Last index modification timestamp. |
last_refresh_time | TIMESTAMP | UTC Timestamp | Timestamp when index weights were last updated. |
table_name | STRING | Table ID | Base table name. |
total_logical_bytes | INT64 | Bytes | Logical index size. |
total_storage_bytes | INT64 | Bytes | Physical compressed index size. |
unindexed_row_count | INT64 | Count | Number of vectors pending indexing. |
<!-- mdformat on -->
INFORMATION_SCHEMA.VECTOR_INDEX_COLUMNS
High-Level Description
Defines columns participating in BigQuery Vector Indexes.
Required IAM Permissions & Predefined Roles
Requires
bigquery.tables.getandbigquery.tables.liston the target dataset or project.Predefined Roles: BigQuery Metadata Viewer (
roles/bigquery.metadataViewer- Least Privilege), BigQuery Data Viewer (roles/bigquery.dataViewer), or BigQuery Admin (roles/bigquery.admin).
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
index_catalog | STRING | Project ID | Project name. |
index_column_name | STRING | Column Name | Vector embedding column name. |
index_field_path | STRING | Field Path | Field path for struct columns. |
index_name | STRING | Index Name | Vector index name. |
index_schema | STRING | Dataset ID | Dataset name. |
table_name | STRING | Table ID | Table name. |
<!-- mdformat on -->
INFORMATION_SCHEMA.BI_CAPACITIES & BI_CAPACITY_CHANGES
High-Level Description
Tracks BigQuery BI Engine in-memory acceleration reservations, configured RAM capacities, and capacity alteration events.
Required IAM Permissions & Predefined Roles
Requires
bigquery.bireservations.geton the project.Predefined Roles: BigQuery Resource Viewer (
roles/bigquery.resourceViewer), BigQuery Resource Admin (roles/bigquery.resourceAdmin), or BigQuery Admin (roles/bigquery.admin).
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
bi_capacity_name | STRING | Resource Path | BI Engine capacity identifier. |
preferred_tables | ARRAY<RECORD> | Array | Pinned tables prioritized for memory caching. |
project_id | STRING | Project ID | Project hosting the BI Engine capacity. |
project_number | INT64 | Numeric ID | Project number. |
size | INT64 | Bytes | Configured in-memory RAM capacity allocation. |
<!-- mdformat on -->
8. Security, Access Control, Governance & Policy Views
INFORMATION_SCHEMA.OBJECT_PRIVILEGES
High-Level Description
Lists IAM permissions and role grants across datasets, tables, views, routines, and models.
Required IAM Permissions & Predefined Roles
Requires
bigquery.datasets.getIamPolicyon datasets orbigquery.tables.getIamPolicyon tables.Predefined Roles: BigQuery Data Owner (
roles/bigquery.dataOwner), BigQuery Admin (roles/bigquery.admin), or Security Admin (roles/iam.securityAdmin).
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
grantee | STRING | Principal | Grantee identity ('user:[email protected]', 'group:[email protected]', 'serviceAccount:[email protected]'). |
object_catalog | STRING | Project ID | Project containing the resource. |
object_name | STRING | Resource Name | Name of table, view, or dataset. |
object_schema | STRING | Dataset ID | Dataset containing the resource. |
object_type | STRING | Enum | 'SCHEMA', 'TABLE', 'VIEW', 'ROUTINE', 'MODEL'. |
privilege_type | STRING | Role ID | IAM Role ID granted (e.g. 'roles/bigquery.dataViewer'). |
<!-- mdformat on -->
INFORMATION_SCHEMA.ROW_ACCESS_POLICIES & ROW_ACCESS_POLICY_OPTIONS
High-Level Description
Defines Row-Level Security (RLS) policies and filter predicates on base tables within a dataset.
Required IAM Permissions & Predefined Roles
Requires
bigquery.rowAccessPolicies.getFilteredDataorbigquery.rowAccessPolicies.getIamPolicyon the target table/dataset.Predefined Roles: BigQuery Data Owner (
roles/bigquery.dataOwner) or BigQuery Admin (roles/bigquery.admin).
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
creation_time | TIMESTAMP | UTC Timestamp | Timestamp when policy was created. |
filter_predicate | STRING | SQL Boolean | GoogleSQL filter expression applied to restrict row visibility. |
last_modified_time | TIMESTAMP | UTC Timestamp | Timestamp when filter predicate was modified. |
row_access_policy_name | STRING | Policy Name | Unique RLS policy identifier. |
table_catalog | STRING | Project ID | Project name. |
table_name | STRING | Table ID | Table identifier. |
table_schema | STRING | Dataset ID | Dataset identifier. |
<!-- mdformat on -->
9. Recommendations & Insights Views
INFORMATION_SCHEMA.RECOMMENDATIONS (and _BY_PROJECT, _BY_ORGANIZATION)
High-Level Description
Surfaces automated BigQuery Recommender recommendations for cost savings, performance optimization, partition/cluster suggestions, and reservation rightsizing.
Required IAM Permissions & Predefined Roles
Project-Level (Least Privilege): Requires
recommender.bigqueryCapacityCommitmentsRecommendations.getandrecommender.bigqueryCapacityCommitmentsRecommendations.liston the project. Granted by Recommender Viewer (roles/recommender.viewer/roles/recommender.bigqueryViewer) or BigQuery Admin (roles/bigquery.admin)._BY_ORGANIZATION: Requires recommender permissions at the organization level.
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
additional_details | RECORD | Struct | JSON details and recommended DDL/CLI operations (operations.action, operations.path, operations.value). |
associated_insight_ids | ARRAY<STRING> | IDs | IDs of INSIGHTS supporting this recommendation. |
description | STRING | Text | Human-readable recommendation text and rationale. |
last_updated_time | TIMESTAMP | UTC Timestamp | Timestamp when recommendation was generated or refreshed. |
primary_impact | RECORD | Struct | Cost, performance, or security impact (category, cost_projection.duration_seconds). |
priority | STRING | Enum | 'P1', 'P2', 'P3', 'P4'. |
project_id | STRING | Project ID | Project ID. |
project_number | INT64 | Numeric ID | Project number. |
recommendation_id | STRING | Base64 ID | Unique recommendation identifier. |
recommender | STRING | String | Recommender type (e.g. 'google.bigquery.table.PartitionClusterRecommender'). |
state | STRING | Enum | 'ACTIVE', 'CLAIMED', 'SUCCEEDED', 'DISMISSED'. |
subtype | STRING | String | Subtype classification (e.g. 'PARTITION', 'CLUSTER'). |
target_resources | ARRAY<STRING> | Resource Paths | Fully qualified GCP resources affected by recommendation. |
<!-- mdformat on -->
INFORMATION_SCHEMA.INSIGHTS (and _BY_PROJECT)
High-Level Description
Surfaces underlying workload signals, slot bottlenecks, table scan patterns, and stats that trigger recommender actions.
Required IAM Permissions & Predefined Roles
Project-Level (Least Privilege): Requires
recommender.bigqueryCapacityCommitmentsInsights.get/listorrecommender.bigqueryPartitionClusterInsights.get/liston the project. Granted by Recommender Viewer (roles/recommender.viewer/roles/recommender.bigqueryViewer) or BigQuery Admin (roles/bigquery.admin)._BY_ORGANIZATION: Requires insight permissions at the organization level.
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
additional_details | RECORD | Struct | JSON details and observation period (observation_period_seconds). |
associated_recommendation_ids | ARRAY<STRING> | IDs | Full recommendation names/IDs associated with this insight. |
category | STRING | Enum | 'COST', 'PERFORMANCE', 'SECURITY'. |
description | STRING | Text | Description of observed performance signal. |
insight_id | STRING | Base64 ID | Unique insight identifier. |
insight_type | STRING | String | Insight type (e.g. 'google.bigquery.table.StatsInsight'). |
last_updated_time | TIMESTAMP | UTC Timestamp | Generation timestamp. |
project_id | STRING | Project ID | Project ID. |
project_number | INT64 | Numeric ID | Project number. |
severity | STRING | Enum | 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL'. |
state | STRING | Enum | 'ACTIVE', 'ACCEPTED', 'DISMISSED'. |
subtype | STRING | String | Subtype classification ('TABLE_STATS'). |
target_resources | ARRAY<STRING> | Resource Paths | Targeted GCP resources. |
<!-- mdformat on -->
<a id="sec-config"></a>
10. Project & Organization Configuration Views
INFORMATION_SCHEMA.PROJECT_OPTIONS
High-Level Description
Lists configured project-level default options (e.g. default time travel duration, KMS keys, default query priority, and default reservation assignments).
Required IAM Permissions & Predefined Roles
Requires
bigquery.config.geton the project.Predefined Roles: BigQuery Metadata Viewer (
roles/bigquery.metadataViewer- Least Privilege), BigQuery Resource Viewer (roles/bigquery.resourceViewer), or BigQuery Admin (roles/bigquery.admin).
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
project_number | INT64 | Numeric ID | Project number. |
project_id | STRING | Project ID | Project identifier. |
option_name | STRING | Option Name | Option identifier (e.g. 'default_time_travel_hours', 'default_query_job_timeout_ms'). |
option_description | STRING | Text | Description of the option's behavior. |
option_type | STRING | SQL Type | GoogleSQL data type. |
option_value | STRING | Value String | Configured parameter value. |
<!-- mdformat on -->
INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS
High-Level Description
Lists effective project options accounting for organization and folder inheritance hierarchy.
Required IAM Permissions & Predefined Roles
Requires
bigquery.config.geton the project.Predefined Roles: BigQuery Metadata Viewer (
roles/bigquery.metadataViewer- Least Privilege), BigQuery Resource Viewer (roles/bigquery.resourceViewer), or BigQuery Admin (roles/bigquery.admin).
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
project_number | INT64 | Numeric ID | Project number. |
project_id | STRING | Project ID | Project identifier. |
option_name | STRING | Option Name | Option identifier. |
option_value | STRING | Value String | Effective option value. |
option_set_level | STRING | Enum | Definition level: 'DEFAULT', 'ORGANIZATION', 'FOLDER', 'PROJECT', 'USER'. |
option_set_on_id | STRING | Resource ID | GCP resource ID where the setting was overridden. |
<!-- mdformat on -->
INFORMATION_SCHEMA.ORGANIZATION_OPTIONS
High-Level Description
Defines organization-level default configuration settings across BigQuery projects.
Required IAM Permissions & Predefined Roles
Requires
bigquery.config.geton the organization.Predefined Roles: BigQuery Admin (
roles/bigquery.admin) on the organization resource.
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
option_name | STRING | Option Name | Organization setting name. |
option_description | STRING | Text | Option description. |
option_type | STRING | SQL Type | Option data type. |
option_value | STRING | Value String | Configured organization-wide value. |
<!-- mdformat on -->
INFORMATION_SCHEMA.ORGANIZATION_OPTIONS_CHANGES
High-Level Description
Maintains an audit log of organization-level setting updates.
Required IAM Permissions & Predefined Roles
Requires
bigquery.config.geton the organization.Predefined Roles: BigQuery Admin (
roles/bigquery.admin) on the organization resource.
<!-- mdformat off -->
| Column Name | Data Type | Physical Unit | Description |
|---|---|---|---|
project_id | STRING | Project ID | Project where change originated. |
update_time | TIMESTAMP | UTC Timestamp | Timestamp of option change. |
username | STRING | User Identity | Identity of administrator who committed change. |
updated_options | JSON | JSON Struct | JSON object containing old and new setting values. |
<!-- mdformat on -->
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs a command-line tool, Needs Node.js
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Publisher
- Google (Official)
- Source
- google/skills · skills/cloud/bigquery-observability · commit 2194d3b
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Google.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download bigquery-observability.zip