参照フィールドと参照修飾子：候補はどう絞られるか

Incident フォームの Caller（caller_id）をクリックすると、ユーザーの一覧が出てきて、その中から1人を選びます。Change の RFC、Problem の problem_id も同じように「別テーブルのレコードを選ぶ」入力欄です。こうした欄を ServiceNow では参照（Reference）フィールドと呼びます。

では、その「一覧に出てくる候補」は、どこで・どうやって決まっているのでしょうか。候補の絞り込みを担うのが参照修飾子（Reference Qualifier）です。そして「Company を選ぶと Caller の候補がその会社の人だけになる」ような連動は、依存フィールド（dependent）で表されています。これらはすべて、フィールド定義テーブル sys_dictionary の数列に書かれています。

この記事は、Incident を触ったことがあり、参照フィールドの候補がなぜその顔ぶれになるのかを自分で調べられるようになりたい管理者・開発者を想定しています。参照フィールドが sys_dictionary でどう定義されるか、参照修飾子の3種類（Simple / Dynamic / Advanced）が何を指すか、依存（dependent）と dot-walk がどう効くかを、実機の sys_dictionary で順番に確認します。

この記事で分かること

• 参照（reference）型フィールドが sys_dictionary の internal_type=reference と reference 列で定義されること

• 候補を絞る参照修飾子（Reference Qualifier）が Simple / Dynamic / Advanced の3種類であること

• 3種類がそれぞれ sys_dictionary のどの列（reference_qual_condition / dynamic_ref_qual / reference_qual）に入るか

• 依存フィールド（dependent）が「別のフィールドの値で参照候補を絞る」仕組みであること

• dot-walk が参照フィールドから参照先の列をたどる操作であること、その注意点

• 自分のインスタンスで参照フィールドと修飾子を調べる URL

参照（Reference）フィールドとは

結論を先に書くと、参照フィールドは「別テーブルのレコードを1件指す列」で、その定義は sys_dictionary に書かれています。internal_type が reference で、reference 列に参照先テーブルが入っているフィールドが参照フィールドの実体です。

たとえば incident.caller_id は、sys_dictionary 上で internal_type=reference、reference=sys_user となっています。フォームで Caller を選ぶと、実データには選んだ sys_user レコードの sys_id が保存されます。表示は名前ですが、中身は参照先レコードへのポインタ（sys_id）です。sys_dictionary（Dictionary Entry）の各列の意味は、公式の Dictionary entry form（Zurich） にまとまっています。

今回確認した PDI（Zurich / OOTB）では、参照（reference）型フィールドは全部で 25,554 件ありました（全フィールド定義 152,744 件の中の数）。そのうち最も多く参照されているテーブルのひとつが sys_user で、sys_user を参照するフィールドは 4,270 件でした。Caller・Assigned to・Opened by など、ServiceNow が「人」を指す欄をいかに多く持っているかが分かります。なお、複数のレコードをまとめて参照する glide_list（複数参照リスト）型は 585 件で、こちらは1対多を1フィールドで持つ形です。

incident テーブルの参照フィールド

incident テーブルに絞ると、参照型フィールドは7件でした。

caller_id・reopened_by・resolved_by は sys_user（User）を、caused_by・rfc は change_request を、problem_id は problem を、parent_incident は incident（自テーブル）を参照しています。「このフィールドは○○を参照する」という説明は、すべて sys_dictionary の reference 列の値そのものです。

https://<YourInstance>/sys_dictionary_list.do?sysparm_query=name=incident^internal_type=reference

参照修飾子（Reference Qualifier）の3種類

参照フィールドの候補を絞り込むのが参照修飾子（Reference Qualifier）で、OOTB では Simple / Dynamic / Advanced の3種類があります。どれを使うかは sys_dictionary の use_reference_qualifier 列に入ります。今回の PDI で use_reference_qualifier の選択肢を確認したところ、ちょうど simple / dynamic / advanced の3つでした。参照修飾子の概念と種類は、公式の Reference qualifiers（Zurich） にまとまっています。

3種類の件数の内訳

今回確認した PDI（Zurich / OOTB）の reference 型 25,554 件は、すべていずれかの種類に分類されていました（未設定は0件）。内訳は次のとおりです。

• Simple（22,144 件） … 条件ビルダーで絞り込みます。設定は reference_qual_condition 列に入ります。コードを書かずに「customer=true のものだけ」のような条件を組めます。実際に reference_qual_condition に条件が入っているのは 2,590 件で、残りは「絞り込みなし＝参照先テーブル全件」です。

• Dynamic（742 件） … あらかじめ定義された「動的修飾子」を選んで再利用します。設定は dynamic_ref_qual 列（sys_filter_option_dynamic への参照）に入ります。同じ絞り込みを複数のフィールドで共有したいときに使います。

• Advanced（2,668 件） … エンコードクエリや javascript: 式を直接書きます。設定は reference_qual 列に入ります。「現在編集中のレコードの値に応じて候補を変える」ような複雑な絞り込みに使います。reference_qual に式が入っているのは 6,000 件でした。

3種類の違いは「絞り込みの書き方」です。単純な条件なら Simple、使い回したいなら Dynamic、現在レコードに依存する複雑な条件なら Advanced、という住み分けになります。これらの設定は、参照フィールドを定義する sys_dictionary の各列に分かれて入ります。

Simple の実例

たとえば cmdb_ci_lb_datacenter テーブルの company フィールドは core_company（Company）を参照しますが、reference_qual_condition に customer=true が入っていて、「customer フラグが立った会社だけ」に候補を絞っています。同じテーブルの vendor フィールドは vendor=true で、ベンダー扱いの会社だけを候補にします。コードは一切登場しません。

Dynamic の実例

cmdb_ci_* 系（CI関連）のテーブルの model_id フィールドは cmdb_model（Product Model）を参照しますが、その候補を絞る動的修飾子として「CI Model Qualifier」という定義済みの修飾子が設定されていました。同じ絞り込みロジックを複数の CI テーブルで使い回している例です。Simple のように条件を1件ずつ書くのではなく、あらかじめ用意された修飾子（sys_filter_option_dynamic のレコード）を選ぶだけで済みます。

Advanced の実例

incident.parent_incident（親インシデント）は incident（自テーブル）を参照しますが、reference_qual に javascript:'sys_id!='+current.sys_id が入っています。これは「今開いているレコード自身を、親候補から除外する」という意味です。current.sys_id で現在のレコードを参照し、自分自身を親に選べないようにしています。Simple では書けない「現在レコードに依存する条件」を、Advanced の JavaScript 式が実現しています。

https://<YourInstance>/sys_dictionary_list.do?sysparm_query=internal_type=reference^reference_qual_conditionISNOTEMPTY

依存フィールド（dependent）：別のフィールドで候補を絞る

参照修飾子と並んでよく出てくるのが依存（dependent）です。dependent は「別のフィールドの値が決まると、この参照フィールドの候補がそれに合わせて絞られる」という連動を表します。

代表例が incident.caller_id です。sys_dictionary を見ると、caller_id は use_reference_qualifier=simple かつ dependent=company（dependent_on_field=company）になっています。つまり Company を選ぶと、その会社に属する User だけが Caller の候補になる、という連動です。

今回確認した PDI（Zurich / OOTB）では、dependent が設定された参照型フィールドは 749 件でした。参照修飾子が「条件で絞る」のに対し、依存は「別フィールドの値で絞る」もので、どちらも候補を絞る仕組みですが、絞る基準が違います。実務では、両者を組み合わせて「Company で会社を絞り、さらに修飾子で active なユーザーだけに絞る」といった使い方もされます。依存フィールドの設定方法は、公式の Specify dependent fields（Zurich） を参照してください。

dot-walk：参照フィールドから参照先の列をたどる

参照フィールドがあると、その参照先の列を「.」でたどれます。これを dot-walk（ドットウォーク）と呼びます。たとえば incident.caller_id は sys_user を参照するので、caller_id.manager（Caller の上司）や caller_id.department.name（Caller の部署名）のように、参照の先の値をフォームやレポート、クエリで利用できます。

dot-walk は「参照のチェーンをたどる」操作なので、参照フィールドが連なっていれば何段でもたどれます。クエリでも caller_id.active=true のように使え、本連載の調査でも super_class.name=task のような dot-walk クエリを使ってきました。

ただし注意点があります。dot-walk で持ってきた列は基本的に表示用で、そこに依存（dependent）の連動を期待しても効きません。公式の Known Error やコミュニティでも、dot-walk したフィールドでは依存が働かない（候補が絞られない）ことが指摘されています。「会社で絞った Caller」のような連動が必要なときは、dot-walk ではなく、その表に依存フィールドや参照修飾子（必要なら Advanced のスクリプト）を設定するのが定石です。dot-walk の具体例は、公式の Dot-walking examples（Zurich） にまとまっています。

参照フィールドと修飾子を読むときのポイント

• 参照フィールドは sys_dictionary の internal_type=reference で、参照先は reference 列 に入ります。今回の PDI では reference 型は 25,554 件、うち sys_user 参照が 4,270 件でした。

• 候補を絞る参照修飾子は Simple / Dynamic / Advanced の3種類です。今回の PDI では simple 22,144・dynamic 742・advanced 2,668 で、合計が reference 型総数（25,554）と一致しました。種類は use_reference_qualifier に入ります。

• 3種類は設定列が違います。 Simple は reference_qual_condition（条件ビルダー）、Dynamic は dynamic_ref_qual（定義済み修飾子）、Advanced は reference_qual（エンコードクエリ / javascript:）です。

• 依存（dependent）は「別フィールドの値で候補を絞る」 仕組みです。incident.caller_id は dependent=company で、会社を選ぶと候補が絞られます。今回の PDI で dependent 設定は 749 件でした。

• dot-walk は参照先の列を「.」でたどる 操作です。クエリやフォームで使えますが、dot-walk した列では依存が効かない点に注意します。

参照まわりの主な列一覧

ここまでに出てきた列を実務で見る順に並べると、internal_type（型）・reference（参照先）・use_reference_qualifier（修飾子の種類）・reference_qual_condition（Simple の条件）・dynamic_ref_qual（Dynamic の定義）・reference_qual（Advanced の式）・dependent / dependent_on_field（依存の設定）の7つです。候補の絞り込みを調べるときは、この7列のどれに値が入っているかを順に見ていくと迷いません。sys_dictionary にはこのほか use_dependent_field という列もあり、依存まわりの設定は dependent と dependent_on_field の2列だけにとどまりません。

参照フィールドの候補が「なぜこの顔ぶれか」を調べたくなったら、まず sys_dictionary でそのフィールドの reference（参照先）と use_reference_qualifier（修飾子の種類）を見て、種類に応じて reference_qual_condition / dynamic_ref_qual / reference_qual を読み、最後に dependent を確認します。この順番で、候補の絞り込みロジックを自分で再現できます。

実機を見て気づいたこと

• Advanced に分類されているフィールドは 2,668 件なのに、reference_qual 列に式が入っている行は 6,000 件ありました。種類を Advanced に変えないまま reference_qual だけ値が残っている行があるようです。件数が食い違ったら、まず use_reference_qualifier の値と、実際に設定列へ値が入っているかを別々に確認するとよさそうです。

• 参照フィールド全 25,554 件のうち 4,270 件が sys_user を参照していました。比率にすると6件に1件以上が「人」を指す参照フィールドで、業務データが人に紐づく設計であることが件数からも読み取れます。

次に読むなら

参照フィールドは sys_dictionary の一機能なので、まず テーブル定義とフィールド定義の読み方（sys_dictionary） の記事に戻ると、internal_type や reference 列の位置づけが俯瞰できます。そこから、Advanced 修飾子で使う Script Include、Dynamic 修飾子の実体である sys_filter_option_dynamic、参照候補にさらに効いてくる ACL（sys_security_acl）が、次に確認する入口になります。参照の「候補がなぜその顔ぶれか」は、修飾子・依存・ACL の3つで決まると考えると整理しやすいです。

用語

• PDI：Personal Developer Instance（無料の検証用インスタンス）

• OOTB：Out of the Box（初期設定のまま）

• 参照（reference）フィールド：別テーブルのレコードを1件指す列（internal_type=reference）

• 参照修飾子（Reference Qualifier）：参照フィールドの候補を絞り込む設定。Simple / Dynamic / Advanced

• dependent（依存）：別フィールドの値で参照候補を絞る連動

• dot-walk：参照フィールドから参照先の列を「.」でたどる操作

自分の環境で確認するときのURL

先頭に自分のインスタンスを付けると、同じ画面が開けます。

incident の参照型一覧   : sys_dictionary_list.do?sysparm_query=name=incident^internal_type=reference
caller_id の定義        : sys_dictionary_list.do?sysparm_query=name=incident^element=caller_id
parent_incident の定義  : sys_dictionary_list.do?sysparm_query=name=incident^element=parent_incident
Simple 条件つきの一覧   : sys_dictionary_list.do?sysparm_query=internal_type=reference^reference_qual_conditionISNOTEMPTY
全参照型フィールド一覧   : sys_dictionary_list.do?sysparm_query=internal_type=reference

検証範囲とおことわり

• 確認した範囲：reference 型フィールド総数（25,554）、sys_user 参照（4,270）、glide_list（585）、参照修飾子3種の件数（Simple 22,144 / Dynamic 742 / Advanced 2,668、合計＝25,554）、reference_qual_condition 設定（2,590）、reference_qual 設定（6,000）、dependent 設定（749）、incident の参照型7件と各参照先・修飾子・依存、Simple / Dynamic / Advanced / dependent の代表例。すべて PDI（Zurich / 2026-06-22 確認）の OOTB で取得しています。

• 確認していない範囲：各 reference_qual スクリプトの実行時の挙動、Dynamic 修飾子（sys_filter_option_dynamic）の中身の網羅、dot-walk と依存（dependent）を組み合わせたときの挙動の網羅的検証、ACL やドメイン分離による参照候補の差、カスタムテーブルでの挙動。これらは別途確認が必要です。