Example
=======

この例では、小さな\ ``sales``
スキーマを介した完全なセマンティックナレッジベースのワークフローを説明します。スキーマの文書化、インデックス付け、意味による検索、および再利用可能なエイリアスとしての繰り返しの質問のキャプチャ。

ステップ1エンベディングモデルを登録する
---------------------------------------

セマンティックKBは、テキスト埋め込みモデルを使用してスキーマメタデータを埋め込みます。最初に1つ登録します

.. code:: sql

   SELECT aidb.create_model(sales_embeddings, bert_local);
   __OUTPUT__
      create_model
   - -------------------
    sales_embeddings
   (1 row)

ステップ2スキーマを作成および文書化する
---------------------------------------

コメントは構造メタデータとともに埋め込まれるため、スキーマを直接文書化すると検索品質が向上します。

.. code:: sql

   CREATE SCHEMA sales;

   CREATE TABLE sales.customers (
       id     INT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
       email  TEXT NOT NULL,
       region TEXT
   );

   CREATE TABLE sales.orders (
       id          INT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
       customer_id INT NOT NULL REFERENCES sales.customers(id),
       amount      NUMERIC(12,2) NOT NULL,
       status      TEXT NOT NULL,
       order_date  DATE NOT NULL
   );

   COMMENT ON TABLE  sales.orders          IS One row per customer order, with its monetary amount and lifecycle status.;
   COMMENT ON COLUMN sales.orders.amount   IS Order total in USD.;
   COMMENT ON COLUMN sales.orders.status   IS Order lifecycle state: pending, confirmed, shipped, delivered, cancelled.;
   COMMENT ON COLUMN sales.customers.email IS Customer contact email address.;

ステップ3セマンティックKBを作成する
-----------------------------------

``sales`` スキーマを介してKBを作成します。 ``model`` は必須です。
``Live``
自動処理は、スキーマの変更に応じてインデックスを最新の状態に保ちます。

.. code:: sql

   SELECT aidb.create_semantic_kb(
       name    => analytics_kb,
       model   => sales_embeddings,
       schemas => ARRAY[sales],
       auto_processing => Live
   );
   __OUTPUT__
    create_semantic_kb
   - -------------------
    analytics_kb
   (1 row)

ステップ4インデックスされた内容を確認する
-----------------------------------------

``aidb.semantic_kb_stats()``
は、エンティティ数と保留中のスキーマの変更をレポートします。

.. code:: sql

   SELECT * FROM aidb.semantic_kb_stats(kb_name => analytics_kb);
   __OUTPUT__
    total | tables | views | columns | pending
   - ------+--------+-------+---------+---------
       10 |      2 |     0 |       8 |       0
   (1 row)

ステップ5意味で検索する
-----------------------

名前が使用されている単語と一致しない場合でも、コンセプトにマップするスキーマエンティティを見つけます。
``semantic_kb_search()``
は、スキーマエンティティと一致するエイリアスを1つのランク付けリストで結果ます。

.. code:: sql

   SELECT source_type, entity_type, schema_name, relation_name, column_name, rank
   FROM aidb.semantic_kb_search(
       query_text => customer email address,
       kb_name    => analytics_kb,
       top_k      => 3
   );
   __OUTPUT__
    source_type | entity_type | schema_name | relation_name | column_name | rank
   - ------------+-------------+-------------+---------------+-------------+------
    schema      | Column      | sales       | customers     | email       |    1
    schema      | Table       | sales       | customers     |             |    2
    schema      | Column      | sales       | orders        | customer_id |    3
   (3 rows)

コメント検索は、名前だけでなく文書化したインテントを介してエンティティを見つけます。

.. code:: sql

   SELECT relation_name, column_name, comment
   FROM aidb.search_by_comment(
       query_text => order status values,
       kb_name    => analytics_kb,
       top_k      => 1
   );
   __OUTPUT__
    relation_name | column_name |                             comment
   - --------------+-------------+------------------------------------------------------------------
    orders        | status      | Order lifecycle state: pending, confirmed, shipped, delivered...
   (1 row)

ステップ6定期的な質問をエイリアスとして保存する
-----------------------------------------------

「特定の月にいくらの収益がありましたか?」という質問は繰り返し発生するため、毎回SQLを再生成するのではなく、 :ref:`Semantic aliases <Semantic aliases>` としてキャプチャします。
AIDBは、エイリアスが\ ``analytics_kb``
のメンバーであると推論し、クエリーが読み取る\ ``sales``
スキーマを所有するKB

.. code:: sql

   SELECT aidb.create_semantic_alias(
       name        => monthly_revenue,
       description => Total revenue for a given month and year,
       query_text  => $$
           SELECT SUM(amount) AS total
           FROM sales.orders
           WHERE EXTRACT(MONTH FROM order_date) = ${month}
             AND EXTRACT(YEAR  FROM order_date) = ${year}
       $$,
       params => [
           {"name": "month", "param_type": "integer", "description": "Month number (1-12)"},
           {"name": "year",  "param_type": "integer", "description": "Four-digit year"}
       ]
   );
   __OUTPUT__
    create_semantic_alias
   - ----------------------
    monthly_revenue
   (1 row)

ステップ7エイリアスを見つけて実行する
-------------------------------------

検索は自然言語の質問をエイリアスに解決します。

.. code:: sql

   SELECT name, similarity
   FROM aidb.search_semantic_aliases(
       query_text => how much money did we make last month,
       kb_name    => analytics_kb,
       top_k      => 1
   );
   __OUTPUT__
         name       | similarity
   - ----------------+------------
    monthly_revenue |      0.83
   (1 row)

パラメーターを使用して実行します。

.. code:: sql

   SELECT result
   FROM aidb.execute_semantic_alias(
       alias_name => monthly_revenue,
       args       => {"month": 3, "year": 2025}
   );
   __OUTPUT__
           result
   - ----------------------
    {"total": 48250.00}
   (1 row)

エージェントからの使用
----------------------

上記はすべて :ref:`Agents reference <Agents reference>` 
でも利用できます。エージェントにセマンティックKB
:ref:`search tools <Knowledge bases reference>` および\ ``run_sql_query``
を与えると、自由形式の質問に自分自身で回答できます。\ ``semantic_kb_search``
を呼び出して関連するテーブルと列を検出し、これらの定義に基づいてSQLを生成、実行します- :ref:`例 text-to- SQLエージェント <例 text-to- SQLエージェント>` ワークフロー。

あなたが構築したもの
--------------------

- 文書化された\ ``sales`` スキーマをインデックスするセマンティックKB
  ``analytics_kb`` ``Live`` モードで最新の状態に保たれます。

- 意味によってリレーションと列を見つける自然言語スキーマ検索。

- 繰り返しの質問の再利用可能なパラメーター化されたエイリアス、意味によって見つけられ、パラメーターを使用して実行可能。