Generated banner for Bigquery Observability
Generated logo for Bigquery Observability

Bigquery Observability

GoogleOfficialPublished by Google

  • Skill
  • Tool integration
  • Data and AI
  • Apache-2.0
  • No issues found

From the author

Provides data-retrieval best practices, tool selection guidance, and performant SQL query syntax for BigQuery telemetry across INFORMATION_SCHEMA, Cloud Monitoring, and the REST API. Use when the telemetry to fetch is already known, selecting telemetry tools, writing performant INFORMATION_SCHEMA queries, retrieving telemetry for diagnosing single-job performance bottlenecks, investigating slot contention, job concurrency and queue latency, analyzing reservation capacity, utilization and autoscaling saturation, or auditing capacity-based and on-demand compute and storage resource billable usage. Don't use for root-cause diagnosis or symptom troubleshooting when the cause is unknown (use bigquery-troubleshooting first), or for writing or optimizing business logic SQL (use bigquery-optimization).
— the description by Google

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

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/google/bigquery-observability/download
  2. Unzip 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 -->

ToolPrimary Use CasesStrengths & CapabilitiesWhen 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:

  1. Google Cloud SDK: Ensure the Google Cloud SDK is installed and configured.

  2. Project Selection: Set the active Google Cloud project:

    gcloud config set project {project_id}
  3. API Enablement: Ensure the BigQuery and Cloud Monitoring APIs are enabled:

    gcloud services enable bigquery.googleapis.com monitoring.googleapis.com
  4. Authentication: Authenticate the environment:

    • CLI queries and bq commands: gcloud auth login

    • SDKs and automated client tools: gcloud auth application-default login

    • Service accounts: Set GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

  5. 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.resourceViewer or roles/bigquery.admin: Organization-level jobs and reservation telemetry.

      • roles/monitoring.viewer: Cloud Monitoring metrics.

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

  1. 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}
  2. Diagnostic Transition Logic: If no job-level issues are found (e.g. no clear internal bottlenecks), the investigation should transition to system-level INFORMATION_SCHEMA queries (such as JOBS_TIMELINE or RESERVATIONS_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
  1. Region-Qualified Syntax:

    `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.{view}

    Example: `my-project`.`region-us`.INFORMATION_SCHEMA.JOBS

    Applies to: Regional telemetry views (JOBS*, JOBS_TIMELINE*, RESERVATIONS*, CAPACITY_COMMITMENTS*, TABLE_STORAGE*, STREAMING_TIMELINE*). The client query execution location MUST match the region-{region} qualifier (or BigQuery throws: Not found: Table {project_id}:region-{region}.INFORMATION_SCHEMA.{view} was not found in location {location}).

  2. Dataset-Qualified Syntax:

    `{project_id}`.`{dataset_id}`.INFORMATION_SCHEMA.{view}

    Example: `my-project`.`analytics`.INFORMATION_SCHEMA.TABLES

    Applies to: Dataset-scoped views (PARTITIONS, SEARCH_INDEXES*, ROW_ACCESS_POLICIES). Never use region- with dataset views.

  3. Dual-Scoped Views: Views like TABLES, COLUMNS, COLUMN_FIELD_PATHS, VIEWS, ROUTINES, and VECTOR_INDEXES can be qualified with either {dataset_id} or region-{region} depending on whether dataset or region-wide analysis is required.

  4. 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:

  1. 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 only bigquery.jobs.list (granted via roles/bigquery.user or roles/bigquery.jobUser), avoiding the need for bigquery.jobs.listAll or roles/bigquery.admin.

  2. Dataset-Level over Region/Project-Level: When querying table metadata, columns, or views for a specific dataset, qualify with {dataset_id} rather than region-{region} when project-level metadata access is restricted. Dataset-scoped queries require permissions only on that target dataset.

  3. Project-Level over Org/Folder-Level (_BY_PROJECT): Always start with project-scoped views before escalating to _BY_FOLDER or _BY_ORGANIZATION. Folder and organization queries require broad folder/org IAM permissions (bigquery.jobs.listAll or bigquery.tables.list at the Org/Folder node).

  4. Metadata Roles over Data Roles: For table and storage introspection, prefer roles/bigquery.metadataViewer (which provides bigquery.tables.get and bigquery.tables.list) over roles/bigquery.dataViewer or roles/bigquery.dataOwner when data read access (bigquery.tables.getData) is not needed. (Note: INFORMATION_SCHEMA.PARTITIONS uniquely requires bigquery.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)) or usage_date to 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 * against INFORMATION_SCHEMA; only project required columns.

  • Dry Run & Cost Estimation: Use a dry run (bq query --dry_run --use_legacy_sql=false "{query}" or API dryRun=true) before executing complex queries, multi-view joins, or large scans to validate syntax and estimate totalBytesProcessed at 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-us returns only multi-region US metadata and does not include single regions like region-us-central1).

  • No Multi-Region Aggregation in SQL: Region qualifiers cannot be joined cross-region in a single query (e.g. region-us cannot join region-eu).

  • Uncached Execution & Minimum Scan Size: INFORMATION_SCHEMA query 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

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 FamilyINFORMATION_SCHEMA View(s)Qualification ScopeSyntax Pattern & Scoping Rules
BI Engine AccelerationBI_CAPACITIES, BI_CAPACITY_CHANGESRegion-Only `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.BI_CAPACITIES*<br>• In-memory RAM capacity and allocation modification logs.
Search IndexesSEARCH_INDEXES, SEARCH_INDEX_COLUMNS, SEARCH_INDEX_OPTIONS, SEARCH_INDEX_COLUMN_OPTIONS<br><br>SEARCH_INDEXES_BY_ORGANIZATIONDataset-Only<br><br><br>Region-Only• Dataset views require {dataset_id}.<br>• Org view requires region-{region}.
Vector IndexesVECTOR_INDEXES, VECTOR_INDEX_COLUMNS, VECTOR_INDEX_OPTIONSDual-Scoped `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.VECTOR_INDEXES*<br>OR<br> `{project_id}`.`{dataset_id}`.INFORMATION_SCHEMA.VECTOR_INDEXES*
Access ControlOBJECT_PRIVILEGESRegion-Only `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.OBJECT_PRIVILEGES<br>• IAM permissions on datasets, tables, views, and routines.
Row-Level SecurityROW_ACCESS_POLICIES, ROW_ACCESS_POLICY_OPTIONSDataset-Only `{project_id}`.`{dataset_id}`.INFORMATION_SCHEMA.ROW_ACCESS_POLICIES*<br>• Row access filter expressions and predicate definitions.
Streaming IngestionSTREAMING_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.
ConfigurationsPROJECT_OPTIONS*, EFFECTIVE_PROJECT_OPTIONS, ORGANIZATION_OPTIONS*Region-Only `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.{view_name}<br>• Default option settings and audit history.
Insights & RecommendationsRECOMMENDATIONS*, INSIGHTSRegion-Only `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.{view_name}<br>• Slot rightsizing and partitioning recommendations.
Routines & ParametersROUTINES, PARAMETERS, ROUTINE_OPTIONSDual-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.get and bigquery.routines.list on 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 NameData TypePhysical UnitDescription
specific_catalogSTRINGProject IDProject name.
specific_schemaSTRINGDataset IDDataset name.
specific_nameSTRINGRoutine IDUnique routine identifier.
routine_catalogSTRINGProject IDCatalog name.
routine_schemaSTRINGDataset IDSchema name.
routine_nameSTRINGNameFunction/procedure name.
routine_typeSTRINGEnum'FUNCTION', 'PROCEDURE', 'TABLE FUNCTION'.
data_typeSTRINGSQL TypeReturn data type (or NULL for procedures).
routine_bodySTRINGEnum'SQL' or 'EXTERNAL'.
routine_definitionSTRINGSQL CodeRoutine body expression or JavaScript/Python function text.
external_languageSTRINGEnum'JAVASCRIPT', 'PYTHON', 'SQL'.
is_deterministicSTRING'YES' / 'NO'Indicates whether identical inputs always return identical results.
security_typeSTRINGEnumExecution security context: 'DEFINER' or 'INVOKER'.
createdTIMESTAMPUTC TimestampCreation timestamp.
last_alteredTIMESTAMPUTC TimestampLast modification timestamp.
ddlSTRINGSQL StringDDL statement to recreate the routine.
connectionSTRINGResource PathCloud 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.get and bigquery.routines.list on 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 NameData TypePhysical UnitDescription
specific_catalogSTRINGProject IDProject name.
specific_schemaSTRINGDataset IDDataset name.
specific_nameSTRINGRoutine IDUnique routine identifier.
ordinal_positionINT64Position1-indexed parameter position (0 = return value).
parameter_modeSTRINGEnum'IN', 'OUT', 'INOUT'.
is_resultSTRING'YES' / 'NO''YES' if row represents function return value.
parameter_nameSTRINGParam NameParameter identifier.
data_typeSTRINGSQL TypeGoogleSQL data type of parameter.
parameter_defaultSTRINGSQL LiteralDefault value expression.
is_aggregateSTRING'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.get and bigquery.routines.list on 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 NameData TypePhysical UnitDescription
specific_catalogSTRINGProject IDProject name.
specific_schemaSTRINGDataset IDDataset name.
specific_nameSTRINGRoutine IDUnique routine identifier.
option_nameSTRINGOption NameOption key.
option_typeSTRINGSQL TypeGoogleSQL type of option.
option_valueSTRINGOption ValueConfigured 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.list on the project. Granted by BigQuery Metadata Viewer (roles/bigquery.metadataViewer), BigQuery Data Viewer (roles/bigquery.dataViewer), or BigQuery Admin (roles/bigquery.admin).

  • _BY_FOLDER: Requires bigquery.tables.list on the parent folder.

  • _BY_ORGANIZATION: Requires bigquery.tables.list on the organization.

<!-- mdformat off -->

Column NameData TypePhysical UnitDescription & Conversion Formula
dataset_idSTRINGDataset IDTarget dataset.
error_codeSTRINGError CodeIngestion error classification code.
folder_numbersARRAY<INT64>ArrayFolder hierarchy IDs containing the project (only in _BY_FOLDER).
project_idSTRINGProject IDProject receiving streamed rows.
project_numberINT64Numeric IDNumeric project identifier.
start_timestampTIMESTAMPUTC Timestamp1-minute discrete interval timestamp.
table_idSTRINGTable IDTarget table.
total_input_bytesINT64BytesRaw ingested byte payload.
total_requestsINT64CountNumber of streaming append requests.
total_rowsINT64CountTotal 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.list on the project. Granted by BigQuery Metadata Viewer (roles/bigquery.metadataViewer), BigQuery Data Viewer (roles/bigquery.dataViewer), or BigQuery Admin (roles/bigquery.admin).

  • _BY_FOLDER: Requires bigquery.tables.list on the parent folder.

  • _BY_ORGANIZATION: Requires bigquery.tables.list on the organization.

<!-- mdformat off -->

Column NameData TypePhysical UnitDescription
dataset_idSTRINGDataset IDTarget dataset ID.
error_codeSTRINGError CodeWrite API error code.
folder_numbersARRAY<INT64>ArrayFolder hierarchy IDs containing the project (only in _BY_FOLDER).
project_idSTRINGProject IDProject containing the target tables.
project_numberINT64Numeric IDNumeric project identifier.
start_timestampTIMESTAMPUTC Timestamp1-minute discrete interval timestamp.
stream_typeSTRINGEnum'COMMITTED', 'PENDING', 'BUFFERED', 'DEFAULT'.
table_idSTRINGTable IDTarget table ID.
total_input_bytesINT64BytesTotal bytes processed by the Storage Write API.
total_requestsINT64CountNumber of append requests.
total_rowsINT64CountTotal 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.get and bigquery.tables.list on 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: Requires bigquery.tables.get and bigquery.tables.list on the organization.

<!-- mdformat off -->

Column NameData TypePhysical UnitDescription
analyzerSTRINGEnumText analyzer: 'LOG_ANALYZER', 'NO_OP_ANALYZER', 'TEXT_ANALYZER'.
coverage_percentageINT64PercentPercentage of base table data currently indexed (0–100).
creation_timeTIMESTAMPUTC TimestampTimestamp when index was created.
ddlSTRINGSQL StringDDL statement to recreate search index.
disable_reasonSTRINGReason StringReason index was disabled.
disable_timeTIMESTAMPUTC TimestampTimestamp when index was disabled.
index_catalogSTRINGProject IDProject name.
index_nameSTRINGIndex NameSearch index name.
index_schemaSTRINGDataset IDDataset name.
index_statusSTRINGEnum'ACTIVE', 'PENDING', 'STALE', 'DISABLED'.
last_index_alteration_infoRECORDAlteration StructDetails of latest user-triggered index alteration (status, message, new_coverage_percentage, start_time, end_time, ddl).
last_modification_timeTIMESTAMPUTC TimestampLast index modification timestamp.
last_refresh_timeTIMESTAMPUTC TimestampLast completed index build timestamp.
table_nameSTRINGTable IDBase table identifier.
total_logical_bytesINT64BytesLogical storage consumed by search index structures.
total_storage_bytesINT64BytesPhysical storage consumed by search index structures.
unindexed_row_countINT64CountNumber 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.get and bigquery.tables.list on 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 NameData TypePhysical UnitDescription
index_catalogSTRINGProject IDProject name.
index_schemaSTRINGDataset IDDataset name.
table_nameSTRINGTable IDTable name.
index_nameSTRINGIndex NameSearch index name.
index_column_nameSTRINGColumn NameName of indexed column.
index_field_pathSTRINGField PathField 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.get and bigquery.tables.list on 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 NameData TypePhysical UnitDescription
coverage_percentageINT64PercentBase table vector data indexing coverage percentage (0–100).
creation_timeTIMESTAMPUTC TimestampTimestamp when vector index was created.
ddlSTRINGSQL StringDDL statement to recreate vector index.
disable_reasonSTRINGReason StringReason index was disabled.
disable_timeTIMESTAMPUTC TimestampTimestamp when index was disabled.
index_catalogSTRINGProject IDProject name.
index_nameSTRINGIndex NameVector index name.
index_schemaSTRINGDataset IDDataset name.
index_statusSTRINGEnum'ACTIVE', 'PENDING DISABLEMENT', 'TEMPORARILY DISABLED', 'PERMANENTLY DISABLED'.
last_index_alteration_infoRECORDAlteration StructDetails of latest user-triggered index alteration (status, message, new_coverage_percentage, start_time, end_time, ddl).
last_model_build_timeTIMESTAMPUTC TimestampTimestamp when index model build was initiated.
last_modification_timeTIMESTAMPUTC TimestampLast index modification timestamp.
last_refresh_timeTIMESTAMPUTC TimestampTimestamp when index weights were last updated.
table_nameSTRINGTable IDBase table name.
total_logical_bytesINT64BytesLogical index size.
total_storage_bytesINT64BytesPhysical compressed index size.
unindexed_row_countINT64CountNumber 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.get and bigquery.tables.list on 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 NameData TypePhysical UnitDescription
index_catalogSTRINGProject IDProject name.
index_column_nameSTRINGColumn NameVector embedding column name.
index_field_pathSTRINGField PathField path for struct columns.
index_nameSTRINGIndex NameVector index name.
index_schemaSTRINGDataset IDDataset name.
table_nameSTRINGTable IDTable 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.get on 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 NameData TypePhysical UnitDescription
bi_capacity_nameSTRINGResource PathBI Engine capacity identifier.
preferred_tablesARRAY<RECORD>ArrayPinned tables prioritized for memory caching.
project_idSTRINGProject IDProject hosting the BI Engine capacity.
project_numberINT64Numeric IDProject number.
sizeINT64BytesConfigured 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.getIamPolicy on datasets or bigquery.tables.getIamPolicy on tables.

  • Predefined Roles: BigQuery Data Owner (roles/bigquery.dataOwner), BigQuery Admin (roles/bigquery.admin), or Security Admin (roles/iam.securityAdmin).

<!-- mdformat off -->

Column NameData TypePhysical UnitDescription
granteeSTRINGPrincipalGrantee identity ('user:[email protected]', 'group:[email protected]', 'serviceAccount:[email protected]').
object_catalogSTRINGProject IDProject containing the resource.
object_nameSTRINGResource NameName of table, view, or dataset.
object_schemaSTRINGDataset IDDataset containing the resource.
object_typeSTRINGEnum'SCHEMA', 'TABLE', 'VIEW', 'ROUTINE', 'MODEL'.
privilege_typeSTRINGRole IDIAM 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.getFilteredData or bigquery.rowAccessPolicies.getIamPolicy on the target table/dataset.

  • Predefined Roles: BigQuery Data Owner (roles/bigquery.dataOwner) or BigQuery Admin (roles/bigquery.admin).

<!-- mdformat off -->

Column NameData TypePhysical UnitDescription
creation_timeTIMESTAMPUTC TimestampTimestamp when policy was created.
filter_predicateSTRINGSQL BooleanGoogleSQL filter expression applied to restrict row visibility.
last_modified_timeTIMESTAMPUTC TimestampTimestamp when filter predicate was modified.
row_access_policy_nameSTRINGPolicy NameUnique RLS policy identifier.
table_catalogSTRINGProject IDProject name.
table_nameSTRINGTable IDTable identifier.
table_schemaSTRINGDataset IDDataset 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.get and recommender.bigqueryCapacityCommitmentsRecommendations.list on 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 NameData TypePhysical UnitDescription
additional_detailsRECORDStructJSON details and recommended DDL/CLI operations (operations.action, operations.path, operations.value).
associated_insight_idsARRAY<STRING>IDsIDs of INSIGHTS supporting this recommendation.
descriptionSTRINGTextHuman-readable recommendation text and rationale.
last_updated_timeTIMESTAMPUTC TimestampTimestamp when recommendation was generated or refreshed.
primary_impactRECORDStructCost, performance, or security impact (category, cost_projection.duration_seconds).
prioritySTRINGEnum'P1', 'P2', 'P3', 'P4'.
project_idSTRINGProject IDProject ID.
project_numberINT64Numeric IDProject number.
recommendation_idSTRINGBase64 IDUnique recommendation identifier.
recommenderSTRINGStringRecommender type (e.g. 'google.bigquery.table.PartitionClusterRecommender').
stateSTRINGEnum'ACTIVE', 'CLAIMED', 'SUCCEEDED', 'DISMISSED'.
subtypeSTRINGStringSubtype classification (e.g. 'PARTITION', 'CLUSTER').
target_resourcesARRAY<STRING>Resource PathsFully 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/list or recommender.bigqueryPartitionClusterInsights.get/list on 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 NameData TypePhysical UnitDescription
additional_detailsRECORDStructJSON details and observation period (observation_period_seconds).
associated_recommendation_idsARRAY<STRING>IDsFull recommendation names/IDs associated with this insight.
categorySTRINGEnum'COST', 'PERFORMANCE', 'SECURITY'.
descriptionSTRINGTextDescription of observed performance signal.
insight_idSTRINGBase64 IDUnique insight identifier.
insight_typeSTRINGStringInsight type (e.g. 'google.bigquery.table.StatsInsight').
last_updated_timeTIMESTAMPUTC TimestampGeneration timestamp.
project_idSTRINGProject IDProject ID.
project_numberINT64Numeric IDProject number.
severitySTRINGEnum'LOW', 'MEDIUM', 'HIGH', 'CRITICAL'.
stateSTRINGEnum'ACTIVE', 'ACCEPTED', 'DISMISSED'.
subtypeSTRINGStringSubtype classification ('TABLE_STATS').
target_resourcesARRAY<STRING>Resource PathsTargeted 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.get on 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 NameData TypePhysical UnitDescription
project_numberINT64Numeric IDProject number.
project_idSTRINGProject IDProject identifier.
option_nameSTRINGOption NameOption identifier (e.g. 'default_time_travel_hours', 'default_query_job_timeout_ms').
option_descriptionSTRINGTextDescription of the option's behavior.
option_typeSTRINGSQL TypeGoogleSQL data type.
option_valueSTRINGValue StringConfigured 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.get on 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 NameData TypePhysical UnitDescription
project_numberINT64Numeric IDProject number.
project_idSTRINGProject IDProject identifier.
option_nameSTRINGOption NameOption identifier.
option_valueSTRINGValue StringEffective option value.
option_set_levelSTRINGEnumDefinition level: 'DEFAULT', 'ORGANIZATION', 'FOLDER', 'PROJECT', 'USER'.
option_set_on_idSTRINGResource IDGCP 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.get on the organization.

  • Predefined Roles: BigQuery Admin (roles/bigquery.admin) on the organization resource.

<!-- mdformat off -->

Column NameData TypePhysical UnitDescription
option_nameSTRINGOption NameOrganization setting name.
option_descriptionSTRINGTextOption description.
option_typeSTRINGSQL TypeOption data type.
option_valueSTRINGValue StringConfigured 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.get on the organization.

  • Predefined Roles: BigQuery Admin (roles/bigquery.admin) on the organization resource.

<!-- mdformat off -->

Column NameData TypePhysical UnitDescription
project_idSTRINGProject IDProject where change originated.
update_timeTIMESTAMPUTC TimestampTimestamp of option change.
usernameSTRINGUser IdentityIdentity of administrator who committed change.
updated_optionsJSONJSON StructJSON 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
Google
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 or Google.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download bigquery-observability.zip