kintoneルックアップ機能の使い方と設計のコツ

kintoneのルックアップでいちばん誤解されているのは、これが「参照」ではなく「コピー」だという点です。取得ボタンを押した瞬間の値が自分のレコードに書き込まれ、そのあとマスタ側を直しても、書き込まれた値は変わりません。

この性質は欠陥ではなく仕様です。請求書に載せた住所が、先方の移転後に勝手に書き換わったら困ります。ただし知らずに使うと、「マスタを直したのに反映されない」という形で必ずつまずきます。

ルックアップ・関連レコード・計算の使い分け

先にここを決めておくと、あとの作り直しが減ります。

「一覧で絞り込みたい／集計したい」ならルックアップ、「開いたときに確認できればよい」なら関連レコード一覧が基本の分け方です。

計算フィールドが他アプリを参照できないのは重要な制約です。「案件アプリで、発注アプリの合計金額を計算する」はできません。ここはグラフ機能かJavaScriptで出します（→kintoneのグラフ・レポート機能）。

設定の手順

Step 1: マスタアプリを先に作る

参照される側（顧客マスタ、品目マスタ、案件台帳）を先に作ります。このときキーになる項目を必ず1つ用意します。

• 顧客マスタ → 顧客コード
• 品目マスタ → 品番
• 案件台帳 → 案件番号

キーは文字列（1行）か数値です。レコード番号をキーにするのは避けてください。 移行やCSVの入れ直しで番号が変わると、紐付けが全部ずれます。

Step 2: キーを一意にする

マスタ側のキー項目で「値の重複を禁止する」をオンにします。これはkintoneの標準機能です。

ただし標準の重複禁止は1つの項目しか見られません。「会社名＋電話番号の組み合わせで重複を止めたい」場合は、無料の重複チェック Proを使います（→kintoneで重複を禁止・チェックする方法）。

Step 3: 参照する側にルックアップを置く

記録する側（請求書、発注、内見予約）にルックアップフィールドを追加し、次を設定します。

「取得するレコードの条件」を最初から設定しておくと、退職した担当者や取引終了の顧客が候補に出なくなります。あとから入れると既存レコードとの整合を気にすることになるので、最初に入れてください。

Step 4: 動作を確かめる

ルックアップ欄に値を入れて「取得」を押し、コピー先の項目が埋まることを確認します。このとき、コピー先の項目を手で編集できてしまうことも一緒に確認しておいてください（後述）。

つまずく5つのポイント

1. マスタを直しても、過去のレコードは古いまま

仕様です。直したいなら、レコードを編集して取得ボタンを押し直します。

件数が多いときの現実的な対処は次の3つです。

「古い値のままで正しい」ケースも多いので、そもそも全部そろえる必要があるかを先に考えてください。 請求書の宛先住所は当時のままが正です。一方、品目マスタの標準原価を参照している製造指示は、そろえないと原価がずれます。

2. コピーされた値を、あとから手で書き換えられてしまう

ルックアップでコピーした項目は、標準では編集できます。「マスタと違う値が入ったレコード」が生まれる原因がこれです。

止めるには、無料の条件付き入力禁止で、コピー先の項目を編集できないようにします。「ステータスが確定なら編集不可」のように条件を付けることもできます。

3. キーの表記がゆれて、取得できない

「ABC商事」と「ＡＢＣ商事」、「1234」と「１２３４」、前後に空白が入っている、といった状態です。人は同じに見えますが、機械は別物として扱うので取得できません。

保存時に自動でそろえるには、無料の入力値の整形を使います。前後の空白の削除、全角英数字の半角化、半角カナの全角化などを項目ごとに選べます。マスタ側と記録側の両方に入れるのがポイントです。

4. 連鎖が深すぎて、直せなくなる

顧客マスタ → 案件 → 請求書 → 入金、のように4段になると、マスタ側の項目を1つ変えるだけで全部を触ることになります。2段までを目安にしてください。

3段目が欲しくなったら、たいていは1段目から直接ルックアップを引けるはずです。請求書が「案件経由で顧客名を持つ」必要はなく、顧客マスタから直接引けば済みます。

5. 候補が多すぎて選べない・遅い

参照先が数万件あると、候補の表示が重くなります。対処は2つです。

• ルックアップの「取得するレコードの条件」で候補を絞る
• コピーするフィールドを減らす（住所も電話も部署も…と増やすほど重くなる）

ルックアップが失敗する設計

JavaScriptで一括再取得する

マスタの値を過去のレコードにも反映したい、というときの最小の例です。一覧画面にボタンを出し、表示中のレコードのコピー項目をマスタの現在値で書き換えます。

(() => {
  'use strict';
  const MASTER_APP = 5;        // マスタアプリのID
  const KEY = '顧客コード';     // 自分のアプリ側のルックアップ（キー）
  const MAP = {                // 自分の項目 ← マスタの項目
    '顧客名': '顧客名',
    '住所': '住所',
  };

  kintone.events.on('app.record.index.show', (event) => {
    if (document.getElementById('refresh-lookup')) return event;
    const btn = document.createElement('button');
    btn.id = 'refresh-lookup';
    btn.textContent = 'マスタの値で更新';
    btn.onclick = async () => {
      btn.disabled = true;
      try {
        // 1. 表示中のレコードのキーを集める
        const keys = [...new Set(
          event.records.map((r) => r[KEY].value).filter(Boolean)
        )];
        if (keys.length === 0) return;

        // 2. マスタの現在値をまとめて取る
        const list = keys.map((k) => `"${String(k).replace(/"/g, '\\"')}"`).join(',');
        const master = await kintone.api('/k/v1/records', 'GET', {
          app: MASTER_APP,
          query: `${KEY} in (${list}) limit 500`,
          fields: [KEY, ...Object.values(MAP)],
        });
        const byKey = Object.fromEntries(
          master.records.map((m) => [m[KEY].value, m])
        );

        // 3. 自分のレコードを書き換える（100件ずつ）
        const updates = event.records
          .filter((r) => byKey[r[KEY].value])
          .map((r) => {
            const m = byKey[r[KEY].value];
            const rec = {};
            for (const [mine, theirs] of Object.entries(MAP)) {
              rec[mine] = { value: m[theirs].value };
            }
            return { id: r.$id.value, record: rec };
          });
        for (let i = 0; i < updates.length; i += 100) {
          await kintone.api('/k/v1/records', 'PUT', {
            app: kintone.app.getId(),
            records: updates.slice(i, i + 100),
          });
        }
        location.reload();
      } catch (e) {
        alert('更新に失敗しました：' + (e.message || e));
        btn.disabled = false;
      }
    };
    kintone.app.getHeaderMenuSpaceElement().appendChild(btn);
    return event;
  });
})();

注意点が3つあります。レコードの一括更新は1回100件までなので分けて送ること、limit 500 を超えるマスタではカーソルでの取得に書き換えること、そしてこの更新はルックアップの「取得」とは別物なので、コピー先の項目を条件付き入力禁止で止めている場合はいったん外す必要があることです。

JavaScriptを使わずに一覧から項目をまとめて書き換えるだけなら、無料の一覧からの一括更新でも足ります。JavaScriptカスタマイズの基本は13章 JavaScript・API・外部連携にまとめています。

実務での使われ方

不動産：内見予約 → 顧客・物件

内見予約アプリで顧客と物件を選ぶだけで、名前・住所・賃料が入ります。ここで担当者の予定の重なりを保存前に止めると、当日の鉢合わせがなくなります（→期間重複チェック）。実際の画面は不動産会社のkintoneにあります。

建設：発注 → 案件台帳

発注アプリで案件番号を選ぶと現場名が入ります。発注を案件のサブテーブルに持たず別アプリにするのは、業者別・支払予定日別の集計をしたいからです（→建設業の原価管理をkintoneで作る方法）。画面は建設会社のkintoneにあります。

製造：受注 → 品目マスタ

品番を選ぶだけで品名と標準原価が入ります。標準原価を改定したときは、過去の受注はそのままにしておくのが原則です（当時の原価が正）。画面は製造業のkintoneにあります。

いずれも「マスタ1つ × 記録が何本もぶら下がる」形です。アプリの分け方の判断は6章 複数アプリのつなぎ方と5章 アプリ設計の基本にまとめています。

よくある質問

ルックアップでコピーした値は参照元を直すと自動で更新されますか

自動では更新されません。ルックアップでコピーされた値はコピーした時点のスナップショットで、参照元のマスタを変更しても反映されません。更新したい場合は、レコードの編集画面で取得ボタンをもう一度押す必要があります。

ルックアップと関連レコード一覧の違いは何ですか

ルックアップは参照先の値を自分のアプリにコピーする機能で、関連レコード一覧は関連するレコードをその場で一覧表示する機能です。ルックアップはコピーなのでコピー先で編集でき、関連レコードはリアルタイム参照なので閲覧のみです。マスタデータを取り込みたいならルックアップ、関連情報を確認したいだけなら関連レコードを使います。

ルックアップのキーにはどんなフィールドを使えばいいですか

顧客コードのように重複しない一意の値を持つフィールドを使います。キーに重複があると、意図しないデータがコピーされる可能性があります。マスタアプリを設計する段階で、キーとなるフィールドを必ず用意しておきます。

ルックアップの候補表示が遅いときはどうすればいいですか

参照先のレコード数が数万件以上あると候補表示が遅くなります。ルックアップの設定でフィルター条件を指定し、候補を絞り込んでください。あわせて、コピーするフィールドを必要最小限に減らすことも有効です。

ルックアップは何段階まで連鎖させていいですか

3段階以上の連鎖は避けてください。AからBへ、BからCへ、CからDへとルックアップが何段階も連鎖すると、設定の変更が困難になります。顧客マスタから案件アプリ、案件アプリから請求書アプリ程度にとどめ、参照の順序を設計段階で固めておきます。