bigquery-migration-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BigQuery Migration Validator

The validation tool compares a source table with its migrated BigQuery table. It runs in two halves:

Client (this machine): Reads the config, queries the source database, and stages a row sample, source aggregates, and run metadata in Cloud Storage. It then starts a BigQuery Migration workflow for each table and exits.
Backend (Google Cloud, asynchronous): Loads the staged sample into BigQuery, compares it with the target table, and writes the results to BigQuery and Cloud Storage.

Results do not exist when the command exits. Wait for the workflow to finish before reading them (Section 4).

该 validation 工具会将源表与其迁移后的 BigQuery 表进行比较。它分为两个阶段运行：

Client（本机）：读取配置、查询源数据库，并将行样本、源端聚合结果和运行元数据暂存到 Cloud Storage。随后为每张表启动 BigQuery Migration workflow 并退出。
Backend（Google Cloud，异步）：将暂存的样本加载到 BigQuery，与目标表进行比较，并将结果写入 BigQuery 和 Cloud Storage。

命令退出时，结果尚不存在。请等待 workflow 完成后，再读取结果（第 4 节）。

Usage attribution

Usage attribution（使用归属说明）

MUST READ: Before executing any

gcloud

, REST API, or MCP command, you MUST read and follow the instructions in Usage Attribution.

必须阅读：在执行任何

gcloud

、REST API 或 MCP command 之前，你必须阅读并遵循 Usage attribution 中的说明。

Before you begin

开始之前

Google Cloud CLI and project: Ensure the [Google Cloud CLI][gcloud_install] is installed, verify that the Google Cloud project has an active Cloud Billing account, and configure the target project (check regional service availability at [Google Cloud locations][cloud_locations] when choosing
```
--location
```
for validation workflows):
bash
```
gcloud config set project PROJECT_ID
```

Enable the APIs (ask the user before enabling APIs): BigQuery (

bigquery.googleapis.com

), BigQuery Migration (

bigquerymigration.googleapis.com

), Cloud Storage (

storage.googleapis.com

), and Secret Manager (

secretmanager.googleapis.com

, when reading source passwords from Secret Manager):

bash

gcloud services enable \
    bigquery.googleapis.com \
    bigquerymigration.googleapis.com \
    storage.googleapis.com
# Only when source passwords come from Secret Manager:
gcloud services enable secretmanager.googleapis.com

Local runtime, authentication, and IAM permissions (ask before installing software):
- Runtime and drivers: Java 11 or later (JRE 11+) first on
```
PATH
```
  , the
```
bqms
```
  gcloud component (installed on first use or with
```
gcloud components install bqms
```
  ), local network access to the source database, and vendor JDBC driver JARs for Teradata (
```
terajdbc4.jar
```
  ), Vertica (
```
vertica-jdbc.jar
```
  ), Impala, and DuckDB in
```
./drivers
```
  or
```
BQMS_DRIVER_DIR
```
  when required (other JDBC drivers download on first use; see connections and drivers).
- Google Cloud credentials and IAM: Authenticate the Google Cloud CLI and Application Default Credentials with
```
gcloud auth login
```
  and
```
gcloud auth application-default login
```
  (or set
```
GOOGLE_APPLICATION_CREDENTIALS
```
  for a service account). The identity needs write access to the staging Cloud Storage bucket (
```
roles/storage.objectAdmin
```
  ), permission to create BigQuery Migration workflows (
```
roles/bigquerymigration.editor
```
  ), and permission to run BigQuery jobs and write validation results in the target project and, if set, the
```
results.projectId
```
  project (
```
roles/bigquery.dataEditor
```
  and
```
roles/bigquery.jobUser
```
  ). With Secret Manager passwords, it also needs
```
roles/secretmanager.secretAccessor
```
  on the secret, or
```
roles/iam.serviceAccountTokenCreator
```
  on the service account named in
```
secretImpersonateServiceAccount
```
  (which then needs the accessor role).
Cost and cleanup: Review Google Cloud Pricing for BigQuery, Cloud Storage, and Secret Manager. Staged samples in Cloud Storage contain source rows. When validation is complete, ask the user before deleting the staged run directory (a
```
gcs_paths
```
entry in
```
run_state.json
```
) and any per-run tables they no longer need (list them as in the results reference, Section 5). Deleting the run directory also deletes the backend reports stored there (
```
results.json
```
,
```
validation_summary.txt
```
,
```
column_details.txt
```
,
```
queries.sql
```
) and
```
sample_metadata.json
```
, so
```
run_history.gcs_uri
```
no longer resolves; say so and offer to copy the reports locally first:
bash
```
gcloud storage cp GCS_RUN_PATH/results.json \
    GCS_RUN_PATH/validation_summary.txt GCS_RUN_PATH/column_details.txt \
    GCS_RUN_PATH/queries.sql LOCAL_DIR/
gcloud storage rm --recursive GCS_RUN_PATH
bq rm -f -t RESULTS_PROJECT:DATASET.TABLE_NAME
```

Google Cloud CLI 和 project：确保已安装 [Google Cloud CLI][gcloud_install]，验证 Google Cloud project 已启用 Cloud Billing account，并配置目标 project（为 validation workflow 选择
```
--location
```
时，请查看 [Google Cloud locations][cloud_locations] 中的区域服务可用性）：
bash
```
gcloud config set project PROJECT_ID
```

启用 API（启用前询问用户）：BigQuery（

bigquery.googleapis.com

）、BigQuery Migration（

bigquerymigration.googleapis.com

）、Cloud Storage（

storage.googleapis.com

），以及 Secret Manager（

secretmanager.googleapis.com

，用于从 Secret Manager 读取源数据库密码）：

bash

gcloud services enable \
    bigquery.googleapis.com \
    bigquerymigration.googleapis.com \
    storage.googleapis.com
# Only when source passwords come from Secret Manager:
gcloud services enable secretmanager.googleapis.com

本地 runtime、身份验证与 IAM permissions（安装软件前询问用户）：
- Runtime 和 drivers：Java 11 或更高版本（JRE 11+）必须首先位于
```
PATH
```
  中；需要
```
bqms
```
  gcloud component（首次使用时安装，或使用
```
gcloud components install bqms
```
  安装）；需要能够访问源数据库的本地网络；根据需要，将各厂商的 JDBC driver JAR 放入
```
./drivers
```
  或
```
BQMS_DRIVER_DIR
```
  ，包括 Teradata（
```
terajdbc4.jar
```
  ）、Vertica（
```
vertica-jdbc.jar
```
  ）、Impala 和 DuckDB（其他 JDBC drivers 会在首次使用时下载；参见 connections and drivers）。
- Google Cloud credentials 和 IAM：使用
```
gcloud auth login
```
  和
```
gcloud auth application-default login
```
  对 Google Cloud CLI 与 Application Default Credentials 进行身份验证，或者为 service account 设置
```
GOOGLE_APPLICATION_CREDENTIALS
```
  。该 identity 需要拥有 staging Cloud Storage bucket 的 write access（
```
roles/storage.objectAdmin
```
  ）、创建 BigQuery Migration workflows 的权限（
```
roles/bigquerymigration.editor
```
  ），以及在目标 project 和已设置的
```
results.projectId
```
  project 中运行 BigQuery jobs 并写入 validation results 的权限（
```
roles/bigquery.dataEditor
```
  和
```
roles/bigquery.jobUser
```
  ）。使用 Secret Manager 密码时，还需要 secret 的
```
roles/secretmanager.secretAccessor
```
  权限，或者拥有
```
secretImpersonateServiceAccount
```
  所指定 service account 的
```
roles/iam.serviceAccountTokenCreator
```
  权限（该 service account 还需拥有 accessor role）。
成本与清理：查看 BigQuery、Cloud Storage 和 Secret Manager 的 Google Cloud Pricing。Cloud Storage 中暂存的样本包含源数据行。Validation 完成后，删除暂存的 run directory（
```
run_state.json
```
中的
```
gcs_paths
```
条目）以及不再需要的每次运行所创建的表之前，必须询问用户；这些表可按照 results reference 第 5 节中的方式列出。删除 run directory 还会删除存储其中的 backend reports（
```
results.json
```
、
```
validation_summary.txt
```
、
```
column_details.txt
```
、
```
queries.sql
```
）和
```
sample_metadata.json
```
，因此
```
run_history.gcs_uri
```
将无法再解析；应明确说明这一点，并主动提出先将 reports 复制到本地：
bash
```
gcloud storage cp GCS_RUN_PATH/results.json \
    GCS_RUN_PATH/validation_summary.txt GCS_RUN_PATH/column_details.txt \
    GCS_RUN_PATH/queries.sql LOCAL_DIR/
gcloud storage rm --recursive GCS_RUN_PATH
bq rm -f -t RESULTS_PROJECT:DATASET.TABLE_NAME
```

1. What gets compared

1. 比较内容

Pillar	`--validation-types`	Compares	Coverage
Schema	`schema`	Column presence, mapping, and data type compatibility (one of 9 compatibility notes)	All columns
Aggregate	`aggregate`	Column statistics per type ( `COUNT` , `SUM` , `AVG` , `MIN` , `MAX` , `SUM_LENGTH` , ...), computed per partition, then rolled up	100% of rows (pushed down)
Data	`data`	Cell-by-cell values joined on comparison keys, with a distance per mismatched cell	Sampled or full rows

With

--validation-types

omitted, all three run. With

--validation-types

set (for example

--validation-types=schema,aggregate

), only the listed types run. Query (code) validation is not available in this tool.

Each pillar catches what the others miss. Aggregates cover every row cheaply but cannot see offsetting errors (one row +5, another -5). Row sampling sees those but only in the sample. Run both for sign-off.

验证维度	`--validation-types`	比较内容	覆盖范围
Schema	`schema`	列是否存在、映射关系及 data type 兼容性（9 条 compatibility notes 之一）	所有列
Aggregate	`aggregate`	按 type 划分的 column statistics（ `COUNT` 、 `SUM` 、 `AVG` 、 `MIN` 、 `MAX` 、 `SUM_LENGTH` 等），先按 partition 计算，再进行汇总	100% 的行（推送到数据源执行）
Data	`data`	基于 comparison keys 关联后逐 cell 比较 values，并为每个 mismatched cell 计算 distance	抽样行或全部行

省略

--validation-types

时，三种类型都会运行。设置

--validation-types

后（例如

--validation-types=schema,aggregate

），仅运行指定的类型。

本工具不支持 Query (code) validation。

每个验证维度都能发现其他维度遗漏的问题。Aggregates 能够低成本覆盖每一行，但无法发现相互抵消的错误（某一行 +5，另一行 -5）。Row sampling 能够发现这类差异，但只覆盖样本。为完成 sign-off，应同时运行两者。

2. Quick start

2. 快速开始

Both validation commands run in the alpha release track through the Google Cloud CLI, which calls the

bqms

component (Java 11+ required). Arguments after

--

are forwarded unchanged to the validation client.

[!IMPORTANT] The commands are in the alpha track. If gcloud reports an invalid choice or unknown command, ask the user before running
gcloud components update
(or
gcloud components install alpha bqms
). If the Google Cloud CLI was installed with a system package manager such as
apt
or
yum
, the component manager is disabled; have the user upgrade
google-cloud-cli
through that package manager instead. If the command is still unavailable, stop and point the user to the CLI reference and the [installation guide][gcloud_install] rather than retrying.

bash

undefined

两个 validation command 都通过 Google Cloud CLI 在 alpha release track 中运行，CLI 会调用

bqms

component（要求 Java 11+）。

--

之后的参数会原样转发给 validation client。

[!IMPORTANT] 这些 command 位于 alpha track。如果 gcloud 报告 invalid choice 或 unknown command，请在运行
gcloud components update
（或
gcloud components install alpha bqms
）之前询问用户。如果 Google Cloud CLI 是通过 apt 或 yum 等 system package manager 安装的，component manager 会处于 disabled 状态；应让用户通过该 package manager 升级
google-cloud-cli
。如果 command 仍不可用，则停止操作，并引导用户查看 CLI reference 和 [installation guide][gcloud_install]，不要继续重试。

bash

undefined

1. Generate per-table configs offline from extractor metadata or BQMS

translation output (writes ./validation_config/).

gcloud alpha bq migration validation configure
--metadata=dwh-migration-oracle-metadata.zip
--target-dataset=warehouse
--output=validation_config

2. Edit validation_config/connections.yaml (check the source dialect;

set the target dataset) and settings.yaml (googleCloudStorage.gcsPath),

then run schema and aggregate checks first.

gcloud alpha bq migration validation run validation_config/
--location=us --validation-types=schema,aggregate

3. Run row-level comparison, optionally on a subset of tables.

gcloud alpha bq migration validation run validation_config/
--location=us --validation-types=data --tables=orders


Then wait for the workflows (Section 4) and investigate (Section 5).

Every answer that runs or recommends `validation run` must tell the user that
the comparison finishes later in a BigQuery Migration workflow, that exit code 0
does not mean the data matched, and how to check the workflow before reading
results. Users who skip this read an empty or stale results dataset as a pass.

gcloud alpha bq migration validation run validation_config/
--location=us --validation-types=data --tables=orders


然后等待 workflows（第 4 节）并调查结果（第 5 节）。

每次运行或建议执行 `validation run` 时，都必须告知用户：comparison 会在稍后的 BigQuery Migration workflow 中完成；exit code 0 并不表示数据匹配；以及在读取结果前应如何检查 workflow。跳过此提示的用户可能会将空白或过期的 results dataset 误认为验证通过。

3. Configure

3. 配置

Settings come from YAML (modular

validation_config/

directory or one

validation-config.yaml

), then CLI flags. The essentials:

```
connections
```
: a
```
source
```
and a BigQuery
```
target
```
. The target needs
```
projectId
```
and
```
dataset
```
; without
```
dataset
```
the run fails, even when every
```
targetTable.name
```
is fully qualified.
```
configure
```
can scaffold the wrong source
```
dialect
```
(for example
```
snowflake
```
for PostgreSQL metadata), so check it and its properties before the first run. Connection names are letters and digits only; a name with
```
_
```
or
```
-
```
fails config validation. If the user asks for such a name, drop the separators (for example
```
sales-db
```
becomes
```
salesdb
```
) and tell them why, because the name also forms the environment variable prefix. Keep secrets out of YAML: use
```
BQMS_VALIDATION_<CONNECTION>_PASSWORD
```
or a Secret Manager reference (see connections and drivers). Never ask the user to type a password into the conversation and never echo one. For commands you run yourself, use a Secret Manager reference (
```
passwordSecret
```
or
```
BQMS_VALIDATION_<CONNECTION>_PASSWORD_SECRET
```
); give plaintext
```
export
```
lines only for the user to run in their own terminal.
```
googleCloudStorage.gcsPath
```
: required staging bucket (
```
gs://bucket/path
```
, no trailing slash). Results artifacts also land here.
Per table:
```
sourceTable
```
and
```
targetTable
```
(each with
```
name
```
and, under
```
sourceTable
```
,
```
comparisonKeys
```
: the columns that uniquely identify a row for the validation join when the table has no primary key — explain that
```
comparisonKeys
```
only control how validation matches rows, so no database primary key or schema change is needed;
```
configure
```
fills them in only when the metadata includes primary keys),
```
columnSettings
```
(exclusions, transforms, tolerances),
```
sampleSize
```
, and
```
partitioning
```
.
```
results.dataset
```
and optional
```
results.projectId
```
: BigQuery dataset and project for results (defaults
```
validation_results
```
and the target connection's project). Query results where these point.

Details: configuration reference.

配置来自 YAML（模块化的

validation_config/

目录或单个

validation-config.yaml

），之后可由 CLI flags 覆盖。主要配置项如下：

```
connections
```
：一个
```
source
```
和一个 BigQuery
```
target
```
。Target 必须包含
```
projectId
```
和
```
dataset
```
；即使每个
```
targetTable.name
```
都是 fully qualified，缺少
```
dataset
```
也会导致运行失败。
```
configure
```
可能会根据 metadata 生成错误的 source
```
dialect
```
（例如，PostgreSQL metadata 却生成
```
snowflake
```
），因此首次运行前应检查 dialect 及其 properties。Connection names 只能包含字母和数字；包含
```
_
```
或
```
-
```
的 name 会导致 config validation 失败。如果用户要求使用这类 name，应去掉分隔符（例如，将
```
sales-db
```
改为
```
salesdb
```
），并说明原因，因为该 name 还会用作 environment variable 的前缀。不要在 YAML 中保留 secrets：应使用
```
BQMS_VALIDATION_<CONNECTION>_PASSWORD
```
或 Secret Manager reference（参见 connections and drivers）。绝不要让用户在对话中输入密码，也绝不要 echo 密码。对于你自行运行的 command，应使用 Secret Manager reference（
```
passwordSecret
```
或
```
BQMS_VALIDATION_<CONNECTION>_PASSWORD_SECRET
```
）；只有明文
```
export
```
命令应提供给用户在自己的 terminal 中运行。
```
googleCloudStorage.gcsPath
```
：必需的 staging bucket（
```
gs://bucket/path
```
，末尾不能带斜杠）。结果 artifacts 也会存放在这里。
每张表：
```
sourceTable
```
和
```
targetTable
```
（两者都包含
```
name
```
；
```
sourceTable
```
下还包含
```
comparisonKeys
```
：当表没有 primary key 时，用于 validation join 并唯一标识一行的 columns——应说明
```
comparisonKeys
```
只控制 validation 如何匹配行，因此无需更改数据库 primary key 或 schema；仅当 metadata 包含 primary keys 时，
```
configure
```
才会填充该字段），以及
```
columnSettings
```
（exclusions、transforms、tolerances）、
```
sampleSize
```
和
```
partitioning
```
。
```
results.dataset
```
和可选的
```
results.projectId
```
：存放结果的 BigQuery dataset 和 project（默认值为
```
validation_results
```
，以及 target connection 所在的 project）。查询结果时，应以这些配置为准。

详细信息：configuration reference。

4. Run and wait

4. 运行并等待

Run
```
gcloud alpha bq migration validation run
```
. Exit code 1 means a config or source-side failure; read the error and fix it. Exit code 0 means the samples were staged (or that usage was printed for a bad forwarded flag; check the output). Mismatches never change the exit code.
Confirm a workflow started. The client prints a workflow name per table and writes
```
run_state.json
```
(run ID, Cloud Storage paths, workflow names, results dataset) to
```
--output-dir
```
(default
```
/tmp/validation_outputs
```
, passed after
```
--
```
). If it instead prints "Could not initiate BigQuery Migration validation workflow", fix the cause it reports (usually permissions or the API not enabled) and re-run, or create the workflow from the console link it prints.
Poll until the workflow finishes:
bash
```
gcloud bq migration-workflows describe WORKFLOW_NAME
```
Or check
```
run_history.status
```
in the results dataset;
```
IN_PROGRESS
```
means the backend is still working.

运行
```
gcloud alpha bq migration validation run
```
。Exit code 1 表示 config 或源端发生 failure；应读取错误并修复。Exit code 0 表示样本已暂存（或因转发的 flag 无效而仅打印了 usage；应检查输出）。Mismatches 不会改变 exit code。
确认 workflow 已启动。Client 会为每张表打印一个 workflow name，并将
```
run_state.json
```
（包含 run ID、Cloud Storage paths、workflow names 和 results dataset）写入
```
--output-dir
```
（默认值为
```
/tmp/validation_outputs
```
，通过
```
--
```
之后传递）。如果输出“Could not initiate BigQuery Migration validation workflow”，请修复其报告的原因（通常是权限不足或 API 未启用）后重新运行，或者通过输出的 console link 创建 workflow。
轮询直至 workflow 完成：
bash
```
gcloud bq migration-workflows describe WORKFLOW_NAME
```
也可以检查 results dataset 中的
```
run_history.status
```
；
```
IN_PROGRESS
```
表示 backend 仍在处理。

5. Investigate results

5. 调查结果

Results are in three places. Pick by question, not by habit:

Surface	Audience	Grain	Use for
BigQuery results dataset	Agents, humans	Run, slice (partition), column, aggregate, row	All investigation; the only source for per-partition and per-row detail
Cloud Storage `results.json`	Agents	One run (whole table)	Quick status of one table without BigQuery access; execution times
`validation_summary.txt` , `column_details.txt`	Humans	One run	Show the user; do not parse
Web UI	Humans	All of the above, visual	Point the user to it if the printed link is a real URL

Investigate by zooming in one level at a time, stopping as soon as the cause is clear:

All tables: Latest run per table with status, row deltas, and mismatch counts. Errors first, then the largest mismatch counts.
One table, by pillar: Schema compatibility, then failed aggregates, then missing rows, then per-column mismatch statistics.
Partitions: Per-slice metrics show whether mismatches are local (one day or range: a failed load) or everywhere (a systematic conversion).
Rows: Group mismatched cells by column and distance, then read a few rows to confirm the pattern.
Fix and re-run narrowly: Pass
```
--tables
```
and
```
-- --where
```
, then compare the new run with the old one.

Then zoom back out: say which tables pass, which have explained differences, and which need a fix in the migration itself. A narrower re-run (some

--validation-types

, or

--where

) becomes the table's latest run without covering the rest; a table passes only when every pillar and the whole table passed.

Queries, field names, and decision rules for each level: investigation workflow. What every status, field, and table means: results reference.

结果存放在三个位置。应根据要解决的问题选择，而不是凭习惯：

位置	使用者	粒度	用途
BigQuery results dataset	Agents、人类	Run、slice（partition）、column、aggregate、row	所有调查；per-partition 和 per-row detail 的唯一来源
Cloud Storage `results.json`	Agents	一次运行（整张表）	无需 BigQuery 访问权限即可快速查看单张表的 status；execution times
`validation_summary.txt` 、 `column_details.txt`	人类	一次运行	向用户展示；不要 parse
Web UI	人类	以上全部内容，以可视化方式呈现	如果打印出的 link 是有效 URL，则引导用户使用

调查时，每次只下钻一层，并在原因明确后立即停止：

所有表：每张表的 latest run，包括 status、row deltas 和 mismatch counts。先查看 errors，再查看 mismatch counts 最多的表。
单张表，按验证维度：先检查 schema compatibility，再检查失败的 aggregates、缺失的 rows，最后检查各列的 mismatch statistics。
Partitions：每个 slice 的 metrics 可显示 mismatches 是局部的（某一天或某个 range：failed load），还是普遍存在（systematic conversion）。
Rows：按 column 和 distance 对 mismatched cells 分组，然后读取少量行以确认模式。
修复并缩小范围重新运行：传入
```
--tables
```
和
```
-- --where
```
，然后将新运行与旧运行进行比较。

随后再回到整体层面：说明哪些表已通过、哪些差异已得到解释，以及哪些表仍需在 migration 本身中修复。范围更窄的 re-run（仅包含某些

--validation-types

，或使用

--where

）会成为该表的 latest run，但不会覆盖其他表；只有每个验证维度及整张表都通过时，该表才算通过。

各层级的 queries、field names 和 decision rules：investigation workflow。每种 status、field 和 table 的含义：results reference。

6. Reference guides

6. 参考指南

Guide	Read when
CLI reference	Installing, running, flags, exit codes, workflow status
Configuration reference	Writing or auditing YAML, keys, transforms, tolerances
Connections and drivers	Credentials, Secret Manager, JDBC drivers, JDBC URLs
Sampling and partitioning	Sample sizes, partitioned runs, wide tables, concurrency
Results reference	Statuses, `results.json` , BigQuery tables and views, distances
Investigation workflow	Step-by-step drill-down queries and decision rules
Dialects and types	Default aggregates, type compatibility, dialect quirks
Troubleshooting	Mismatch signatures and their config fixes, run errors

指南	阅读时机
CLI reference	安装、运行、flags、exit codes、workflow status
Configuration reference	编写或审查 YAML、keys、transforms、tolerances
Connections and drivers	Credentials、Secret Manager、JDBC drivers、JDBC URLs
Sampling and partitioning	Sample sizes、partitioned runs、wide tables、concurrency
Results reference	Statuses、 `results.json` 、BigQuery tables 和 views、distances
Investigation workflow	分步下钻 queries 和 decision rules
Dialects and types	默认 aggregates、type compatibility、dialect quirks
Troubleshooting	Mismatch signatures 及其配置修复方式、运行错误

7. Operating principles

7. 操作原则

Read-only: Validation only runs
```
SELECT
```
on the source and target. Never modify source or target data to make a validation pass.
Mismatches are findings, not failures: A run that finishes with mismatches (
```
COMPLETED_WITH_MISMATCHES
```
) succeeded and found differences. Reserve "failed" for
```
ERROR
```
runs and non-zero exit codes.
Explain before excluding: Do not add
```
exclude
```
, tolerances, or transforms to hide a difference until the row-level evidence shows it is a representation difference (padding, precision, empty string versus NULL) and not lost or wrong data. Say which one it is.
Protect row data: Mismatch tables hold real customer values. Query aggregates and small samples (
```
LIMIT
```
), and do not paste bulk row values into the conversation unless the user asks.
Edit the user's config in place: When the user names a config file, read it, change only what the task needs, and keep everything else as written: table names (including dataset or schema prefixes),
```
comparisonKeys
```
, filters, and settings. Do not normalize or shorten existing names. A changed
```
targetTable.name
```
points the comparison at a different table, and a dropped
```
comparisonKeys
```
changes what counts as a missing row, so either silently changes what is validated. If something existing looks wrong, say so instead of changing it.

只读：Validation 只会在源端和目标端运行
```
SELECT
```
。绝不能为了让 validation 通过而修改源数据或目标数据。
Mismatches 是发现项，而不是失败：带 mismatches 完成的运行（
```
COMPLETED_WITH_MISMATCHES
```
）已成功执行并发现了差异。仅将
```
ERROR
```
运行和非零 exit code 称为“失败”。
排除前先解释：在 row-level evidence 证明差异属于 representation difference（padding、precision、empty string 与 NULL），而不是数据丢失或错误之前，不要添加
```
exclude
```
、tolerances 或 transforms 来隐藏差异。应明确说明差异属于哪一种。
保护行数据：Mismatch tables 中包含真实的 customer values。查询 aggregates 和 small samples（
```
LIMIT
```
）；除非用户明确要求，否则不要在对话中粘贴大量 row values。
就地编辑用户的 config：当用户指定 config file 时，应读取该文件，只修改任务所需的部分，并保持其他内容原样，包括 table names（含 dataset 或 schema prefixes）、
```
comparisonKeys
```
、filters 和 settings。不要规范化或缩短现有 names。修改
```
targetTable.name
```
会使 comparison 指向另一张表，删除
```
comparisonKeys
```
会改变判定缺失行的方式；任何一种操作都会在无提示的情况下改变 validation 范围。如果发现现有内容看起来不正确，应直接指出，而不是擅自修改。