Searching a semantic knowledge base
===================================

セマンティックKBがスキーマをクロールしたら、自然言語クエリで検索します。
KBは、スキーマのインデックス付けに使用したものと同じモデルでクエリを埋め込み、メタデータがクエリに最も近いテーブル、ビュー、および列を結果ます。すべての検索ファンクションは、KB名を\ ``kb_name``
として取得します。これは、KBが1つだけ存在する場合に省略できます。

promoteb.semantic_kb_search()
-----------------------------

``semantic_kb_search()``
は、複合エントリーポイントです。ソースごとのランク付け検索スキーマメタデータと厳選された :ref:`Semantic aliases <Semantic aliases>` を実行し、相互ランク融合RRFで1つのランクリストに融合します。
「スキーマの何がこれに関連していますか?」に対する単一のランク付けの回答が必要な場合に使用します。

.. code:: sql

   SELECT source_type, entity_type, schema_name, relation_name, column_name, rank
   FROM aidb.semantic_kb_search(
       query_text => which customers spent the most,
       kb_name    => analytics_kb,
       top_k      => 5
   );

.. csv-table::
  :header: Parameter,Type,Default,Description
  :widths: 15,12,12,20
  :align: left
  :class: longtable

  `query_text`,`text`,—,自然言語クエリー。
  `kb_name`,`text`,`NULL`,検索するKB。 1つのKBのみが存在する場合、単一のKBをターゲットとすることを省略します。
  `top_k`,`int`,`10`,返されるランク付けされた行の数。
  `sources`,`text[]`,`NULL`,検索するソース。アクティブ `schema`、`alias`すべて省略します。 `history`、`relationship`は予約されています。
  `entity_types`,`text[]`,`NULL`,含めるエンティティタイプ。アクティブ `Table`、`View`、`Column`、`Alias`。すべて省略します。
  `rrf_k`,`int`,`60`,ランクフュージョンの減衰定数。
  `min_similarity`,`double precision`,`NULL`,オプションの類似度フロア。それより低いスコアの行はドロップされます。フロアがない場合は省略します。

一致ごとに1行を結果ます。

.. csv-table::
  :header: Column,Description
  :widths: 10,30
  :align: left
  :class: longtable

  `source_type`,行を生成したソース `schema`または`alias`のいずれか。
  `entity_type`,`Table`、`View`、`Column`、または`Alias`
  `schema_name`,エンティティが属するスキーマ。
  `relation_name`,テーブルまたはビューの名前。
  `column_name`,列名テーブルレベルおよびビューレベルの一致の場合は空です。
  `object_ref`,一致したオブジェクトへの修飾参照。
  `definition`,埋め込まれた構造定義。
  `comment`,エンティティの`COMMENT ON`テキスト存在する場合。
  `score`,融合されたRRFスコア。
  `rank`,融合された結果セット内の1ベースのランク。
  `components`,フュージョンをフィードしたソースごとのスコアのJSONB詳細。

``semantic_kb_search()``
は、スキーマエンティティと一致するエイリアスの両方を1つのランク付けリストで返すため、これは :ref:`例 text-to- SQLエージェント <例 text-to- SQLエージェント>` ワークフローでの自然な最初の呼び出しです。

スキーマメタデータファンクション
--------------------------------

より狭いニーズの場合、4つのファンクションはスキーマメタデータのみを検索します。これらは同じオプショナルの\ ``kb_name``
および\ ``similarity``
スコアコサイン類似度、高いほど近いを共有し、\ ``min_similarity``
はオプショナルのフロアとして、ページング用には\ ``top_k`` / ``offset``
を使用します。

promoteb.get_metadata()
^^^^^^^^^^^^^^^^^^^^^^^

これは最も広範なスキーマ検索であり、完全なメタデータとともに列、テーブル、およびビューを結果ます。

.. code:: sql

   SELECT schema_name, relation_name, column_name, entity_type, similarity
   FROM aidb.get_metadata(
       kb_name    => analytics_kb,
       query_text => customer email address,
       top_k      => 10
   );

パラメーター ``kb_name`` 、 ``query_text`` 、 ``min_similarity`` 、
``top_k`` デフォルト\ ``10`` 、\ ``offset`` デフォルト\ ``0`` 。
``schema_name`` 、\ ``relation_name`` 、\ ``column_name``
、\ ``entity_type`` 、\ ``definition`` 、\ ``comment``
、\ ``definition_vector`` 、および\ ``similarity`` を返します。

promoteb.get_entity_Definitions()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**テーブルとビュー** のみに一致します。

.. code:: sql

   SELECT schema_name, relation_name, entity_type, similarity
   FROM aidb.get_entity_definitions(
       kb_name      => analytics_kb,
       query_text   => orders and line items,
       entity_types => ARRAY[Table, View]
   );

パラメーター ``kb_name`` 、\ ``query_text`` 、\ ``min_similarity``
、\ ``entity_types`` デフォルト\ ``ARRAY['Table','View']`` 、\ ``top_k``
、\ ``offset`` 。 ``schema_name`` 、\ ``relation_name``
、\ ``entity_type`` 、\ ``definition`` 、\ ``comment``
、\ ``similarity`` を返します。

promoteb.get_column_definings()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

一致する列とテーブルの **定義** 、最もリーンな結果のみを返します、
SQL生成のコンパクトな基礎として役立ちます。

.. code:: sql

   SELECT definition
   FROM aidb.get_column_definitions(
       kb_name    => analytics_kb,
       query_text => order total amount
   );

パラメーター ``kb_name`` 、\ ``query_text`` 、\ ``min_similarity``
、\ ``top_k`` 、\ ``offset`` 単一の\ ``definition`` 列を結果ます。

promoteb.search_by_comment()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

スキーマ、テーブル、列に添付された自然言語\ ``COMMENT ON``
テキストのみと一致します。

.. code:: sql

   SELECT relation_name, column_name, comment, similarity
   FROM aidb.search_by_comment(
       kb_name    => analytics_kb,
       query_text => order status values
   );

パラメーター ``kb_name`` 、\ ``query_text`` 、\ ``min_similarity``
、\ ``top_k`` 、\ ``offset`` ``schema_name`` 、\ ``relation_name``
、\ ``column_name`` 、\ ``entity_type`` 、\ ``definition``
、\ ``comment`` 、\ ``similarity`` を返します。

これは、スキーマに既に書き込んだドキュメントを活用する最も直接的な方法です。たとえば、
*「order lifecycle state:
pending、confirmed、shiped、delivered、Cancelled」*
とコメントされた列は、列自分自身の名前が\ ``st`` であっても、 *「order
statusvalues」*
のようなクエリーに表示されます。コメント検索は十分に文書化されたオブジェクトに依存しているため、
``COMMENT ON``
ステートメントを最新の状態に保つことが、セマンティックKBの結果を向上させる最も効果的な方法です。

チューニング結果
----------------

- **``min_similarity``**
  は、再現率を犠牲にして精度を高めます。クエリが何も返さない場合、それを下げますたとえば
  ``0.3`` 。結果が広範すぎる場合に上げます。

- **``top_k`` / ``offset``** 結果をページスルーします。

- **``entity_types``**
  特定のフィールドをハンティングしているときに、\ ``ARRAY['Column']``
  などの関心のある種類に絞り込みます。

次のステップ
------------

- よくある質問を :ref:`Semantic aliases <Semantic aliases>` 
  を使用して、再利用可能なパラメーター化クエリーとして保存します。

- :ref:`例 text-to- SQLエージェント <例 text-to- SQLエージェント>` ワークフローでエージェントにこれらの検索をエンドツーエンドで駆動させます。