crm-data-quality

まず bulk-operations/SKILL.md を読んでください — JSONL のパイピング、バッチ読み取り、ページネーション、および dry-run/digest/confirm のゲートは、以下のすべてのコマンドに適用されます。

プロパティの検出

プロパティ名を推測しないでください。一覧表示してください:

hubspot properties list --type contacts --format table
hubspot properties list --type contacts | jq -c 'select(.type=="enumeration") | {name, label}'

--type companies、deals、または任意のカスタムタイプ (hubspot objects types) についても同様です。

1. 不完全なレコードを検索する

!name = NOT_HAS_PROPERTY (欠落または空)。裸の name = HAS_PROPERTY。1つの --filter 内では AND で連結します。複数の --filter フラグは OR で結合されます。

hubspot objects search --type contacts --filter "!email" --properties firstname,lastname,company
hubspot objects search --type contacts --filter "!phone AND !mobilephone" --properties email
hubspot objects search --type contacts --filter "!hubspot_owner_id" --properties email,lifecyclestage

結果が100件を超える場合は、bulk-operations のページネーションループを使用してください。

2. フィールド値を正規化する

検索 → jq で整形 → update にパイプします。objects update は不可逆であるため、まず --dry-run を実行してください — dry-run → digest → confirm のフローは、100件を超える場合だけでなく、すべての行数で必須です (bulk-operations が最初から最後まで網羅しています)。整形パターン: bulk-operations/resources/json-patterns.md。

# Collapse spellings into one canonical value — 1. preview
hubspot objects search --type contacts --filter "company~acme" \
| jq -c '{id, properties:{company:"Acme Corporation"}}' \
| hubspot objects update --type contacts --dry-run \
| tee /tmp/normalize.preview.jsonl

# 2. lift the digest + confirm (present at every row count)
digest=$(jq -r 'select(.digest != null) | .digest' /tmp/normalize.preview.jsonl)
confirm=$(jq -r 'select(.digest != null) | .target.id' /tmp/normalize.preview.jsonl)   # single: record ID; batch of 2+: row count

# 3. execute — re-pipe the SAME inputs plus --digest/--confirm
hubspot objects search --type contacts --filter "company~acme" \
| jq -c '{id, properties:{company:"Acme Corporation"}}' \
| hubspot objects update --type contacts --digest "$digest" --confirm "$confirm"

# Lowercase emails (read, reshape, write) — 1. preview
hubspot objects search --type contacts --filter "email" --properties email \
| jq -c '{id, properties:{email: (.properties.email | ascii_downcase)}}' \
| hubspot objects update --type contacts --dry-run \
| tee /tmp/lower.preview.jsonl

# 2. lift the digest + confirm, then 3. re-pipe the SAME inputs to execute
digest=$(jq -r 'select(.digest != null) | .digest' /tmp/lower.preview.jsonl)
confirm=$(jq -r 'select(.digest != null) | .target.id' /tmp/lower.preview.jsonl)
hubspot objects search --type contacts --filter "email" --properties email \
| jq -c '{id, properties:{email: (.properties.email | ascii_downcase)}}' \
| hubspot objects update --type contacts --digest "$digest" --confirm "$confirm"

3. hubspot objects merge で重複を排除する

セカンダリはプライマリに統合され、削除されます。不可逆です。 dry-run/digest/confirm のゲートが適用されます。

# Single pair — dry-run first, then execute with the digest + confirm (confirm = the secondary ID for one pair)
hubspot objects merge --type contacts --primary 149 --secondary 425 --dry-run
hubspot objects merge --type contacts --primary 149 --secondary 425 --digest <hash> --confirm 425

一括処理: JSONL {"primary":"...","secondary":"..."} を標準入力にパイプします (--primary/--secondary は省略します)。

ページネーションが必須です。 objects search は1回の呼び出しで最大100行に制限され、jq -s は単一のストリームをメモリに読み込みます — 以下のスニペットを生の search に対して実行すると、ページ境界をまたぐすべての重複を黙って見逃します。まず bulk-operations/SKILL.md のページネーションループで完全なセットを収集し (/tmp/contacts.jsonl に書き込み)、その後ファイルから重複を排除します:

# /tmp/contacts.jsonl produced by the pagination loop (bulk-operations/SKILL.md)
jq -s -c '
    group_by(.properties.email)[]
    | select(length > 1)
    | sort_by(.id | tonumber)
    | .[0].id as $p | .[1:][] | {primary: $p, secondary: .id}
  ' /tmp/contacts.jsonl \
| hubspot objects merge --type contacts --dry-run | tee /tmp/merge-preview.jsonl

プレビュー行から任意のサイズで digest/confirm を取り出します — select(.digest != null)。バッチの場合、confirm はペア数 (.target.id) であり、mutation_kind は100行のしきい値を超える場合のみ BulkData になります (しきい値以下では RecordMutation ですが、いずれの場合も digest は存在します)。同じプロデューサーを --digest/--confirm で再パイプします (bulk-operations を参照)。

4. プロパティを監査する

hubspot properties list (および get、batch-read) は、行ごとに {name, label, type, fieldType, groupName, optionsDisplay} を出力します。Enum オプションの値は properties options-list を介して公開されます — ライブレコードや UI から読み取る必要はありません。

# Count properties per group (HubSpot groups standard fields; custom groups stand out)
hubspot properties list --type contacts | jq -rs 'group_by(.groupName) | map({group: .[0].groupName, count: length}) | .[]'

# All enumeration properties
hubspot properties list --type contacts | jq -c 'select(.type=="enumeration") | {name, label, fieldType}'

# Create a DQ flag property, then set it via the normalize pattern in section 2
hubspot properties create --type contacts --name dq_missing_phone --label "DQ: Missing Phone" --prop-type string --field-type text

Enum オプション — 一覧表示と管理 (properties options-*、v0.11.0)

# List the allowed options on an enumeration property
hubspot properties options-list --type contacts hs_buying_role
# each row: {"value":"EVALUATOR","label":"Evaluator","displayOrder":9,"hidden":false}

# Add / rename / remove an option (options-delete is irreversible — dry-run → digest → confirm, confirm = the option value)
hubspot properties options-create --type contacts hs_buying_role --label "Evaluator" --value EVALUATOR --display-order 9
hubspot properties options-update --type contacts hs_buying_role --value EVALUATOR --label "New Label"
hubspot properties options-delete --type contacts hs_buying_role --value EVALUATOR --dry-run
hubspot properties options-delete --type contacts hs_buying_role --value EVALUATOR --digest <hash> --confirm EVALUATOR

読み取り専用オプションを持つ HubSpot 定義のプロパティは、API が呼び出される前に options-create/update/delete を拒否します。

復旧

マージは不可逆です。マージ後は、hubspot history --since 1h で監査証跡を取得できます。方向が逆の場合は、UI のごみ箱からセカンダリを復元してください。