# ルックアップ簡単検索＆一括追加 詳細マニュアル | 設定リファレンス・トラブルシューティング - KINTAUROS

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

元ページ: https://kintauros.com/plugins/table-lookup-search/manual/

ルックアップ簡単検索＆一括追加(旧称: 検索してテーブル追加)は、参照元アプリのレコードを品番・商品名などの部分一致で検索し、レコード直下のルックアップフィールドへのセット・新規レコードの一括追加・サブテーブルへの行追加を行うプラグインです。このマニュアルでは、設定項目のリファレンスと、動作仕様・制限事項・トラブルシューティングを説明します。

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

## 基本情報

- **プラグインID**: table-lookup-search

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

- **カテゴリ**: ルックアップ

- **説明**: 品番や名称のあいまい検索で、ルックアップへのセット・新規レコードの一括追加・テーブル行の追加を行います。

## 動作条件

- **対応環境**: kintone スタンダードコース(デスクトップ版UI)。最新版の Chrome / Edge / Safari / Firefox に対応。

- **動作画面**: targetMode=field: 利用画面(fieldScreens)に応じて、レコードの登録・編集画面(簡単検索。ボタンは指定したスペース、空欄時はヘッダー)と一覧画面(レコード一括追加。ボタンはヘッダー)。targetMode=table: レコードの登録・編集画面。

- **必要な事前準備**: 参照元アプリと、キー値を保存するルックアップフィールド(table ではサブテーブル内、field / records ではレコード直下)が必要です。

- **必要な権限**: 実行するユーザーに参照元アプリのレコード閲覧権限が必要です。レコード一括追加はこのアプリのレコード追加権限も必要です。

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

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

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

- **sourceAppId**: 文字列 / 必須 / 参照元アプリID / 形式: ^[0-9]+$

- **sourceAppName**: 文字列 / 任意 / 参照元アプリ名 / 表示用の控え。ID が一致していれば名前は自動で最新化される。

- **keyField**: 文字列 / 必須 / キーフィールド / 参照元アプリ側の、行を一意に特定するフィールドコード(または "$id")。追加先のルックアップフィールドに保存される。 / 1文字以上

- **keyFieldType**: 文字列 / 任意 / キーフィールドの型(保存時に自動算出) / クエリ組み立てに使う内部情報。手で編集しない。

- **searchMode**: 文字列 / 任意 / 検索方式 / all = 全レコードを読み込んでからブラウザ内で絞り込み / query = kintone のクエリ(like)で検索。省略時は all。 / 値: all | query

- **searchFields**: 配列(文字列) / 必須 / 検索対象フィールド / 要素: 参照元アプリのフィールドコード。query 方式では like が使える型のみ。 / 1件以上 / 1文字以上

- **displayColumns**: 配列 / 必須 / 検索結果の表示列 / 1件以上

- **displayColumns[].field**: 文字列 / 必須 / 参照元アプリのフィールドコード(または "$id") / 1文字以上

- **displayColumns[].label**: 文字列 / 任意 / 列ヘッダー名。空なら参照元のフィールド名

- **targetMode**: 文字列 / 任意 / 追加先モード / table = サブテーブルの行として追加(省略時の既定) / field = レコード直下のルックアップフィールドが対象(利用画面は fieldScreens で指定)。 / 値: table | field

- **fieldScreens**: 文字列 / 任意 / 利用画面(field モードのみ) / form = レコードの登録・編集画面で1件を選んでルックアップにセット(簡単検索) / list = 一覧画面から選んだ件数分の新規レコードを一括追加(REST API で登録) / both = 両方(省略時の既定)。table モードでは無視される。 / 値: form | list | both

- **excludeExisting**: 真偽値 / 任意 / 登録済みのキーを一括追加から除外する(field モードのみ・省略時 false) / true にすると、このアプリに既に存在するキー値を検索結果で「登録済み」と表示して選択不可にし、追加直前にも再確認して除外する(同じキーのレコードを1件に保つ運用向け)。false(既定)では既存確認を行わず、選択したものをそのまま追加する。

- **targetTable**: 文字列 / 任意 / 追加先テーブル(このアプリ) / targetMode が table のとき必須。field では使わない(空)。 / 対応フィールド型: SUBTABLE

- **lookupField**: 文字列 / 必須 / キー値を保存するフィールド / table: 追加先テーブル内のフィールドコード / field: レコード直下のフィールドコード。ルックアップフィールドを指定すると取得も実行される(一括追加では kintone がコピー先フィールドを自動で埋める)。 / 1文字以上

- **lookupFieldType**: 文字列 / 任意 / キー値保存先フィールドの型(保存時に自動算出) / 一括追加の登録済みキー除外(excludeExisting)で既存レコードを検索するクエリ組み立てに使う内部情報。手で編集しない。

- **sortOrderField**: 文字列 / 任意 / 並び順を登録するテーブル内フィールド / targetMode が table のときのみ有効。追加先テーブル内の数値フィールドのコード。空なら登録しない。

- **spaceId**: 文字列 / 任意 / ボタンを表示するスペースの要素ID / レコード登録・編集画面のボタン位置。空なら table はテーブルの直前、field はヘッダー(フォーム上部)に表示する。一覧画面のボタンは常にヘッダーに表示する。

- **fieldMappings**: 配列 / 任意 / 追加時のフィールド転記

- **fieldMappings[].sourceField**: 文字列 / 必須 / 参照元アプリのフィールドコード(または "$id") / 1文字以上

- **fieldMappings[].targetField**: 文字列 / 必須 / 追加先フィールドコード(table: テーブル内 / field: レコード直下) / 1文字以上

## 設定のポイント

- 追加先は targetMode で選びます。table(既定・サブテーブルの行として追加)/ field(レコード直下のルックアップフィールドが対象)。field では利用画面 fieldScreens を form(登録・編集画面の簡単検索)/ list(一覧画面のレコード一括追加)/ both(両方・既定)から選びます。v1.8 以前の設定(targetMode 未指定)は table として無変更で動作します。

- キーフィールドには、レコードID("$id")など変更されない値の使用を推奨します。マスタ側で品番・名称を変更しても過去の明細との紐付けが壊れません。

- lookupField にルックアップフィールドを指定すると、行追加・簡単検索時にルックアップの取得も自動実行されます。レコード一括追加では kintone がコピー先フィールドを自動で埋めるため、フィールドマッピングはコピー先以外に転記したい場合だけ設定します。

- searchMode は参照元アプリの規模で選びます。all(全件読み込み)は中小規模マスタ向けでインクリメンタルに絞り込め、query(クエリ検索)は大規模マスタ向けで like 検索が使える型のみ検索対象にできます。

- keyFieldType / lookupFieldType / fieldScreens(table モード時)は保存時に自動算出・整理される内部項目です。手で編集しないでください。

## 動作仕様

- 簡単検索(field × 登録・編集画面): ボタンを押すと検索モーダルが開き、部分一致で探した1件を選んで OK を押すと、レコード直下のルックアップフィールドにキー値がセットされ、ルックアップの取得が実行されます。既に値があれば置き換えます。fieldMappings はレコード直下のフィールドへ転記されます。

- レコード一括追加(field × 一覧画面): 一覧ヘッダーのボタンから検索モーダルを開き、複数レコードを選んで「一括追加」を押すと、確認の後に選択件数分の新規レコードを追加します(100件ごとに一括登録)。オプション「登録済みのキーを一括追加から除外する」(excludeExisting・既定OFF)を有効にすると、このアプリに登録済みのキーは「登録済み」と表示され選択できなくなり、追加直前にも再確認して除外されます。追加に失敗したレコード(重複禁止違反など)は1件ずつ登録し直して、失敗したキーと理由を結果画面に表示します。完了後に「閉じて一覧を更新」で一覧を再読み込みします。

- テーブルの行追加(table): 「検索して追加」ボタンを押すと検索モーダルが開き、複数レコードをチェックして一括追加できます。選択した順序でテーブルへ反映され、fieldMappings に従い参照元のフィールド値が追加行へ転記されます。転記対象以外のフィールドはフォーム設定の初期値(初期値・「レコード登録時の日時」など)で初期化されます(v1.10.0。初期値定義の取得に失敗した場合は空値)。sortOrderField を指定すると行順の連番が登録されます。

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

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

- クエリ検索方式の検索対象フィールドは、kintoneのクエリで like が使える型(文字列など)に限られます。

- 追加先テーブル・ルックアップフィールドがフォームから削除されていると実行時にエラーになります。

- レコード一括追加の登録済みキー除外(オプション・既定OFF)で「登録済み」表示にする事前取得は最大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())。

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

**検索ボタンが表示されない**

(1)設定を保存して「アプリを更新」したか、(2)スペースの要素IDを指定している場合はそのスペースがフォームに存在するか、(3)利用画面の設定と開いている画面が合っているか(簡単検索は登録・編集画面、レコード一括追加は一覧画面)を確認してください。

**実行時に「テーブルが見つかりません」「ルックアップフィールドが見つかりません」「フィールドが見つかりません」というエラーが出る**

フォームの変更で追加先テーブルまたはルックアップフィールドが削除・変更されています。設定画面で現在のフォームに合わせて選び直し、保存してアプリを更新してください。

**検索してもレコードがヒットしない**

検索対象フィールドの設定を確認してください。クエリ検索方式では like が使える型のフィールドのみ検索できます。また参照元アプリの閲覧権限がないレコードは表示されません。

**追加した行のルックアップが取得されない**

lookupField にルックアップフィールドを指定しているか、ルックアップのキー(参照元のキーフィールドの値)が参照先アプリに存在するかを確認してください。

**レコード一括追加で「権限がありません」「値が重複しています」と表示される**

実行ユーザーにこのアプリのレコード追加権限があるか確認してください。重複のエラーは、重複禁止のフィールドに同じ値のレコードが既にある場合に出ます。同じキーのレコードを1件に保ちたい場合は、設定の「登録済みのキーを一括追加から除外する」を有効にしてください。

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

ルックアップ簡単検索＆一括追加を含む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-02 / 対象バージョン: v1.10.2