# 重複レコードマージ 詳細マニュアル | 設定リファレンス・トラブルシューティング - KINTAUROS

> kintoneプラグイン「重複レコードマージ」の詳細マニュアル。全設定項目のリファレンス(意味・制約値)、動作条件・制限事項、エラーコード別のトラブルシューティングを掲載。対象バージョン: v1.0.1。

元ページ: https://kintauros.com/plugins/record-merge/manual/

重複レコードマージは、アプリ内の重複したレコードを検索し、残す値をフィールドごとに選んで1件に統合するプラグインです。統合されるレコードを参照している他アプリ・自アプリのルックアップは、条件を満たすものを一括で残すレコードへ付け替えます。実行前のバックアップJSON自動ダウンロードと「付け替えに失敗したら削除しない」安全設計で、顧客マスタ・商品マスタの整理を安心して進められます。このマニュアルでは、設定項目のリファレンスと、動作仕様・制限事項・トラブルシューティングを説明します。

機能紹介・画面イメージ・導入手順は[プラグイン紹介ページ](https://kintauros.com/plugins/record-merge/)を、ダウンロードは[ダウンロードページ](https://kintauros.com/download/)をご覧ください。このマニュアルは[Markdown版](index.md)でも提供しており、全プラグインのメタ情報と設定スキーマは機械可読な[catalog.json](https://kintauros.com/catalog.json)から取得できます。

## 基本情報

- **プラグインID**: record-merge

- **対象バージョン**: v1.0.1(配布中の最新版)

- **カテゴリ**: 入力効率化

- **説明**: 重複したレコードを、残す値をフィールドごとに選んで1件に統合します。他アプリ・自アプリのルックアップ参照も一括で付け替え。

## 動作条件

- **対応環境**: kintone スタンダードコース(デスクトップ版UI)。最新版の Chrome / Edge / Safari / Firefox に対応。モバイルアプリでは動作しません。

- **動作画面**: レコード一覧画面(「重複レコードマージ」ボタン)とレコード詳細画面(「重複チェック」ボタン)。追加・編集画面には介入しません。

- **必要な権限**: 残すレコードの編集権限と、統合されるレコードの削除権限(削除する場合)。ルックアップ参照の付け替えには参照元アプリのレコード編集権限が必要です。参照元スキャンのベースライン保存は、全アプリを閲覧できる管理者での実行を推奨します。

- **設定**: すべて任意です。設定なしでもマージ機能をそのまま使えます。

## 設定項目リファレンス

プラグイン設定の全項目です。「項目」は設定データ(エクスポートファイルの config)のキーを表し、[] は配列の要素を意味します。設定画面での入力項目と1対1に対応します。この構造の正式な定義はJSON Schema([catalog.json](https://kintauros.com/catalog.json) の configSchema)として公開しています。

- **項目**: 型 / 必須 / 説明・制約

- **dupFields**: 配列(文字列) / 任意 / 重複判定の既定フィールド / 一覧画面の「重複を検索」で最初に選択されるフィールドコード(実行時に変更可能)。 / 3件以内 / 1文字以上

- **detailButton**: オブジェクト / 任意 / 詳細画面の「重複チェック」ボタンの位置 / 未設定または position が header ならレコード詳細画面のヘッダーメニューに表示する。space を指定すると、フォームに配置したスペース(要素ID)に表示する。指定したスペースが見つからない場合はヘッダーに表示する。

- **detailButton.position**: 文字列 / 必須 / 表示位置 / 値: header | space

- **detailButton.spaceId**: 文字列 / 任意 / スペースの要素ID(position が space のとき必須) / 1文字以上

- **allowedEntities**: 配列 / 任意 / マージを利用できるユーザーの制限 / 空または未設定なら全ユーザーが利用可。指定すると、該当するユーザー・所属組織・所属グループにのみ一覧/詳細画面のマージボタンが表示される。これは画面上の表示制御であり、kintoneの権限でレコードを編集・削除できるユーザーはプラグインを使わずに手動で同様の操作ができる点に注意。

- **allowedEntities[].type**: 文字列 / 必須 / 種別 / 値: user | organization | group

- **allowedEntities[].code**: 文字列 / 必須 / ユーザー/組織/グループのコード / 1文字以上

- **allowedEntities[].name**: 文字列 / 任意 / 表示名(控え)

- **baseline**: オブジェクト / 任意 / 参照元スキャンのベースライン / 設定画面の「参照元をスキャン」で保存した、このアプリを参照するルックアップの一覧。マージ実行時のフレッシュスキャンで見えないアプリがここにあれば、権限不足の警告を出す。

- **baseline.scannedAt**: 文字列 / 必須 / スキャン日時(ISO 8601)

- **baseline.appCount**: 整数 / 任意 / スキャンしたアプリ数

- **baseline.refs**: 配列 / 必須 / 参照元ルックアップの一覧

- **baseline.refs[].appId**: 文字列 / 必須 / 参照元アプリID

- **baseline.refs[].appName**: 文字列 / 任意 / 参照元アプリ名(表示用の控え)

- **baseline.refs[].fieldCode**: 文字列 / 必須 / ルックアップフィールドコード

- **baseline.refs[].fieldLabel**: 文字列 / 任意 / ルックアップフィールド名(表示用の控え)

- **baseline.refs[].keyField**: 文字列 / 必須 / このアプリ側の参照キーフィールドコード

- **baseline.refs[].table**: 文字列 / 任意 / ルックアップがテーブル内にある場合、そのテーブルのフィールドコード

## 設定のポイント

- dupFields(重複判定の既定フィールド)は、一覧画面の重複検索と詳細画面の候補検索で最初に選択されるフィールドです(最大3件)。実行時に自由に変更できます。選べるのは 文字列(1行)・数値・リンク・日付・ドロップダウン・ラジオボタン・レコード番号 のフィールドです。

- detailButton(詳細画面の「重複チェック」ボタンの位置)は、既定ではレコード詳細画面のヘッダーメニューに表示されます。フォームにスペースフィールドを置き、その要素IDを指定すると、スペースの位置に表示できます。指定したスペースが見つからない場合は自動でヘッダーに表示されます。

- allowedEntities(利用ユーザーの制限)を設定すると、指定したユーザー本人・組織・グループに所属するユーザーにのみマージのボタンが表示されます。未設定なら全ユーザーが利用できます。これは画面上の表示制御であり、kintoneの権限でレコードを編集・削除できるユーザーはプラグインを使わずに手動で同様の操作ができるため、アクセス権の代わりにはなりません。

- baseline(参照元スキャンのベースライン)は、設定画面の「参照元をスキャン」で保存する「このアプリを参照しているルックアップの一覧」です。マージ実行時のスキャンは実行ユーザーが閲覧できるアプリしか調べられないため、全アプリを閲覧できる管理者がベースラインを保存しておくと、実行ユーザーの権限では見えない参照元があるときに警告を表示できます。アプリ構成(ルックアップの追加・削除)を変えたら再スキャンして保存し直してください。

## 動作仕様

- 一覧画面の「重複レコードマージ」ボタン: 判定フィールド(最大3つ)を選んで検索すると、すべての値が一致するレコードを重複グループとして、件数の多い順に一覧表示します(表示は200グループまで)。値の比較は NFKC 正規化・前後空白の除去・英字の小文字化・連続空白の圧縮を行うため、全角/半角や大文字/小文字の表記ゆれも同じ値として扱われます。「値が空のレコードは重複として扱わない」(既定ON)の切替もできます。

- 重複の走査はレコード番号順に最大5万件です。超過するアプリでは「レコード番号の小さい5万件で走査を打ち切った」旨が表示され、その範囲で判定します。

- 詳細画面の「重複チェック」ボタン: 表示中のレコードと統合する候補を、フィールド+検索値(「を含む」/「と一致」)で検索し、チェックして選択します(表示は50件まで)。フィールドを選ぶと表示中レコードの値が検索値に自動セットされます。表示中のレコードは常にマージ対象に含まれます。

- 値の選択: 1回のマージで最大10件を統合できます(超過分はレコード番号の小さい10件が対象になり、残りは再実行で統合)。残すレコードは既定でレコード番号が最小のものが選ばれ、ラジオボタンで変更できます(変更するとフィールドの選択はリセットされます)。比較表には値が異なるフィールドだけが表示され、セルをクリックして採用する値を選びます。値が同じフィールド・自動設定フィールドは折りたたみで確認できます。

- 残すレコードの値で固定されるフィールド: レコード番号・作成者・作成日時・更新者・更新日時・計算・重複禁止(unique)フィールド・ルックアップのコピー先フィールド。関連レコード一覧・カテゴリー・グループ(レイアウト用)・プロセス管理のステータス/作業者は選択の対象外です。

- 影響の確認: マージ実行前に、このアプリを参照しているルックアップを実行のたびにスキャンし、参照元アプリ・フィールド・付け替え件数・自動更新の可否(不可の場合は理由)を一覧表示します。「統合されるレコードを削除する」(既定ON)のチェックを外すと、削除せずに値の統合と参照の付け替えだけを行います。

- 参照の付け替え: 自動更新できるのは、参照キー(このアプリ側のフィールド)が「レコード番号」または「重複禁止」で、残すレコードのキー値が空でなく、付け替え対象が1ルックアップあたり1万件以下の場合です。テーブル内のルックアップは、変更する行のルックアップセルだけを送信して更新します。条件を満たさない参照は理由付きで警告され、マージ後の手動更新が必要です。

- 実行順序: (1)バックアップJSONの自動ダウンロード → (2)残すレコードの更新(失敗したらこの時点で中止。レコードは一切変更されません) → (3)ルックアップ参照の付け替え → (4)統合されるレコードの削除。付け替えに1件でも失敗があると削除は行われず、原因を解消して再実行すると残りから再開できます。

- バックアップJSON: マージ実行の最初に必ずダウンロードされます(ファイル名 record-merge-backup-app{アプリID}-{残すレコードID}.json)。対象レコード全件の全フィールド値の写しで、誤ってマージした場合に手動・API・AIエージェントで再登録する材料になります。添付ファイルの中身は含まれません。

- 添付ファイル・テーブルの引き継ぎ: 残すレコード以外の添付ファイルを採用した場合は、ファイルをダウンロード→再アップロードして新しいファイルとして登録します。テーブルは行ごとコピーし、行内のルックアップは値がある場合コピー先の再取得に任せます。

- 外部通信: レコードの内容が当社(KINTAUROS)のサーバーに送信されることはありません。レコード操作はすべてお使いのkintone環境のAPI内で完結し、外部への通信はライセンス確認(kintoneドメイン名・プラグインID・バージョンのみ)です。利用ユーザー制限の所属判定と設定画面の候補一覧には、kintone(cybozu.com)のUser APIを同一ドメイン内で利用します。

## 制限事項・既知の仕様

- モバイルアプリの画面では動作しません(デスクトップ版UIのみ)。

- 1回のマージで統合できるのは最大10件です。10件を超える重複グループは、レコード番号の小さい10件を対象にし、残りは再実行で統合します。

- 重複の走査はレコード番号順に最大5万件、重複グループの表示は200グループまで、詳細画面の候補検索の表示は50件までです。

- 重複判定・候補検索に使えるフィールドは 文字列(1行)・数値・リンク・日付・ドロップダウン・ラジオボタン・レコード番号 です。

- ルックアップ参照の自動付け替えは、参照キーが「レコード番号」または「重複禁止」のフィールドで、残すレコードのキー値が空でない場合のみです(1ルックアップあたり1万件まで)。条件外の参照は手動更新が必要です。

- 実行ユーザーが閲覧できないアプリ・ゲストスペース内のアプリは、参照元として検出できません(ベースラインを保存していれば、見えない参照元があることを実行時に警告します)。

- プロセス管理のステータス・作業者はマージされません(残すレコードの状態がそのまま残ります)。重複禁止フィールドとルックアップのコピー先は残すレコードの値が維持されます。

- 残すレコード以外から採用した添付ファイルは再アップロードで新しいファイルになります。統合されるレコードのレコードコメント・変更履歴は引き継がれません。

## 設定のインポート / エクスポート

プラグイン設定画面の上部にある「設定のインポート / エクスポート」から、現在の設定をJSONファイルとして書き出し(エクスポート)、別のアプリで読み込み(インポート)できます。検証用アプリから本番アプリへの設定コピーや、バックアップ・復元にご利用ください。

- インポートは取り込む内容の差分を確認してから「設定画面に反映」し、最後に「保存」を押して確定します(反映しただけでは保存されません)。

- 読み込んだファイルはブラウザ内で処理され、KINTAUROSのサーバーには送信されません。

- 別のアプリの設定を取り込んだ場合、このアプリに存在しないフィールドは警告として一覧表示されるので、反映後に該当箇所を選び直してください。

エクスポートファイルは次の形式(封筒形式)です。config の中身が設定本体で、その構造は上の設定項目リファレンスのとおりです。

```
{
  "kintauros": "config/v1",
  "plugin": "<プラグインID>",
  "pluginName": "<プラグイン名>",
  "pluginVersion": "<バージョン>",
  "exportedAt": "<書き出し日時(ISO 8601)>",
  "sourceApp": "<書き出し元アプリID>",
  "config": { ... 設定本体 ... }
}
```

### AIエージェント向け: ブラウザコンソールAPI

各プラグインは共通ランタイム window.KINTAUROS を搭載しており、ブラウザの開発者コンソールから設定の読み取り・検証・保存ができます。設定の保存(save: true)はkintoneの制約上、プラグイン設定画面でのみ成功します。

```
KINTAUROS.config.plugins()                   // このページのKINTAUROSプラグインID一覧
KINTAUROS.config.describeAll()               // 同居プラグインすべての設定サマリ
KINTAUROS.config.of('<プラグインID>').schema()    // 設定のJSON Schema
KINTAUROS.config.of('<プラグインID>').export()    // 現在の設定(封筒つき)
KINTAUROS.config.of('<プラグインID>').validate(x) // 保存せず検証
KINTAUROS.config.of('<プラグインID>').diff(x)     // 現在の設定との差分
await KINTAUROS.config.of('<プラグインID>').import(x, { save: true }) // 検証して保存(設定画面のみ)
```

登録が1件だけのページでは of(...) を省略できます(例: KINTAUROS.config.export())。

## トラブルシューティング

**一覧画面・詳細画面にボタンが表示されない**

アプリにプラグインが追加され「アプリを更新」済みかを確認してください。設定画面で利用ユーザーの制限(allowedEntities)を設定している場合、該当しないユーザーにはボタンが表示されません。また、所属組織・グループの取得(User API)に失敗した場合も安全側に倒してボタンを表示しません(ブラウザのコンソールに警告が出ます)。

**重複しているはずのレコードが検索でヒットしない**

判定フィールドの値がすべて一致したレコードだけが重複グループになります。判定フィールドを減らす、値のゆらぎが大きいフィールド(住所など)を外す、などお試しください。「値が空のレコードは重複として扱わない」が既定でONのため、空同士は重複になりません。また、5万件を超えるアプリではレコード番号の小さい5万件だけが走査されます。

**「自動更新できない参照があります」と警告される**

参照キー(このアプリ側のフィールド)が「レコード番号」でも「重複禁止」でもない場合、参照先を一意に特定できないため自動更新できません(kintoneの仕様上、ルックアップのAPI更新にはこの条件が必要です)。参照キーのフィールドに重複禁止を設定するか、マージ後に参照元アプリで手動更新してください。残すレコードのキー値が空の場合も、参照が空になるのを防ぐため自動更新されません。

**参照の付け替えに失敗し、レコードが削除されなかった**

安全のための動作です。付け替えに1件でも失敗すると、統合されるレコードの削除は行われません。失敗の原因(参照元アプリのレコード編集権限がない、プロセス管理でレコードが編集できない状態、など)を実行ログで確認・解消して、もう一度マージを実行してください。処理済みの部分はスキップされ、残りから再開されます。

**マージを間違えたので元に戻したい**

実行時に自動ダウンロードされたバックアップJSON(record-merge-backup-…json)に、対象レコード全件の値が写しで残っています。削除したレコードはこのファイルを材料に手動・API・AIエージェントで再登録できます(添付ファイルの中身は含まれないため、添付は残っているレコードや手元のファイルから登録し直してください)。レコード番号は再登録で新しくなるため、付け替え済みの参照は必要に応じて修正してください。

**E001: 設定されたフィールドが見つかりません**

設定後に重複判定の既定フィールドが削除・変更された状態です。プラグイン設定画面を開き、現在のフォームに合わせてフィールドを選び直して保存してください。

## エラーコードと診断情報

重複レコードマージを含むKINTAUROSプラグインは、エラー発生時にブラウザのコンソールへ統一形式のログを出力します。人間向けの1行に続けて、機械可読なJSON(code / plugin / version / appId / message / doc)を出力し、doc には該当エラーの解説ページのURLが入ります。

```
[KINTAUROS <プラグインID>@<バージョン>] E001: 設定されたフィールドが見つかりません: ...
{"kintauros":{"code":"E001","plugin":"...","version":"...","appId":"...","message":"...","doc":"https://kintauros.com/docs/errors/E001"}}
```

各エラーコードの意味と対処は[エラーコード一覧](https://kintauros.com/docs/errors/)を参照してください。また、プラグイン設定画面の「サポート用情報をコピー」から、環境・バージョン・ライセンス状態・直近のエラーを含む診断情報をコピーできます(レコードの内容や個人情報は含まれません)。お問い合わせの際はこの情報を添えてください。

## ライセンスについて

- 初回利用時は、プラグイン設定画面の「利用開始」ボタンから60日間の無料トライアルを開始できます(カード登録不要)。

- トライアル・契約の期限が切れるとプラグインの動作は停止し、画面に案内が表示されます。[料金プラン](https://kintauros.com/#pricing)から契約すると同じ設定のまま再開できます。

- ライセンス確認のための外部通信で送信されるのは、kintoneドメイン名・プラグインID・バージョンのみです。レコードの内容や個人情報が外部に送信されることはありません。

- ライセンスサーバーに一時的に接続できない場合も、プラグインは一定期間動作を継続する設計です。

## サポート

解決しない場合は[お問い合わせ](https://kintauros.com/contact/)からご連絡ください。その際、プラグイン設定画面の「サポート用情報をコピー」でコピーした診断情報を添えていただくと、調査がスムーズです。

最終更新: 2026-09-12 / 対象バージョン: v1.0.1