cli-kintoneのCSV更新でテーブル行が消える・空欄にならないときの確認順

Q: 列をヘッダーごと省くこととセルを空文字にすることは同じですか？

異なります。--fields未指定かつ一致する行IDがある場合、列省略は既存値を保持し、セルの空文字は値を空にクリアします（テーブル取り込み仕様）。半角スペースとも区別されます。

2026 10/25

2026年10月7日 2026年10月25日

cli-kintoneのCSV更新でテーブル行が消える・空欄にならないときの確認順

著者: Walkers編集部公開: 2026年10月7日最終更新: 2026年10月25日

cli-kintoneでテーブルを含むレコードを更新する際に既存行が消えたり空欄に更新されなかったりする場合、親レコードの更新キー一致を前提に、明細行ID・列省略・空文字の扱いを区別することが確認の基本です。本稿は2026年10月7日時点の一次資料に基づき設計の確認項目を整理したものであり、製品実機での動作検証は実施していません。

CSVを再実行する前に実行ファイルと版を確認する

予期しないテーブル更新結果となった際、CSVデータ自体の記述を見直す前に、実際に呼び出されているcli-kintoneのバイナリパスとバージョンを確認する必要があります。特に自動化スクリプトやバッチ処理では、作業端末の環境変数（PATH）で解決される版と、スクリプト内で直接指定された絶対パスの版が食い違っている状況が起こり得ます。

importとexportの呼出パスとバージョンを記録する

コマンド名だけで実行している場合、シェルやタスクスケジューラの実行ユーザーごとに異なるバージョンのバイナリが呼び出されることがあります。エクスポートして手元で確認した環境のバージョンと、インポートを実行したスクリプト側のバージョンが異なると、同一のCSVであっても処理結果が変わる要因になります。

cybozu developer networkの過去相談（2025年3月のコミュニティ投稿）では、インポート用のバッチファイルが意図せず上位ディレクトリにあったv1.7.0を呼び出していたため空文字更新が無視され、検証端末で確認していたv1.14.0に実行パスを修正して解決した事例が記録されています。トラブル発生時は単に環境変数を調べるだけでなく、importとexportのそれぞれで実際に呼び出されているバイナリの絶対パスに対して--versionを実行し、実行パスとバージョンを個別に対応づけて記録することが不可欠です。

空文字の仕様変更履歴と実行環境を切り分ける

cli-kintoneにおけるテーブル内フィールドの空文字更新は、過去のリリースで仕様変更が行われています。2023年12月リリースのv1.10.7およびPull Request #630において、テーブル内の空文字セルを空として更新対象に含める破壊的変更（BREAKING CHANGES）が適用されました。

この変更以前の版（v1.10.7未満）では、テーブル内フィールドが空文字のセルは更新要求に含まれず、kintone側の既存値が保持される仕様でした。「セルを空にして取り込んだのに既存値が消去されない」という事象に直面した場合、現行仕様を疑う前に、実行中のバイナリが2023年12月以前の古い版でないかを切り分ける必要があります。

親レコード一致を前提としたテーブル更新の仕様

cli-kintoneのCSVインポートでテーブルを更新する場合、レコード単位の更新とテーブル明細行の更新という2段階の判定条件を正確に把握しておく必要があります。

2段階の更新判定：–update-keyと行ID（Row ID）

公式のUPSERT（アップサート：一致するキーがあれば更新し、なければ新規追加する処理）仕様によると、--update-keyで指定したキー値が一致した場合に既存の親レコードが更新対象となります。キーが一致しない場合は新規レコードの作成（INSERT）として処理されます。

テーブルの更新判定は、この親レコードの更新キーが一致している状態においてのみ成立します。親レコードが特定された上で、cli-kintoneがCSVを解釈し、最終的にkintone REST APIのレコード更新要求を生成します。親レコードの更新キーと、明細行を識別する行ID（Row ID）は別個の階層で評価されます。こうしたAPI更新を伴う外部連携は、kintoneの限界はどこかでも扱われているように運用の制約に突き当たりやすい代表例です。

行単位の省略（削除）と列単位の省略（値保持）の違い

cli-kintoneのテーブル取り込み仕様およびREST API仕様において、最も誤解が生じやすいのが「行の省略」と「列の省略」の扱いです。

更新対象の親レコード内にテーブルが含まれている場合、CSVに記載しなかった既存の行IDは削除されます。一方で--fields未指定時、CSVヘッダーに含めなかったテーブル内列は更新対象外となり既存値が保持されます。ただし、列ヘッダーが存在する状態でセルの値を空文字（長さ0の文字列）にした場合は、そのフィールドの値を空として更新要求に含めます。更新要求に含まれることと実際の更新成功は別であり、必須設定やフィールド型の制約などによって空値を受け付けない場合はAPI側でエラーになります（更新成功の可否は実環境で確認が必要）。半角スペースなどの空白文字は空文字とは異なり、文字データとして扱われます。

以下の表は、v1.10.7以降・--fields未指定・親レコードの更新キー一致という共通前提における、CSV入力パターンと公式仕様の対応です。

入力パターン	行IDの指定	CSV内の行・列の状態	公式仕様における判定・挙動
既存行の更新	既存の行IDと一致	行が存在し値が入力されている	指定行が新しい値で更新される
既存行の削除	CSVに記載なし	更新対象テーブルの行を除外	CSVに含まれない既存行は削除される
新規行の追加	空欄（指定なし）	テーブル内のいずれかの列に値あり	対象テーブルに新しい行として追加される
空行の無視	空欄（指定なし）	テーブル内のすべての列が空欄	取り込み対象から除外され行は追加されない
行IDあり空行	既存の行IDと一致	ヘッダーにある全テーブル列が空文字	ヘッダー各列を空とする更新要求が送信される（必須やフィールド型等の制約を満たし更新が成功するかは実環境で確認）
列ヘッダー省略	既存の行IDと一致	テーブル内の一部列がCSVヘッダーに非存在	ヘッダーから除外された列の既存値は保持される
セル空文字指定	既存の行IDと一致	列は存在するがセルの値が空文字	該当セルの値が空文字に更新される

業務フローの改善や自動化の設計を可視化する AI業務診断を利用できます。

3行中1行を変更するCSVの設計とエラー条件

親キーが一致し対象テーブルを更新する条件下で、変更したい行だけをCSVに記載して取り込むと、記載のない既存行は意図せず削除されます。編集部が作成した架空の3明細例をもとに、保持とエラーの条件を整理します。

変更しない行も行ID付きで全行残す設計

親レコード（更新キー「A001」）に、行ID「101」「102」「103」という3つの明細行が存在する状況を想定します。このうち行ID「102」の数量だけを変更したい場合を考えます。

誤って行ID「102」の1行だけをCSVに記載して更新を実行すると、cli-kintoneは親レコード内の対象テーブルにおいて「102のみが存在し、101と103は除外された」と解釈し、101と103をkintone上から削除します。既存の3行を維持しつつ102だけを更新するには、変更のない「101」と「103」の行もCSVに含め、全3行構成で取り込む必要があります。

ここで重要な注意点として、CSVに含めた列については、変更しない101・103の行であってもセルの値を元のまま記載しておく必要があります。行IDだけを残してセルの値を空にしてしまうと、空文字更新と判定されて値が消去されます。また、エクスポートしてからCSVを取り込むまでの間に他ユーザーが101や103を更新していた場合、古いCSVの値で上書きしてしまうリスクがあるため、取り込み直前のデータ状態を確認した上で実行することが推奨されます。

–fieldsで対象テーブル（例: Table）のフィールドコードを指定した場合のエラー条件

コマンド実行時に--fieldsオプションで特定のフィールドを明示する場合、テーブルの扱いには強い制約があります。対象フィールド指定の仕様によると、--fieldsに対象テーブルのフィールドコード（例: Table）を指定した場合、そのテーブルに属するすべての内部フィールドが更新対象となります。テーブル内部の特定の列だけを個別に対象として指定することはできません。

公式の対象フィールド指定の仕様およびテーブル取り込み仕様によると、--fieldsに対象テーブル（例: Table）を指定している場合、CSV側のヘッダーにテーブル内部の列が不足しているとエラー（Error: The specified field "<missing_field>" does not exist on the CSV）が発生します。また、明細行の行IDが空文字の行が含まれている場合もエラー（Error: The specified field "Table" does not exist on the CSV）となります。列省略による既存値保持は、--fieldsを指定していない実行環境でのみ有効な動作です。

検証用データでの確認手順と試験票案

本番運用のデータを更新する前に、テスト用アプリ環境で構造の比較検証を行う手順を設計します。

レコード区切りマーカーとテーブル外の値

公式のCSV形式解説によると、cli-kintoneのCSVではレコードの先頭行にアスタリスク記号（*）のマーカーが配置されます。レコード全体の基本情報や親更新キーは、このマーカーがある先頭行で処理されます。

同一レコードに属する2行目以降のテーブル明細行において、テーブル外の通常フィールドに値が記載されていた場合、それらの値はエラーになるのではなく単に無視されます。2行目以降のテーブル外フィールドを空欄にしておくことは必須条件ではありませんが、更新対象の値を明確化しCSVの読み違いを防ぐ観点から、先頭行のみに親情報を配置する形式が推奨されます。

値・行数・行順・行IDの再取得比較

テーブル更新の検証では、管理画面の見た目だけでなく、エクスポートコマンドを用いて更新後のデータを再取得し、以下の4要素を更新前と比較します。

各フィールドの値が意図通り更新またはクリアされているか
テーブルの総行数が想定と一致しているか
明細行の並び順が崩れていないか
既存行の行ID（Row ID）が更新前と同一のまま維持されているか

一度kintone上から削除された行は、後から同じ値を再取り込みしても新しい行IDが採番されます。元のCSVデータを再度投入しても削除前の行IDまで完全に復元することは保証されないため、行IDをもとに外部連携を行っている場合は細心の注意が必要です。行IDの保持を含む高度な外部連携要件が重なる場合は、kintoneで足りる会社、AI駆動開発が向く会社を念頭に現行ツールの適用可否を検討します。

以下の表は、更新挙動を検証するための試験票案です。実機による測定結果ではなく、各環境において記録すべき確認項目と期待値の設計例を示しています。

試験項目	更新キー・対象行列	呼出パス・オプション	期待値・確認の観点
呼出環境の確認	レコード・テーブル共通	import／exportの実行パス	両方の呼出パスとバージョンが明確に記録されていること
1行のみの更新	親キー一致・全3行維持（1行変更）	–fieldsなし	変更行のみ値が変わり、他2行の値と行IDが維持されること
明細行の削除確認	親キー一致・全3行中1行除外	–fieldsなし	CSVから除外した1行のみが削除され、合計2行になること
列省略の値保持	親キー一致・全3行維持・1列除外	–fieldsなし	ヘッダーから除外された列の既存値が全行で保持されること
セル空文字更新	親キー一致・全3行維持・1セル空文字	–fieldsなし	該当セルの値のみが空にクリアされ、行IDは維持されること
内部列不足エラー	親キー一致・全3行維持・1列除外	–fieldsでテーブルのフィールドコード（Table）指定	テーブル内部列不足のエラーが出力され中断すること（他レコード等の更新範囲を再取得して確認）
空行IDのエラー	親キー一致・新規1行追加（行ID空）	–fieldsでテーブルのフィールドコード（Table）指定	行ID空のエラーが出力され中断すること（エラー発生時の反映・未反映範囲を再取得して確認）

※cli-kintoneが取り込み前に事前検証を行う範囲や、複数リクエストに分割された際の中断挙動（すでに送信されたリクエストのロールバック有無等）は公式ドキュメント上で一律の原子性が保証されているわけではありません。エラー発生時は、対象レコードだけでなく同一CSVに含まれる他レコードも含め、エクスポート等で実際の反映状況を必ず再確認してください。

データ連携や業務プロセスの課題を可視化する AI業務診断を利用できます。