目次
kintoneで業務アプリを作るとき、多くの会社が最初に使うのがルックアップです。商品マスタや取引先マスタから情報を引っ張ってきて、入力の手間を減らす仕組み。便利ですし、実際よく機能します。
ただ、この設計を一箇所だけ間違えると、運用が半年進んだあたりで静かに破綻します。それが**「ルックアップのキーに何を選ぶか」**です。
品名や取引先名といった、人が読んで分かる文字列をキーにしてしまう。よくある選択ですが、これが後から効いてきます。この記事では、なぜ名称キーが崩れるのか、どう設計すべきか、そしてAPI連携を見据えるなら最初から必要になる設定を整理します。
なぜ「名称」をキーにすると崩れるのか
ルックアップは、キーの値が完全一致したレコードを探します。ここが肝心で、人間の目には同じに見えても、システムから見れば別物です。
| 入力された値 | 見た目 | システムの判定 |
|---|---|---|
株式会社ABC / 株式会社 ABC | ほぼ同じ | 別の値（スペース有無） |
ＡＢＣ商事 / ABC商事 | ほぼ同じ | 別の値（全角・半角） |
ボールペン(黒) / ボールペン（黒） | ほぼ同じ | 別の値（括弧の種類） |
フリー入力の文字列は、必ず表記ゆれが起きます。担当者が2人以上いれば、ほぼ確実に起きます。しかも厄介なのは、エラーにならず「該当なし」になるだけという点です。入力した人は「マスタに無いのかな」と思って手入力で埋め、データはじわじわ汚れていきます。
さらに、名称は変わります。商品名のリニューアル、取引先の社名変更。名称をキーにしていると、マスタ側を直した瞬間に、過去のレコードとの紐付きが切れます。
堅牢な設計：キーは「番号」、名称は別フィールド
答えはシンプルで、キーには自動採番される値を使うことです。kintoneならレコード番号が代表格です。
- キー：レコード番号（または自社で決めたコード）— 一意で、変わらない
- 表示用の名称：別フィールドとしてルックアップのコピー元に指定する
こうすると、キーは機械が管理し、人が見る名称は別で持つ形になります。名称が変わってもキーは不変なので、紐付きが切れません。表記ゆれも起きようがありません。
「番号だと現場が探しにくいのでは」という懸念はもっともです。kintoneのルックアップは検索画面で名称からも絞り込めるので、実運用では困りません。入力の入口は名称で探し、保持する値は番号、という切り分けです。
API連携する予定があるなら、「値の重複を禁止する」は必須
ここからが、後で直せなくなる話です。
プログラム（API）からレコードを登録・更新して、ルックアップの値をセットする場面があります。基幹データの取り込み、他システムとの同期、GASからの一括登録などです。
このとき、ルックアップのキー側フィールドに「値の重複を禁止する」が設定されていないと、APIでの登録・更新が失敗します。エラーコードは GAIA_LO03。値そのものが一意であってもです。
理由は、UIとAPIの違いにあります。画面から入力した場合、候補が複数あればkintoneは選択ダイアログを出して人に選ばせられます。しかしAPIには「人に聞く」手段がありません。だから仕様として、キーが一意であることを設定レベルで保証していないと受け付けないのです。
つまり「重複禁止」は、データを守るための任意設定ではなく、API連携の前提条件だと考えてください。
なお、kintoneの仕様やエラー挙動は変わる可能性があるため、最新の条件は必ず公式ドキュメントで確認してください。
後から有効化できない、という落とし穴
「必要になったら設定すればいい」——これが通用しません。
「値の重複を禁止する」は、既存データに重複が1件でもあると有効化できません。 半年運用したマスタに、表記ゆれ由来の重複や、テスト時のゴミデータが残っている。この状態からデータを全件チェックして名寄せするのは、想像以上に骨が折れます。運用を止めるわけにもいきません。
だからこそ、API連携の可能性が少しでもあるなら、最初からコード／番号キー＋重複禁止で設計する。これが結論です。
順番が大事です。データを入れる前に設定を終えておく。それだけで、後の詰みを回避できます。
属性の持たせ方も「文字列」を避ける
同じ発想は、マスタが持つ属性フィールドにも当てはまります。
たとえば取引先マスタの「締め日」。ドロップダウンで 20日締め 月末締め といった文字列を並べる設計をよく見ますが、これはイレギュラーに弱い形です。集計や計算で使うたびに文字列を解釈し直す必要があり、選択肢を1つ増やすたびに処理を直すことになります。
| 持たせ方 | 例 | イレギュラーへの強さ |
|---|---|---|
| ドロップダウンの文字列 | 20日締め | 弱い（計算に使えない・選択肢追加で改修） |
| 数値＋チェックボックス | 締め日 20 ／ 月末フラグ ON | 強い（そのまま計算できる） |
数値は数値で、例外はフラグで持つ。締め日は数値フィールドに 20 と入れ、月末締めだけチェックボックスで表現する。こうすると、日付計算にそのまま使えますし、25日締め という取引先が現れても、選択肢の追加もアプリ改修も要りません。数値を入れるだけです。
マスタ設計の勘所は、「人が読む形」ではなく「機械が計算できる形」でデータを持ち、表示は後から作ることに尽きます。
実案件で見えたこと
実案件（匿名）でも、既存のkintoneアプリを引き継いだ際に、ルックアップのキーが取引先名になっていて、マスタに同名の重複が複数残っている状態に出くわしました。API連携を追加しようとした段階で「重複禁止が有効化できない」と判明し、まず名寄せから着手することになります。
このとき私たちが優先したのは、現場の入力画面を変えないまま、裏側のキーだけ差し替えることです。見た目が変わると現場が混乱し、移行そのものが止まります。表示は今まで通り名称、内部で持つのは番号。この形に寄せてから、API連携を乗せました。
先に設計しておけば数分で済んだ設定が、後からだと数日の作業になる。これがマスタ設計の怖いところであり、逆に言えば最初の30分で回避できるリスクでもあります。
まとめ
- ルックアップのキーに名称などフリー入力の文字列を使うと、スペース・全角半角・表記ゆれで完全一致が崩れる。しかもエラーにならず「該当なし」になるだけなので気づきにくい
- 堅牢な形はキー＝レコード番号（またはコード）、名称は別フィールド。名称が変わっても紐付きが切れない
- API連携でルックアップ値をセットするなら、キー側の**「値の重複を禁止する」設定が必須**。未設定だと
GAIA_LO03で失敗する（仕様は変わるため最新は公式で確認） - この設定は既存データに重複があると後から有効化できない。API連携を見据えるなら、データ投入前に設計しておく
- 締め日などの属性も、**ドロップダウンの文字列より「数値＋チェックボックス」**の方がイレギュラーに強い
RENOYでは、kintoneのアプリ設計・マスタ設計から、API連携や他システムとのつなぎ込みまでご支援しています。「すでに動いているアプリだが、この先の連携に耐えられるか不安」という段階のご相談も歓迎です。まずはお気軽に無料個別相談（オンライン・60分）をご利用ください。サービス内容をまとめた資料は資料請求からご覧いただけます。