Example#

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

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

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

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

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

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

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 自動処理は、スキーマの変更に応じてインデックスを最新の状態に保ちます。

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() は、エンティティ数と保留中のスキーマの変更をレポートします。

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つのランク付けリストで結果ます。

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)

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

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を再生成するのではなく、 Semantic aliases としてキャプチャします。 AIDBは、エイリアスがanalytics_kb のメンバーであると推論し、クエリーが読み取るsales スキーマを所有するKB

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エイリアスを見つけて実行する#

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

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)

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

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

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

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

あなたが構築したもの#

文書化されたsales スキーマをインデックスするセマンティックKB analytics_kb Live モードで最新の状態に保たれます。
意味によってリレーションと列を見つける自然言語スキーマ検索。
繰り返しの質問の再利用可能なパラメーター化されたエイリアス、意味によって見つけられ、パラメーターを使用して実行可能。

Example

目次