Shopify CSVのMetafield列を触る前に決めること

Shopifyの商品CSVでMetafield列を一括編集する前に、まず確認すべきことがあります。namespaceとkeyの対応、データ型の一致、そして空欄が「値の削除」なのか「変更しない」なのかの違いです。これらを押さえずにCSVをアップロードすると、意図しないデータ消失や型エラーの原因になります。

Metafield列の構造を知る

Shopify商品CSVでは、Metafieldは列名（ヘッダー）で識別されます。列名のフォーマットは次のようになります。

metafield.namespace.key

たとえば custom.brand_name という列があれば、custom がnamespace、brand_name がkeyです。この構造によって、どのMetafield定義に値を書き込むかが決まります。

namespaceとは

namespaceはMetafieldをグループ化する識別子です。標準機能で作成したカスタム項目は custom というnamespaceに属することが多いです。アプリが独自に作成したMetafieldは、アプリごとに異なるnamespace（app.bundler や my_fields など）を使います。

keyとは

keyはnamespace内での項目名です。たとえば custom.warranty_months なら、warranty_months がkeyで、「保証月数」を表すMetafieldへの書き込みを意味します。

データ型とCSV入力形式の対応表

Metafieldには型（type）があり、CSVに入力する値もその型に合わせる必要があります。代表的な型とCSVでの入力例をまとめました。

型（type）	意味	CSV入力例	注意点
single_line_text_field	1行テキスト	夏季限定	改行を含めない
multi_line_text_field	複数行テキスト	素材: 綿100%<br>产地: 日本	引用符で囲む
number_integer	整数	12	小数を入れない
number_decimal	小数	3.5	小数点はピリオド
boolean	真偽値	true / false	空欄は不可
url	URL	https://example.com	http/httpsで始める
color	カラーコード	#FF5500	16進数6桁
date	日付	2026-06-01	ISO 8601形式
product_reference	商品参照	gid://shopify/Product/12345	GraphQL IDが必要

CSV上のMetafield列と管理画面の定義の違い

ここを混同しやすいので整理します。

• 管理画面のMetafield定義: 「設定 → カスタムデータ → 商品」で定義するnamespace、key、型のセット。これが存在しないと、CSVに列を追加しても値は保存されません。
• CSVのMetafield列: ヘッダー行に metafield.namespace.key 形式で列を追加し、その下に値を書き込む仕組み。

つまり、CSVでMetafieldを編集する前提として、管理画面側に同名の定義が存在する必要があります。定義がない状態でCSVに列を追加しても、Shopifyはその値をどこに保存してよいか分かりません。

空欄の意味——削除か、変更なしか

CSVのMetafield列を空欄にした場合、Shopifyの挙動は次のようになります。

• 列自体が存在しない: そのMetafieldは変更されず、既存の値が保持されます。
• 列が存在し、値が空欄: そのMetafieldの値が削除（クリア）されます。

この違いは非常に重要です。「変更したくない項目」の列までCSVに含めて空欄にすると、意図せず値が消えることがあります。変更対象のMetafield列だけをCSVに含めるか、変更しない項目は現在の値をそのまま記載するか、方針を決めておきましょう。

CSV編集前に確認すべきチェックリスト

実際にCSVを開く前に、次の項目を確認します。

確認項目	確認方法
編集対象のnamespaceとkey	管理画面「設定 → カスタムデータ → 商品」で一覧確認
各Metafieldの型	定義画面の「タイプ」欄
現在の値	商品編集画面の下部「Metafield」セクション、または1件だけCSV書き出し
空欄にする意図があるか	値のクリアが必要な商品と不要な商品を仕分け
CSVに含めるMetafield列の範囲	変更しない項目の列を含めない方針にする
バックアップの有無	編集前に現在のCSVを書き出して保存

自動で確認できること vs 人間が判断すること

CSV編集の品質を保つには、機械的にチェックできる部分と人間が判断する部分を分けておくと効率的です。

自動チェックで確認できること

• 列名が metafield.namespace.key の形式に従っているか
• namespaceとkeyが管理画面の定義に存在するか
• 値が定義された型と一致しているか（数値列に文字がないか、booleanが true/false かなど）
• 必須項目が空欄になっていないか
• 文字数上限を超えていないか

これらはスプレッドシートのデータバリデーションや、スクリプトで事前に検証できます。

人間が判断すべきこと

• そのMetafield項目の本来の目的（たとえば「ブランド名」欄にカテゴリ名を入れていないか）
• 空欄にしてよいか、それとも誤入力が疑われるか
• 値の統一表記のルール（「有」「無」か「true」「false」か、「あり」「なし」か）
• 複数担当者間で入力基準が揃っているか

型ミスマッチが起きたときの挙動

CSVで型と合わない値を入力した場合、Shopify側では次のような扱いになります。

• 数値型に文字を入れた: インポート時にエラーとなり、その行のMetafield値は更新されません。
• boolean型に true/false 以外を入れた: 同様にエラー扱いで更新がスキップされます。
• URL型に不正な文字列を入れた: 一部は保存されるものの、管理画面で表示エラーになることがあります。

エラーがあった行はインポート結果画面で確認できますが、一部だけ更新されて一部がスキップされる「部分成功」の状態になるため、事前の型確認が重要です。

実務での進め方——3ステップ

ステップ1: 現状を書き出して確認

管理画面から商品CSVを書き出し、対象のMetafield列の現在値を確認します。このとき、列名の namespace.key が定義と一致しているかも併せて確認します。

ステップ2: 編集方針を決める

次の方針を決めます。

1. 変更するMetafield列だけをCSVに残す（空欄による誤削除を防ぐ）
2. 型のバリデーションルールをスプレッドシートに設定する
3. サンプル5〜10行でテストインポートして挙動を確認する

ステップ3: 本番CSVをインポート

テストで問題なければ、全量のCSVをインポートします。インポート後、結果画面でエラーや警告がないか確認し、必要に応じて商品詳細画面も開いて値が反映されているか目視で確認します。

---

まとめ

Shopify商品CSVのMetafield列を編集する前に確認すべきポイントをまとめます。

• 列名の metafield.namespace.key 形式を理解し、管理画面の定義と一致させる
• データ型（single_line_text_field、number_integer、boolean など）に合った値を入力する
• 空欄は「値の削除」を意味するため、変更しない項目の列はCSVに含めない
• CSVのMetafield列は、管理画面に定義が存在することが前提
• 自動チェック（形式・型）と人間の判断（目的・表記揺れ）を分けて品質を保つ

相談時に用意するとよい情報

Metafieldの一括編集について相談する際は、次の情報があると話が進めやすくなります。

1. 編集したいMetafieldのnamespaceとkey（管理画面の定義名）
2. 現在の値のサンプル（数件で構いません）
3. 変更後の値のイメージ（表記ルールや単位など）
4. 対象商品の件数
5. 使用しているCSV編集ツール（Excel、Googleスプレッドシート、その他）

機密CSVやスクリーンショットの送付は不要です。上記のテキスト情報だけで対応可能です。

参考にした公式情報

• Shopify Help Center: Product details