PolarDB:外部データソースを使用した Data-Agent の構築

仕組み

PolarDB for AI は、外部データソースのメタデータを特定のテーブルに保存します。このメタデータには、テーブルスキーマ、列コメント、サンプル値などの情報が含まれます。その後、内部モデルがテキストメタデータをベクターに変換し、schema_info_index という名前の検索可能なインデックステーブルに保存します。

自然言語クエリを実行すると、大規模言語モデルベースの自然言語から SQL へ (NL2SQL) 機能は次の操作を実行します：

1. 自然言語の質問をベクターに変換します。

2. schema_index テーブルでベクター類似性検索を実行し、質問に関連するテーブルと列を見つけます。

3. 取得したメタデータを使用して、実行可能な SQL または DSL のクエリ文を生成します。

適用範囲

開始する前に、次の準備が完了していることを確認してください：

• エンジン：PostgreSQL 16 (マイナーエンジンバージョン 2.0.16.10.11.0 以降)。

事前準備

4. schema_info メタデータテーブルの作成

   このテーブルには、テーブル名、列名、コメント、データの型など、外部データソースに関する情報が記録されます。

   CREATE TABLE IF NOT EXISTS public.schema_info (
       id SERIAL PRIMARY KEY,
       table_name VARCHAR(255) NOT NULL,
       table_comment TEXT,
       column_name VARCHAR(255) NOT NULL,
       column_comment TEXT,
       data_type VARCHAR(255) NOT NULL,
       sample_values TEXT,
       is_primary BOOLEAN DEFAULT FALSE,
       is_foreign BOOLEAN DEFAULT FALSE,
       ext TEXT,
       db_type VARCHAR(128)
   );
   
   COMMENT ON TABLE schema_info IS 'データベースメタデータ情報テーブル';
   COMMENT ON COLUMN schema_info.id IS '自動増分プライマリキー';
   COMMENT ON COLUMN schema_info.table_name IS 'テーブル名';
   COMMENT ON COLUMN schema_info.table_comment IS 'テーブルコメント。NL2SQL の精度にとって重要です。';
   COMMENT ON COLUMN schema_info.column_name IS '列名';
   COMMENT ON COLUMN schema_info.column_comment IS '列コメント。NL2SQL の精度にとって重要です。';
   COMMENT ON COLUMN schema_info.data_type IS '列のデータの型';
   COMMENT ON COLUMN schema_info.sample_values IS 'サンプル値。カンマで区切ります。';
   COMMENT ON COLUMN schema_info.is_primary IS '列がプライマリキーであるかどうかを示します (true/false)。';
   COMMENT ON COLUMN schema_info.is_foreign IS '列が外部キーであるかどうかを示します (true/false)。';
   COMMENT ON COLUMN schema_info.ext IS '外部キーの関連情報。フォーマット：database_name.table_name.column_name';
   COMMENT ON COLUMN schema_info.db_type IS 'リレーショナルデータベースの言語タイプ (MySQL、PostgreSQL、StarRocks、Oracle など)。';

5. メタデータの準備と挿入

   次のフォーマットでメタデータを schema_info テーブルに挿入します。

   • db_type：ソースデータベースのタイプを指定します (例：MySQL、PostgreSQL)。同じ論理データベース内のすべてのテーブルは、同じ db_type を持つ必要があります。

   • sample_values：サンプル値。複数の値を区切るにはカンマ (,) を使用します。最適なパフォーマンスを確保するため、フィールドの全長は 100 文字を超えないようにしてください。

   • is_foreign：列が外部キーであるかどうかを示します。値 1 は、列が外部キーであることを示します。

   • ext：is_foreign が 1 に設定されている場合、この列には外部キーの関連情報を含める必要があります。フォーマットは <database_name>.<table_name>.<column_name> です。

   例：customers テーブルと orders テーブルのメタデータを挿入します。

   -- customers テーブルのメタデータを挿入
   INSERT INTO schema_info (table_name, table_comment, column_name, column_comment, data_type, sample_values, is_primary, is_foreign, ext, db_type) VALUES
   ('customers', 'Customer information table', 'id', 'Unique customer identifier', 'INT', '1,2,3', true, false, NULL, 'MySQL'),
   ('customers', 'Customer information table', 'name', 'Customer name', 'VARCHAR(100)', 'John Doe,Jane Smith,Peter Jones', false, false, NULL, 'MySQL'),
   ('customers', 'Customer information table', 'email', 'Customer email', 'VARCHAR(100) UNIQUE', 'johndoe@example.com,janesmith@example.com', false, false, NULL, 'MySQL');
   
   -- orders テーブルのメタデータを挿入
   INSERT INTO schema_info (table_name, table_comment, column_name, column_comment, data_type, sample_values, is_primary, is_foreign, ext, db_type) VALUES
   ('orders', 'Order information table', 'order_id', 'Unique order identifier', 'INT', '1001,1005,1003', true, false, NULL, 'MySQL'),
   ('orders', 'Order information table', 'order_date', 'Order date', 'DATE', '2023-01-01,2023-05-06', false, false, NULL, 'MySQL'),
   ('orders', 'Order information table', 'customer_id', 'Associated customer ID', 'INT', '1,2,3', false, true, 'dbname.customers.id', 'MySQL'),
   ('orders', 'Order information table', 'total_amount', 'Total order amount', 'DECIMAL(10,2)', '99.99,101.81,250.00', false, false, NULL, 'MySQL');

6. AI ノードのデータベースアカウントへのビジネス テーブルの権限付与

   例えば、AI ノードに設定されたデータベース接続アカウントが polarai_user の場合、schema_info テーブルに対する権限を polarai_user に付与する必要があります。

   説明

   本番環境では、AI ノードのデータベースアカウントが関連するビジネス テーブルに対する権限を持っていることを確認してください。

   -- 権限を付与
   GRANT ALL PRIVILEGES ON TABLE public."schema_info" TO polarai_user;

検索インデックスの構築

schema_info テーブルのメタデータに基づいて、NL2SQL のための検索インデックスを作成できます。

構文

text ai_BuildSchemaIndex(text name, jsonb text2vecOption default '{"mode": "async", "resource": "schema"}');

• name：インデックスに指定する名前。この名前は後続のクエリで使用されます。

• text2vecOption：次のパラメーターを含む JSON 文字列です：

  • mode：データ書き込みモード。デフォルト値は async で、非同期実行を示します。

  • resource：リソースタイプ。ベクター化する情報を指定します。このパラメーターを schema_info に設定します。

  • to_sample：列値をサンプリングするかどうかを指定します。列数が少ないテーブル (例えば 15 未満) では、サンプリングによって生成される SQL の品質が向上しますが、インデックス構築時間が増加します。0 (デフォルト)：サンプリングなし。1：サンプリングを実行。

例

• 次のコマンドを実行して、schema_info テーブルに対して schema_info_index という名前のテーブルスキーマインデックスを作成します。この操作は、テーブルスキーマ、コメント、およびその他の情報を収集してベクター化し、大規模言語モデルにコンテキストを提供します。

  SELECT polar_ai.ai_BuildSchemaIndex('schema_info_index', '{"mode":"async", "resource":"schema_info", "to_sample":1}');

• コマンドは bce632ea-97e9-11ee-bdd2-492f4dfe0918 のようなタスク ID を返します。次のコマンドを実行してタスクステータスをクエリできます。finish というステータスは、インデックスが構築されたことを示します。

  SELECT polar_ai.ai_ShowTask('<your_task_id>');

Data-Agent を使用したデータクエリ

インデックスが構築された後、大規模言語モデルベースの自然言語から SQL へ (NL2SQL) 機能を使用して、自然言語でデータをクエリできます。

-- 最も注文数の多い上位 10 人の顧客をクエリ
SELECT polar_ai.ai_nl2sql('top 10 customers with the most orders', 'schema_info_index');

この関数は、質問の意図に一致する AI 生成の SQL 文を返します。上記の例では、次のような SQL 文が返されます：

SELECT customer_id, COUNT(*) AS order_count FROM orders GROUP BY customer_id ORDER BY order_count DESC LIMIT 10;

よくある質問