К основному содержанию
скилл CX Codex официальный · Google

bigquery-migration-data-loader — скилл для Claude Code

Скилл bigquery-migration-data-loader для Claude Code загружает подготовленные Parquet-файлы в BigQuery и развёртывает переведённые представления. Запускается при настройке целевых наборов данных и переносе таблиц.

Apache-2.0 ★ 24 522 обновлён 2026-10-23

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add google/skills --skill bigquery-migration-data-loader -a claude-code
Открыть на GitHub

Что делает bigquery-migration-data-loader

Скилл создаёт наборы данных BigQuery, загружает в них подготовленные Parquet-файлы командой bq load и развёртывает представления из результатов перевода BQMS. Он также проверяет количество строк в загруженных таблицах. Схемы таблиц формируются по типам Parquet; типы и параметры из исходного DDL могут отличаться после загрузки.

Для работы нужны Google Cloud CLI с командами gcloud и bq, проект с активным Cloud Billing, доступ к BigQuery и Cloud Storage, а также PyYAML 6.0.2 в виртуальном окружении. Нужны IAM-роли BigQuery Job User и BigQuery Data Editor, а для бакета с файлами — Storage Object Viewer. Расположение набора данных и команд bq должно совпадать с регионом бакета, иначе возможна плата за передачу данных. Перед включением API и установкой пакета скилл запрашивает подтверждение; инструкции Usage Attribution нужно прочитать до вызова gcloud, REST API или MCP-команд.

Какие задачи решает

  • создать целевой набор данных BigQuery для миграции
  • загрузить подготовленные Parquet-файлы в таблицы BigQuery
  • сверить количество строк после загрузки
  • развернуть переведённые представления из результатов BQMS

Примеры запросов агенту

  • Создай набор данных BigQuery для миграции в проекте PROJECT_ID.
  • Загрузи подготовленные Parquet-файлы из gs://BUCKET/EXPORT_PREFIX в таблицы BigQuery.
  • Разверни переведённые представления из результатов BQMS в целевой набор данных.

Как установить bigquery-migration-data-loader

1Через Skills CLI (Vercel)

npx skills add google/skills --skill bigquery-migration-data-loader -a claude-code

2Вручную: положить файлы

~/.claude/skills/bigquery-migration-data-loader/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/bigquery-migration-data-loader/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о bigquery-migration-data-loader

Как установить bigquery-migration-data-loader в Claude Code?

Выполни npx skills add google/skills --skill bigquery-migration-data-loader -a claude-code. Файл скилла находится по пути ~/.claude/skills/bigquery-migration-data-loader/SKILL.md.

Что делает bigquery-migration-data-loader?

Скилл создаёт наборы данных BigQuery, загружает подготовленные Parquet-файлы через bq load, проверяет число строк и развёртывает уже переведённые представления BQMS.

Что нужно для работы bigquery-migration-data-loader?

Нужны Google Cloud CLI с gcloud и bq, проект с активным Cloud Billing, включённые BigQuery API и Cloud Storage API, авторизация Google Cloud и нужные IAM-роли. Также требуются PyYAML 6.0.2 и доступ Storage Object Viewer к бакету с файлами.

Исходный текст

SKILL.md · Apache-2.0
---
name: bigquery-migration-data-loader
metadata:
  version: "1.0.0"
  category: BigDataAndAnalytics
  publisher: google
description: >-
  Provisions BigQuery datasets, ingests staged Parquet files directly into
  native BigQuery tables by using bq load, and deploys already-translated views
  from local or Cloud Storage BigQuery Migration Service (BQMS) translation
  outputs. Use when provisioning target BigQuery datasets for warehouse
  migrations, batch loading staged Parquet files into native BigQuery tables by
  using bq load, auditing loaded table row counts, or deploying
  already-translated BigQuery views into a target dataset. Don't use for
  extracting source database catalog metadata, translating SQL queries, views,
  stored procedures, or DDL schemas to GoogleSQL (use
  bigquery-migration-sql-translator), exporting or unloading source database
  tables (such as Snowflake, Databricks, Teradata, or Oracle) to Parquet on
  Cloud Storage, or running post-migration cross-database data validation.
---

# BigQuery Migration Data Loader

This skill coordinates the automated provisioning of BigQuery datasets, direct
ingestion of staged Parquet files into native BigQuery tables by using the
`bq load` command, and automated view deployment directly from BigQuery
Migration Service (BQMS) translation output directories (local or Cloud
Storage).

## Usage attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you
MUST read and follow the instructions in
[Usage Attribution](references/attribution.md).

## Before you begin

1.  **Google Cloud CLI, project, and location setup**: Install the
    [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) (including
    the `gcloud` and `bq` command-line tools), confirm that your Google Cloud
    project has an active Cloud Billing account attached, and configure the
    target project and default Compute Engine region:

    ```bash
    gcloud config set project PROJECT_ID
    gcloud config set compute/region REGION
    ```

    `gcloud config set compute/region` sets the default Compute Engine region;
    the `bq` CLI does not read `compute/region` and defaults to `US` unless
    `--location` is passed on `bq` commands or set in `~/.bigqueryrc` (or
    configured through a project or organization `default_location`). BigQuery
    is retiring the *multi-region* designation—including `US` and `EU` in the
    single-regions list colocated with `us-central1` and `europe-west4`, with no
    change to existing data residency (see
    [BigQuery locations](https://cloud.google.com/bigquery/docs/locations))—so
    always pass an explicit `--location` on `bq` commands that matches your
    staged Cloud Storage bucket, as described in step 5 (check regional
    service availability at
    [Google Cloud locations](https://cloud.google.com/about/locations)).

2.  **Enable the APIs**: Ask the user before enabling APIs, then enable the
    BigQuery and Cloud Storage APIs (`bigquery.googleapis.com` and
    `storage.googleapis.com`):

    ```bash
    gcloud services enable bigquery.googleapis.com storage.googleapis.com
    ```

3.  **Authentication and required IAM roles**: Authenticate with `gcloud auth
    login` and `gcloud auth application-default login` (or set
    `GOOGLE_APPLICATION_CREDENTIALS` for service account authentication). Verify
    that your identity or service account has the required IAM roles on each
    resource:

    *   Grant **BigQuery Job User** (`roles/bigquery.jobUser`) on the target
        Google Cloud project.
    *   Grant **BigQuery Data Editor** (`roles/bigquery.dataEditor`) on the
        target Google Cloud project (to create new datasets with `bq mk`) or on
        an existing target dataset (to create or overwrite tables and views).
    *   Grant **Storage Object Viewer** (`roles/storage.objectViewer`) on the
        Cloud Storage bucket holding staged Parquet files and translation
        metadata.

4.  **Python environment**: Ask the user for confirmation before installing
    Python packages, then install PyYAML in a virtual environment:

    ```bash
    pip install pyyaml==6.0.2
    ```

5.  **Location, cost, and cleanup**: Use the location of your staged Cloud
    Storage bucket for the dataset and every `bq` command: the bucket's region
    for a regional bucket, or `US` or `EU` for a `US` or `EU` multi-region
    bucket. Default to `us-central1` only when you also choose the bucket
    location. Loading from a bucket in a different location incurs data
    transfer charges (see
    [BigQuery locations](https://cloud.google.com/bigquery/docs/locations)).
    Review
    [Google Cloud pricing](https://cloud.google.com/pricing) before loading
    large datasets or running audit queries. Ask the user for confirmation
    before deleting temporary staged Parquet files
    (`gcloud storage rm -r gs://BUCKET/EXPORT_PREFIX`) or test datasets
    (`bq rm -r -f PROJECT_ID:DATASET_ID`) when no longer needed.

--------------------------------------------------------------------------------

## 1. Loader workflow overview

The following diagram illustrates the four-stage ingestion and view deployment
pipeline:

```mermaid
flowchart TD
    subgraph 1. Inputs
        A1["Translation Output Directory / Cloud Storage URI<br>gs://bucket/translation_output/metadata/"]
        A2["Staged Parquet Files<br>gs://bucket/data_unload/TABLE/*.parquet"]
    end

    subgraph 2. Ingestion Pipeline
        B1["1. Ensure Dataset Exists<br>bq mk --dataset --location=LOCATION DATASET"]
        B2["2. Concurrent Parquet Ingestion<br>bq load --source_format=PARQUET --replace=true<br>Auto-creates native tables"]
        B3["3. Row Count Audit<br>Print BigQuery Row Counts for Comparison"]
        B4["4. Deploy Consumption Views<br>Deploys views directly from consolidated views.sql or relations/"]
    end

    A1 & A2 --> B1 --> B2 --> B3 --> B4
```

--------------------------------------------------------------------------------

## 2. Direct translation output ingestion

> [!TIP] **Migration workflow context**: Before running the loader, translate
> source schemas and views into GoogleSQL by using the
> `bigquery-migration-sql-translator` skill and stage exported source table
> Parquet files in Cloud Storage. After loading tables and deploying views,
> compare row counts and data aggregates against the source database.

The data loader directly consumes BQMS translation output directories (the
`--translation-metadata-dir` flag):

*   **Zero-DDL native ingestion**: Table schemas are inferred and created
    automatically from staged Parquet files during `bq load`. Inferred types
    follow the Parquet types, not the translated DDL: naive source timestamps
    (no time zone) load as `TIMESTAMP` instead of `DATETIME`, and
    `STRING(n)` and `NUMERIC(p, s)` parameters are dropped (see Step 2 in
    Section 3).
*   **Automated object discovery**: Base tables and views are auto-discovered
    directly from the translation output metadata. Pass the BQMS `metadata/`
    directory (or its parent), which contains `config/DATABASE/SCHEMA/*.yaml`
    files whose `sourceName` names each object (table configs also set
    `externalTableName` or `externalTableDdlPath`; the others are views) and
    view DDL in `relations/db_DATABASE/schema_SCHEMA/VIEW.sql` (or a single
    `views.sql`).
*   **Automated view deployment**: Translated views are deployed directly into
    the target dataset with source references rewritten to the target BigQuery
    project and dataset. Plain `CREATE VIEW` statements are deployed as
    `CREATE OR REPLACE VIEW` so that reruns don't fail on existing views.
*   **Flexible Parquet path resolution**: Under the `--parquet-base-uri`
    (`BASE_URI`) flag, the loader automatically checks schema-scoped
    subfolders (`BASE_URI/SCHEMA/TABLE/*.parquet`) first if present and falls
    back to flat table paths (`BASE_URI/TABLE/*.parquet`). For example,
    `gcloud storage cp -r LOCAL_DIR/SCHEMA gs://BUCKET/data_unload/` stages a
    local schema folder of table subfolders under `data_unload/SCHEMA/`.
*   **Single target dataset**: All discovered schemas load into one
    `--dataset` by table or view name. If tables or views from different
    source databases or schemas share a name, the loader stops before creating
    the dataset and lists the conflicting objects; load each schema into its
    own dataset instead.

--------------------------------------------------------------------------------

## 3. CLI execution interface (`bq load`)

### Step 1: Provision the target dataset

Set the shell variables for your environment, and then create the target
dataset if it doesn't already exist:

```bash
PROJECT_ID="PROJECT_ID"
DATASET_ID="DATASET_ID"
LOCATION="LOCATION"
TABLE_NAME="TABLE_NAME"
BUCKET="BUCKET"
PREFIX="data_unload"

bq show --dataset --project_id=${PROJECT_ID} ${DATASET_ID} >/dev/null 2>&1 || \
bq mk --dataset --project_id=${PROJECT_ID} --location=${LOCATION} ${DATASET_ID}
```

Replace the following:

*   `PROJECT_ID`: the target Google Cloud project ID.
*   `DATASET_ID`: the target BigQuery dataset ID.
*   `LOCATION`: the BigQuery location for the dataset and load jobs (for
    example, `us-central1`).
*   `TABLE_NAME`: the name of the table to load.
*   `BUCKET`: the name of the Cloud Storage bucket that holds the staged
    Parquet files.

### Step 2: Ingest Parquet tables (auto-creates native table schema)

Pass `--decimal_target_types=NUMERIC --decimal_target_types=BIGNUMERIC
--decimal_target_types=STRING` so BigQuery selects the smallest compatible type
(`NUMERIC` → `BIGNUMERIC` → `STRING`) based on each Parquet `DECIMAL(p, s)`
column's precision and scale: columns with `p - s <= 29, s <= 9` map to
`NUMERIC`, columns with `p - s <= 38, s <= 38` (such as `DECIMAL(38, 10)`) widen
to `BIGNUMERIC`, and larger `DECIMAL256` precisions or scales fall back to
`STRING`:

```bash
bq load \
    --project_id=${PROJECT_ID} \
    --location=${LOCATION} \
    --source_format=PARQUET \
    --replace=true \
    --decimal_target_types=NUMERIC \
    --decimal_target_types=BIGNUMERIC \
    --decimal_target_types=STRING \
    ${DATASET_ID}.${TABLE_NAME} \
    "gs://${BUCKET}/${PREFIX}/${TABLE_NAME}/*.parquet"
```

The `--replace=true` flag overwrites the destination table, including its
schema, with the schema inferred from the Parquet files. If you pre-created
tables from translated BQMS DDL statements to preserve target types such as
`JSON`, `INTERVAL`, or `RANGE`, either run `TRUNCATE TABLE` and then load with
`--replace=false` (so that reruns stay idempotent and don't duplicate rows), or
keep `--replace=true` and pass an explicit `--schema`. If you use the loader
template with native `JSON` columns, also set
`_WRAP_JSON_QUERY_WITH_PARSE_JSON = False` in the copied script: by default it
wraps `JSON_QUERY()` calls in `SAFE.PARSE_JSON()` for `JSON` source columns that
Parquet loads as `STRING`, which fails on native `JSON` columns.

Parquet `TIMESTAMP` columns always load as BigQuery `TIMESTAMP`, including
naive timestamps (`isAdjustedToUTC=false`, such as source `TIMESTAMP WITHOUT
TIME ZONE` columns) that the translated DDL maps to `DATETIME`; the wall-clock
values are kept and read as UTC. To restore `DATETIME` after loading, rewrite
those columns with `DATETIME(column)`, which converts at UTC by default:

```sql
CREATE OR REPLACE TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME` AS
SELECT * REPLACE (DATETIME(created_at) AS created_at)
FROM `PROJECT_ID.DATASET_ID.TABLE_NAME`;
```

### Step 3: Run a row-count audit

Count the rows in the loaded table so that you can compare the result with the
source table:

```bash
bq query \
    --project_id=${PROJECT_ID} \
    --location=${LOCATION} \
    --use_legacy_sql=false \
    "SELECT '${TABLE_NAME}' AS table_name, count(*) AS row_count FROM \`${PROJECT_ID}\`.\`${DATASET_ID}\`.\`${TABLE_NAME}\`;"
```

--------------------------------------------------------------------------------

## 4. Automated loader asset template (`assets/bq_loader_template.py`)

This skill provides an [automated BigQuery loader template][loader_template]
(`assets/bq_loader_template.py`) for dataset creation, concurrent Parquet
loading, direct view deployment, and table row-count auditing.

### Agent workflow: Copy, conditionally customize, and execute

1.  **Copy the asset template**: Always instruct the user to copy the
    [automated BigQuery loader template][loader_template]
    (`assets/bq_loader_template.py`) from this skill's directory (`SKILL_DIR`)
    into their working directory (`./bq_loader.py`) by using the `cp`
    command—never write, synthesize, or inline a custom Python loader script
    from scratch, and never paste or re-type the template contents into the
    response. The template already handles quote-aware SQL splitting,
    destination name collision checks, chunked row-count audits, and
    multi-pass view retries, which a rewritten script would likely miss.
    `SKILL_DIR` is the directory containing this `SKILL.md`:

    ```bash
    cp SKILL_DIR/assets/bq_loader_template.py ./bq_loader.py
    ```

2.  **Conditionally customize extension points**: Run the copy as-is. Modify it
    only if one of the following applies (prefer editing the marked `#
    CUSTOMIZE:` sections; `# DEFAULT SCAFFOLDING` sections can be kept unchanged
    unless deeper orchestration adjustments are needed):

    *   **Schema overrides and partitioning (`# CUSTOMIZE: Schema Overrides &
        Partitioning`)**: Add custom `bq load` flags (such as
        `--time_partitioning_field`, `--clustering_fields`, or explicit schema
        JSON files) inside `load_parquet_table()`.
    *   **Custom view rewriting (`# CUSTOMIZE: Custom View Rewriting &
        Deployment`)**: Adjust view SQL regular expressions, cross-project
        dataset mapping rules, or retry bounds in `_rewrite_view_sql()` and
        `deploy_views()`. Set `_WRAP_JSON_QUERY_WITH_PARSE_JSON = False` if you
        pre-created tables with native `JSON` columns.
    *   **Connection and CLI wrapper (`# CUSTOMIZE: Connection & CLI
        Wrapper`)**:
        Pass custom `bq` CLI flags (for example, `--default_kms_key` in
        `ensure_dataset()`, or `--destination_kms_key` and `--reservation_id` in
        `load_parquet_table()` and `execute_sql()`).
    *   **Post-load auditing (`# CUSTOMIZE: Post-Load Auditing`)**: Extend
        `audit_row_counts()` with custom data integrity or column-level checksum
        queries.

3.  **Execute the script in your working directory**: Run the copied script
    against a Cloud Storage URI or a local translation output folder:

    ```bash
    # Direct from a Cloud Storage translation_output URI with concurrency:
    python3 ./bq_loader.py \
        --project "PROJECT_ID" \
        --dataset "DATASET_ID" \
        --location "LOCATION" \
        --translation-metadata-dir "gs://BUCKET/translation_output/metadata/" \
        --parquet-base-uri "gs://BUCKET/data_unload/" \
        --concurrency 8

    # Using local translation output folder:
    python3 ./bq_loader.py \
        --project "PROJECT_ID" \
        --dataset "DATASET_ID" \
        --location "LOCATION" \
        --translation-metadata-dir "TRANSLATION_OUTPUT/metadata" \
        --parquet-base-uri "gs://BUCKET/data_unload/" \
        --concurrency 4
    ```

    When a view depends on another view, the first batch and first pass print
    `bq` errors such as `Not found: Table ...` for the dependent view. These
    errors are expected if the run ends with
    `All N views successfully deployed across M passes.`

### Arguments

*   `--project` *(Required)*: Google Cloud project ID.
*   `--dataset` *(Required)*: Target BigQuery dataset name.
*   `--parquet-base-uri` *(Required)*: Base Cloud Storage URI containing table
    Parquet subfolders (`gs://BUCKET/path/`).
*   `--translation-metadata-dir` *(Required)*: Local folder or Cloud Storage URI
    to translation output metadata directory. Auto-discovers tables and views.
*   `--location` *(Optional, Default: `us-central1`)*: Target BigQuery location.
*   `--concurrency` *(Optional, Default: `4`)*: Number of parallel workers for
    concurrent `bq load` operations.

[loader_template]: assets/bq_loader_template.py

© google · Apache-2.0 · google/skills

Похожие скиллы

Все скиллы по теме «Облака: AWS, Azure, GCP» →
bigquery-data-analytics официальный Google LLC Плагин bigquery-data-analytics для работы с BigQuery через естественный язык: запросы к датасетам, аналитика и прогнозы без переключения в консоль GCP. CX Codex ★ 53звёзд репо Google BigQuery bigquery MCP-сервер Google BigQuery подключает агента к BigQuery: он перечисляет наборы и таблицы, читает схемы и выполняет SQL-запросы. CX Codex +1 6 986установок bigquery-mcp SnowLeopard-AI MCP-сервер подключает ИИ-агента к Google BigQuery: он читает схемы таблиц, показывает доступные таблицы и выполняет SQL-запросы. CX Codex +1 ★ 10звёзд репо cwicr-data-loader datadrivenconstruction Скилл cwicr-data-loader для Claude Code загружает базу данных DDC CWICR из Parquet, Excel, CSV и Qdrant. Основа для операций с данными о стоимости строительных работ. CX Codex +1 115установок bigquery-agent-analytics-sdk reason-machines Скилл bigquery-agent-analytics-sdk для разбора телеметрии ИИ-агентов в BigQuery: восстановление трейсов, оценка через LLM-судью, поиск дрейфа поведения. CX Codex +1 773установок google-cloud-data-engineering-hub reason-machines Скилл google-cloud-data-engineering-hub подключает к агенту справочник рабочих проектов по GCP: BigQuery, Dataflow, Beam, Composer, Pub/Sub, Dataproc, Vertex AI. CX Codex +1 1 100установок

Из того же набора203

Весь набор →
cloud-monitoring-alert-configuration Скилл cloud-monitoring-alert-configuration для Claude Code настраивает политики оповещений Cloud Monitoring через Terraform и PromQL. Запускается при создании, проверке, переносе или устранении дубликатов таких политик. CX Codex +1 ★ 24 522звёзд репо cloud-armor-crs-rule-upgrader Скилл cloud-armor-crs-rule-upgrader для Claude Code обновляет правила Google Cloud Armor WAF с OWASP CRS 3.0 или 3.3 до CRS 4.22. Запускается для аудита или перехода на новый набор правил. CX Codex +1 ★ 24 522звёзд репо bigquery-migration-validator Скилл bigquery-migration-validator для Claude Code сравнивает таблицы в BigQuery с исходными данными. Он подключается при настройке или запуске проверки миграции и разборе расхождений. CX Codex +1 ★ 24 522звёзд репо bigquery-migration-metadata-extractor Скилл bigquery-migration-metadata-extractor для Claude Code запускает выгрузку DDL-метаданных и журналов запросов из сторонних хранилищ в BigQuery. Снимает статистику с архивов без экспорта строк таблиц. CX Codex +1 ★ 24 522звёзд репо assured-workloads-basics Скилл assured-workloads-basics для Claude Code создаёт и обслуживает соответствующие требованиям папки Google Cloud Assured Workloads. Он подключается к задачам создания, просмотра, изменения и удаления workload. CX Codex +1 ★ 24 522звёзд репо api-gateway-troubleshooting Скилл api-gateway-troubleshooting для Claude Code диагностирует сбои запросов и развёртывания в Google Cloud API Gateway. Запускается при ошибках 4xx/5xx, тайм-аутах, сбое CORS preflight или ошибках команд создания и обновления шлюза. CX Codex +1 ★ 24 522звёзд репо api-gateway-openapi-spec-authoring Скилл api-gateway-openapi-spec-authoring для Claude Code пишет и исправляет спецификации OpenAPI для Google Cloud API Gateway. Он включается при миграции с OpenAPI 2.0 или разборе ошибок создания конфигурации API. CX Codex +1 ★ 24 522звёзд репо agent-platform-autorater-customization Скилл agent-platform-autorater-customization для Claude Code настраивает метрики оценки ИИ-агента по реальным траекториям и человеческим оценкам. Превращает сбои агента в критерии и рубрики для проверки. CX Codex +1 ★ 24 522звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой