オントロジー
テーブル間の関係とそこに格納されているビジネスエンティティを対応付け、エージェントとAIクエリがビジネスの実態に沿ってデータを結合できるようにします。
オントロジーを使用する理由
テーブル名とカラム名しか見えないAIモデルは、データがどのように関連しているかを推測しなければなりません。crm.accounts.external_refとbilling.customers.idが同じ顧客を指すこと、注文がplaced_byに記載された顧客に属すること、あるいは「Customer」が2つのデータベースにまたがる3つのテーブルに存在することを知ることはできません。
オントロジーには、その知識を一度記述します。
Customer = sales_db.customers (key: id), crm_db.accounts (key: external_ref)
orders.customer_id --[placed by]--> customers.id
エージェントとAIクエリは、カラム名から結合方法を推測するのではなく、テーブルの結合時にこれらの関係を使用します。
概要
オントロジーは、1つ以上のデータベース(および必要に応じてグラフを持つナレッジベース)を対象とする名前付きモデルです。次の3種類の行を保持します。
- 2つのテーブル間のリレーションシップ:結合カラム、各側のカーディナリティ、および「placed by」のような短いビジネスラベル。
- CustomerやOrderなどのビジネスエンティティ:マスターレコードを保持するテーブル(メンバー)と、それらに関する追加の行を保持するテーブル(サポートテーブル)。
date_of_birthなどのエンティティのプロパティ:名前と型を持つビジネスフィールドと、各テーブルでその値を保持するカラム。
すべての行を手動で作成することも、データベーススキーマ、サンプリングされた行、グロッサリーからSquidに生成させることもできます。生成は提案を行うだけです。提案を確認し、必要に応じて変更して保存します。保存されたすべての行は、エージェントとAIクエリに反映されます。
使用する場面
| 状況 | 推奨 |
|---|---|
| 結合が外部キーとして宣言されていない、またはカラム名が分かりにくい | ✅ オントロジー |
| 1つのビジネス概念が複数のテーブルやデータベースにまたがる | ✅ ビジネスエンティティを含むオントロジー |
| ユーザーがビジネス用語(「アクティブな顧客」、「チャーン」)について質問する | グロッサリー |
| スキーマが小さく、外部キーがすべての結合をすでに記述している | 不要:AIクエリは宣言された関連をすでに読み取ります |
クイックスタート
前提条件
- スキーマが検出済みのデータベースコネクタ。
- SquidバックエンドSDK。オントロジーの管理にはアプリのAPIキーが必要なため、バックエンドコードから実行し、executableを通じてフロントエンドに公開してください。
オントロジーAPIはTypeScript SDKで利用できます。
ステップ1:オントロジーを作成して生成する
import { SquidService, executable } from '@squidcloud/backend';
import { AiOntologyGenerationRun } from '@squidcloud/client';
export class OntologyService extends SquidService {
@executable()
async createSalesOntology(): Promise<string> {
const ontologies = this.squid.ai().ontology();
// Creating the ontology stores no rows yet.
const { ontology } = await ontologies.createOntology({
name: 'Sales',
description: 'Customers, the orders they place and the products in them.',
integrationIds: ['sales_db'],
});
// Starts a background run that proposes the content of the ontology. It saves nothing.
await ontologies.generate(ontology.id);
return ontology.id;
}
@executable()
async getGenerationRun(ontologyId: string): Promise<AiOntologyGenerationRun | undefined> {
const ontology = await this.squid.ai().ontology().getOntology(ontologyId);
// status is 'running', 'completed' or 'failed'.
return ontology?.lastGenerationRun;
}
}
ステップ2:生成された提案を保存する
lastGenerationRun.statusがcompletedになったら、提案を読み取り、必要に応じて変更して保存します。
import { SquidService, executable } from '@squidcloud/backend';
export class OntologySaveService extends SquidService {
@executable()
async saveGeneration(ontologyId: string): Promise<number> {
const ontologies = this.squid.ai().ontology();
// The whole content the run proposes: the stored rows with its changes.
const result = await ontologies.getGenerationResult(ontologyId);
if (!result) return 0;
// Drop what you do not want before saving, such as weakly inferred relationships. A stored row you leave out
// is deleted, and every row you leave out is remembered, so generation does not propose it again.
const relationships = result.content.relationships.filter(({ confidence }) => confidence === undefined || confidence >= 0.8);
const { content } = await ontologies.saveContent({
ontologyId,
content: { ...result.content, relationships },
revision: result.revision,
startedOver: result.startedOver,
});
return content.relationships.length;
}
}
代わりに提案を破棄するには、discardGenerationResult(ontologyId)を呼び出します。
ステップ3:エージェントに接続する
データベースに接続されたエージェントにオントロジーをアタッチします。接続されたオントロジーとグロッサリーを参照してください。
基本概念
リレーションシップ
リレーションシップは、from側(参照元テーブル)とto側(参照先テーブル)を結合します。各側には、integrationId、table、結合に使用するcolumns(もう一方の側と位置で対応)、cardinality(ONEまたはMANY)を指定します。
すべてのリレーションシップにはsourceがあります。
| Source | 意味 |
|---|---|
declared | データベーススキーマで宣言された関連からインポート |
inferred | Squidがスキーマに対して推論した関連からインポート |
ai | 生成の実行によって提案 |
human | APIまたはConsoleを通じて人が作成または編集 |
オプションのフィールドでリレーションシップを詳細に指定できます。
conditionは、{ field: 'type', value: 'billing' }のように、カラムが特定の値を持つ行にリレーションシップを制限します。fromEntityIdとtoEntityIdは、各側のビジネスエンティティを指定します。省略すると、Squidは各側について、そのテーブルをメンバーとして持つエンティティを1つ特定し、なければサポートテーブルとして持つエンティティを特定して、resolvedFromEntityIdとresolvedToEntityIdとして返します。confirmationColumnsは、両側の名前など、結合カラムが一致したときに値も一致するはずのカラムのペアです。エージェントにはこれらを比較するよう指示されるため、値が異なるレコードは不一致の可能性があるものとして報告されます。
import { SquidService, executable } from '@squidcloud/backend';
import { AiOntologyRelationship } from '@squidcloud/client';
export class OntologyRelationshipService extends SquidService {
@executable()
async addOrderCustomerRelationship(ontologyId: string): Promise<AiOntologyRelationship> {
return this.squid
.ai()
.ontology()
.createRelationship({
ontologyId,
// Each order points at one customer; a customer places many orders.
from: { integrationId: 'sales_db', table: 'orders', columns: ['customer_id'], cardinality: 'MANY' },
to: { integrationId: 'sales_db', table: 'customers', columns: ['id'], cardinality: 'ONE' },
label: 'placed by',
description: 'The customer who placed the order.',
});
}
}
作成したリレーションシップはすぐに保存されます。両方のテーブルはオントロジーにアタッチされたデータベースに存在し、カラムは存在していて非表示でない必要があります。
ビジネスエンティティ
ビジネスエンティティはCustomerのような概念で、次の要素を持ちます。
members:マスターレコードを保持するテーブル。現実世界の対象1件につき1行を持ち、最も信頼できるテーブルを先頭に指定します。各メンバーには、対象を識別するkeyColumnsを指定します。supportingTables(オプション):対象に関する追加の行を保持するテーブル。それぞれにkindを指定します。detail(注文明細などの子行)、link(別のエンティティとの対応付け)、measurement(時系列の指標)、lookup(小規模なコードまたはステータステーブル)のいずれかです。
import { SquidService, executable } from '@squidcloud/backend';
import { AiOntologyEntity } from '@squidcloud/client';
export class OntologyEntityService extends SquidService {
@executable()
async addCustomerEntity(ontologyId: string): Promise<AiOntologyEntity> {
return this.squid
.ai()
.ontology()
.createEntity({
ontologyId,
name: 'Customer',
description: 'A company that buys from us.',
// The most authoritative table comes first.
members: [
{ integrationId: 'sales_db', table: 'customers', keyColumns: ['id'] },
{ integrationId: 'crm_db', table: 'accounts', keyColumns: ['external_ref'] },
],
supportingTables: [{ integrationId: 'sales_db', table: 'customer_addresses', kind: 'detail' }],
});
}
}
プロパティ
プロパティは、エンティティの名前と型を持つフィールドです。名前はsnake_caseで、プロパティを保持するメンバーテーブルごとに1つのソースカラムを指定します。代わりにサポートテーブルからプロパティを取得することもできますが、その場合はそのカラムが唯一のソースでなければなりません。typeはstring、number、date、boolean、idのいずれかです。分類するにはsensitivity(pii、phi、confidential)を設定し、エージェントとAIクエリに表示しないようにするにはagentVisible: falseを設定します。Squidはsensitivityを保存して表示しますが、それに基づく制限は適用しません。
import { SquidService, executable } from '@squidcloud/backend';
import { AiOntologyProperty } from '@squidcloud/client';
export class OntologyPropertyService extends SquidService {
@executable()
async addSignupDateProperty(customerEntityId: string): Promise<AiOntologyProperty> {
return this.squid
.ai()
.ontology()
.createProperty({
// The id returned by createEntity(). The entity determines the ontology.
entityId: customerEntityId,
name: 'signup_date',
description: 'When the customer first signed up.',
type: 'date',
// One column per member table that holds the property.
sources: [
{ integrationId: 'sales_db', table: 'customers', column: 'created_at' },
{ integrationId: 'crm_db', table: 'accounts', column: 'signup_date' },
],
});
}
}
保存と編集
保存されたすべての行はエージェントとAIクエリに反映されます。行にレビューステータスはありません。保存には2つの方法があります。
- 1行ずつ保存する。
createRelationship()、updateRelationship()、deleteRelationship()、および対応するエンティティとプロパティの呼び出しは、すぐに保存されます。 - 内容全体を保存する。
getContent(ontologyId)は、すべての行をrevisionとともに返します。saveContent({ ontologyId, content, revision })は、送信した内容を1回の書き込みで保存します。変更せずに送り返した行は保持され、新規または変更された行は作成または更新時と同様に検証され、保存済みの行のうち送信内容から除外されたものは削除されます。revisionを読み取ってから誰かがオントロジーを保存した場合、保存はONTOLOGY_CONTENT_CHANGEDエラーで失敗します。
人が行を編集すると、その行のsourceはhumanになり、以降のインポートや生成では変更されません。生成またはインポートされた行を削除したり、保存時に除外したりすると、そのことが記録され、以降の実行では再び提案されません。resetOntology()を実行するか、最初からやり直した実行の結果を保存すると、その記録は消去されます。
オントロジーの生成
generate(ontologyId, options)はバックグラウンドでの実行を開始し、すぐに戻ります。スキーマを読み取り、行をサンプリングし、アタッチされたデータベースのグロッサリーとオントロジーのglossaryIdsに指定されたグローバルグロッサリーを読み取って、リレーションシップ、ビジネスエンティティ、プロパティを提案します。何も保存しません。結果はlastGenerationRunから読み取ります。これにはstatus、提案された項目の件数、warningsが含まれます。
実行がcompletedになると、getGenerationResult(ontologyId)は提案を返します。これには内容全体と、その基になったrevisionが含まれます。そのまま、または編集してからsaveContent()で保存します。結果は1日間保持されますが、保存、discardGenerationResult()、または次の実行によって削除されます。実行開始後にオントロジーが変更された場合、結果の保存はONTOLOGY_CONTENT_CHANGEDエラーで失敗します。再度生成してください。
| オプション | デフォルト | 説明 |
|---|---|---|
mode | update | updateは不足しているものを追加します。regenerateはAIが生成した行を除いてソースを再度読み取り、見つからなくなった行の削除を提案します。再生成を参照してください。 |
usePreviousOntology | true | falseは空の状態から開始し、すべてを再度提案します。その提案を保存すると、手動で作成した行を含むすべての行が置き換えられます。 |
各実行では、アタッチされたデータベーススキーマの関連もリレーションシップとして提案されます。データベースをアタッチしても、実行結果を保存するまでは何も保存されません。人が作成または編集した行の削除が提案されることはありません。
再生成
regenerateの実行では、AIが生成した行を除いてソースを読み取ります。提案には、見つからなくなったAI生成行は含まれず、新たに見つかったものが追加されます。人が作成または編集した行は残ります。結果を保存すると変更が適用され、破棄するとオントロジーはそのまま維持されます。
import { SquidService, executable } from '@squidcloud/backend';
export class OntologyRegenerateService extends SquidService {
@executable()
async regenerate(ontologyId: string): Promise<void> {
await this.squid.ai().ontology().generate(ontologyId, { mode: 'regenerate' });
}
@executable()
async applyRegenerate(ontologyId: string, apply: boolean): Promise<void> {
const ontologies = this.squid.ai().ontology();
const result = await ontologies.getGenerationResult(ontologyId);
if (!result) return;
if (!apply) {
// Removes only this run's result, never a newer one.
await ontologies.discardGenerationResult(ontologyId, result.startedAt);
return;
}
const { content, revision, startedOver } = result;
await ontologies.saveContent({ ontologyId, content, revision, startedOver });
}
}
グロッサリーを使って生成を方向付ける
生成のたびに、アタッチされた各データベースのグロッサリーが読み取られます。グローバルグロッサリーを追加するには、オントロジーの作成時または更新時にglossaryIdsでそのIDを渡します。グロッサリーはコンテキストとしてのみ使用されます。用語が存在するだけでは、生成時に何も提案されません。
import { SquidService, executable } from '@squidcloud/backend';
export class OntologyGlossaryService extends SquidService {
@executable()
async addCompanyGlossary(ontologyId: string): Promise<void> {
await this.squid
.ai()
.ontology()
.updateOntology({
id: ontologyId,
// updateOntology() replaces these three fields, so send their current values too.
name: 'Sales',
description: 'Customers, the orders they place and the products in them.',
integrationIds: ['sales_db', 'crm_db'],
// The ids of global glossaries.
glossaryIds: ['company-vocabulary'],
});
}
}
updateOntology()は名前、説明、アタッチされたデータベースを置き換えます。knowledgeBaseIdsまたはglossaryIdsを省略すると、保存済みのリストが維持されます。データベースを追加しても何も保存されません。次の生成時にそのリレーションシップが提案されます。
オントロジーの使用
- エージェント。 オントロジーをエージェントにアタッチし、そのデータベースを接続します。接続されたオントロジーとグロッサリーを参照してください。
- AIクエリ。 AIクエリのオプションで
ontologyIdsを渡します。指定されたオントロジーのうち、対象のデータベースがアタッチされているすべてのオントロジーのリレーションシップが、通常クエリがスキーマから読み取るリレーションシップに代わって使用されます。
import { SquidService, executable } from '@squidcloud/backend';
import { AiQueryResponse } from '@squidcloud/client';
export class OntologyQueryService extends SquidService {
@executable()
async findFrequentBuyers(ontologyId: string): Promise<AiQueryResponse> {
return this.squid.ai().executeAiQuery('sales_db', 'Which customers placed more than ten orders last month?', {
// The relationships of this ontology guide the joins.
ontologyIds: [ontologyId],
});
}
}
エラー処理
| エラー | 原因 | 対処法 |
|---|---|---|
ONTOLOGY_NOT_FOUND | オントロジーIDが存在しない | listOntologies()を使用してIDを確認する |
ONTOLOGY_GENERATION_RUN_IN_PROGRESS | 実行がすでに進行中、または実行中にソースを変更した | lastGenerationRun.statusがrunningでなくなるまで待つ |
ONTOLOGY_CONTENT_CHANGED | revisionの読み取り後、または実行の開始後にオントロジーが保存された | 内容を再度読み取るか、再生成して変更を適用し直す |
ONTOLOGY_SCHEMA_NOT_FOUND | アタッチされたデータベースのスキーマが検出されていない | Consoleでコネクタのスキーマを検出する |
ONTOLOGY_DATABASE_NOT_ATTACHED | リレーションシップ、エンティティ、またはプロパティが、オントロジーにアタッチされていないデータベースを指定している | updateOntology()でデータベースをintegrationIdsに追加する |
ONTOLOGY_TABLE_NOT_FOUND, ONTOLOGY_COLUMN_NOT_FOUND | テーブルまたはカラムがスキーマに存在しない、または非表示になっている | スキーマと照らし合わせて名前を確認する |
ONTOLOGY_RELATIONSHIP_EXISTS | オントロジーにそれらのカラム間のリレーションシップがすでに存在する | 代わりに既存のリレーションシップを更新する |
ONTOLOGY_PROPERTY_SUPPORTING_SOURCE_ALONE | プロパティがサポートテーブルのソースと他のソースを混在させている | メンバーテーブルのソース、または単一のサポートテーブルのソースのいずれかをプロパティに指定する |
ONTOLOGY_REGENERATE_STARTS_OVER | mode: 'regenerate'とusePreviousOntology: falseを組み合わせた | どちらか一方を使用する |
ONTOLOGY_RELATIONSHIP_LIMIT警告 | 実行がオントロジーあたり2,000件のリレーションシップという上限に達した | アタッチするデータベースを減らすか、コネクタが検出するテーブルを制限する |
実行が失敗すると、lastGenerationRun.statusはfailedに設定され、errorが設定されます。結果は残りません。警告には、実行時に除外されたものが示されます。
ベストプラクティス
- 保存前に確認する。 結果を読み取り、適切でないものを除外して残りを保存します。実行による提案は、保存するまでエージェントに反映されません。
- スキーマの範囲を絞る。 各実行では、アタッチされたすべてのデータベースの関連がすべて提案されます。CRMのように数百のテーブルがあるデータベースでは、コネクタが検出するテーブルをオントロジーの対象にすべきものに制限します。
- 明確な説明を書く。 生成時には、オントロジーの
descriptionがモデル化する範囲として読み取られます。 - 先にグロッサリーを追加する。 グロッサリーの用語は、エンティティやリレーションシップにビジネスで使用している名前を付ける際に役立ちます。
- 非表示にするデータを分類する。 機微なプロパティには
sensitivityを設定し、エージェントに見せてはならないプロパティにはagentVisible: falseを設定します。