natural-language-queries

自然言語クエリ

概要

Happy Platform MCP 5.1 は、自然言語のフレーズのうち、限定されたセットを ServiceNow のエンコード条件に変換します。以下のパーサー検証済みパターンを個別に使用する場合は、SN-Natural-Language-Search を使用してください。正確な演算子、複数の分岐、除外、フィールド固有のテキスト処理、または決定論的な並べ替えが必要な場合は、SN-Query-Table を使用してください。

正規のフィクスチャは contracts/happy-platform-mcp-5.1.0-natural-language.json に含まれており、同階層の MCP ソースと照合するには npm run contract:nl-check を実行します。

前提条件

• 対象インスタンス用に Happy Platform MCP 5.1.0 が設定されていること
• 対象テーブルへの読み取りアクセス権があること
• 正確なテーブル名が分かっていること
• 調査目的の検索では、少数の結果上限と明示的な返却フィールドを指定すること

手順

1. パーサー検証済みのフレーズを1つ選択する

次の個別フレーズは、MCP 5.1.0 で完全に解析されます。

意図	対応フレーズ	生成されるエンコード条件
優先度ラベル	high priority	priority=2
優先度番号	P1 または priority 2	priority=1 または priority=2
影響度	high impact	impact=1
緊急度	medium urgency	urgency=2
現在のユーザー	assigned to me	assigned_to=javascript:gs.getUserID()
担当者なし	unassigned	assigned_toISEMPTY
指定した担当者	assigned to John Smith	assigned_to.nameLIKEJohn Smith
今日起票	opened today	sys_created_on>javascript:gs.daysAgoStart(0)
過去7日以内に起票	opened in the last 7 days	sys_created_on>javascript:gs.daysAgo(7)
最近のレコード	recent	sys_created_on>javascript:gs.daysAgo(7)
アクティブなレコード	active	active=true
説明文のテキスト	description contains authentication	descriptionLIKEauthentication
全般的な内容	about SAP	short_descriptionLIKESAP^ORdescriptionLIKESAP
完全一致する番号	number is INC0012345	number=INC0012345
発信者	caller is John Smith	caller_id.nameLIKEJohn Smith
カテゴリ	category is Software	categoryLIKESoftware
割り当てグループ	assignment group is Network Team	assignment_group.nameLIKENetwork Team

上記の対応関係は、v5.1 パーサーの実際の出力です。たとえば、「high」は優先度の値 2 に、「critical」は値 1 に対応します。

2. 範囲を限定して検索を実行する

必ず table を指定してください。v5.1 では引数名は table_name ではありません。実際のデータに対する作業や並行作業では、対象インスタンスを指定してください。

Tool: SN-Natural-Language-Search
Parameters:
  table: incident
  query: P1
  fields: sys_id,number,short_description,priority
  limit: 10
  instance: dev

encodedQuery、matchedPatterns、unmatchedText、および返されたレコードを確認します。ツールがエンコード条件も返している場合でも、unmatchedText が空でなければ検証失敗として扱ってください。

3. 調査目的の呼び出しは個別に行う

独立した質問ごとに、範囲を限定した呼び出しを個別に行ってください。

Tool: SN-Natural-Language-Search
Parameters:
  table: incident
  query: unassigned
  fields: sys_id,number,assigned_to
  limit: 10
  instance: dev

Tool: SN-Natural-Language-Search
Parameters:
  table: incident
  query: opened in the last 7 days
  fields: sys_id,number,sys_created_on
  limit: 10
  instance: dev

個別に対応している2つのフレーズを自由に組み合わせられるとは考えないでください。v5.1 パーサーは各パターンを最大1回処理し、残った単語によって結果が変わったり、条件が緩くなったりすることがあります。

4. 正確さが必要な場合はエンコードクエリを使用する

正確な比較、除外、複数の値、フィールド固有のテキスト演算子、または決定論的な並べ替えが必要な場合は、エンコードクエリを作成して確認し、SN-Query-Table を使用してください。

Tool: SN-Query-Table
Parameters:
  table_name: incident
  query: priority=1^state!=7^assigned_toISEMPTY^ORDERBYDESCsys_created_on
  fields: sys_id,number,short_description,priority,state,assigned_to,sys_created_on
  limit: 25
  instance: dev

エンコードクエリを使う方法は、自動化にも適しています。意味が自由形式のテキストからのパターン抽出に左右されないためです。

5. インシデント以外の対象は明示的に検証する

自然言語の解析では、テーブルに依存する処理に、指定されたテーブルが使用されます。別のテーブルを検索する場合、デフォルトに頼らないでください。

Tool: SN-Natural-Language-Search
Parameters:
  table: change_request
  query: recent
  fields: sys_id,number,short_description,sys_created_on
  limit: 10
  instance: dev

不慣れなテーブルでは、自然言語の検索結果を既知のレコードと照合して検証するまでは、エンコードした SN-Query-Table クエリを使用してください。

ツールの使用方法

ツール	用途
SN-Natural-Language-Search	パーサー検証済みのフレーズを1つ使用した、範囲を限定した調査
SN-Query-Table	正確で繰り返し可能なエンコードクエリの実行

ベストプラクティス

• table、fields、limit、instance を明示的に指定します。
• パッケージに含まれるフィクスチャの契約にある、単一の原子的なフレーズから始めます。
• パーサーの結果を信頼する前に、unmatchedText が空であることを確認します。
• limit を増やす前に、探索的な結果を既知のレコードと比較します。
• 本番環境での自動化や複雑な条件には、エンコード済みクエリを使用します。
• ペイロードと意図しないデータ露出を抑えるため、フィールドの選択は最小限にします。

トラブルシューティング

エンコード済み条件が返されない

フレーズが v5.1 のパターンに一致しませんでした。フィクスチャで確認済みの原子的なフレーズを1つ使うか、レビュー済みのエンコード済みクエリを使用して SN-Query-Table に切り替えてください。

条件は返されるが、テキストが残っている

パーサーはリクエストの一部だけに一致しました。結果を同等のクエリとして扱わないでください。リクエストを検証済みのフレーズ1つに絞るか、エンコード済みクエリを使用してください。

返された条件の意味が異なる

そのフレーズの使用を中止してください。自然言語のマッチングでは、意図しないパターンの単語が受け入れられることがあります。要件をエンコード済みクエリとして直接表現し、少数の結果セットで検証してください。

インシデント以外の検索で、インシデント形式の結果が返される

呼び出しで古い引数名ではなく table が使われていること、および明示的に指定したテーブルの値が正しいことを確認してください。

関連スキル

• itsm/incident-triage
• itsm/quick-reference
• admin/generic-crud-operations