ベクトルデータ型

ベクトルは、事前計算済みの埋め込み用の列データ型です。ベクトル列は、行ごとに浮動小数点数の配列を保持します。この配列は、すでにお使いの埋め込みモデルが出力したものです。配列は通常のプロジェクトのテーブルに保存され、それを説明するテキスト、キー、金額、ディメンションと同じ行に置かれます。通常のテーブルの通常の列であるため、ファクトテーブルと結合でき、他の列と同じインポートステップや変換ステップで読み込めます。個別のベクトルストアを用意したり、データを投入したり、他のデータと同期を保ったりする必要はありません。

その後、AI: ベクトル検索ステップが、1つ以上のクエリベクトルに最も近い行を見つけます。類似検索は、他と同じワークフローのステップの1つとして実行できます。

ベクトル列の宣言

ベクトルは、データ型の一覧の半構造化グループに、JSON やビットマップと並んで表示されます。表示される場所は、ワークフローのステップの出力列マッピングと、テーブルの列プロパティです。インポートステップのソースデータ型としては表示されません。ファイルの値は数値のリストとして届き、すでにベクトル型になっている列に格納されます。また、ワークフロー変数の宣言型のように、単一のスカラー型が必要な場所にも表示されません。

この型自体にはディメンションがありません。幅ごとに型を用意するのではなく、ベクトル型は1つだけで、ベクトルの幅は列ごとに宣言します。

ベクトル幅

テーブルの列詳細パネルを開き、ベクトル列を選択して、ベクトル幅に各埋め込みが保持する値の数を設定します。768、1024、1536 など、お使いのモデルが出力する値です。このフィールドは、Lakehouse v2（StarRocks）プロジェクトのベクトル列にのみ表示されます。

宣言した幅は、すべての読み込み経路で適用されます。ベクトルの長さが異なる行は、何も格納される前に拒否されます。拒否メッセージには、ファイル、列、行、検出された長さ、宣言した幅が示されるため、どの値がどれだけ食い違っていたかが正確に分かります。ファイルの読み込みでは、行はファイルの先頭から1で数えられます。これにより、切り詰められたファイルや埋め込みモデルの取り違えが、内容を確認できる失敗した実行として表れます。

このチェックは、埋め込みが届くすべての経路を対象にします。

Parquet のインポート。
REST コネクター（QuickBooks、Xero、Sage、Monday.com を含む）。
Singer タップ。
ソースに対して直接実行するリモートデータベースへのクエリ。
テーブルにフレームを書き込むワークフローのステップ。
アーカイブのインポートまたはアーカイブの復元。拒否メッセージにはアーカイブファイルが示されます。
テーブルバンドルのインポート。バンドルのエクスポートはベクトル列を本物のベクトルとして書き出すため、バンドルを往復させても幅は保たれます。

次の2つは対象外です。

CSV のインポートはチェックされず、チェックすることもできません。 変換によって、幅を調べる前に配列がテキストに変わってしまうため、CSV は、列に異なる幅が入り込みうる唯一の経路です。
行レベルの書き込み（個々の行やレコードの保存、キー付きコネクターによる行の書き込み）は、書き込み時にその列がベクトルであると判断できる場合にチェックされます。これは通常のケースであり、無条件の保証ではありません。

テーブルがベクトルとして型付けしなくなった列に残っている幅は、適用されません。列の型を変更すると、その宣言は列に格納される内容を制御しなくなります。

これが重要なのは、行ごとに幅が異なる列は検索できないためです。そのような列に対するベクトル検索は、列名を示すメッセージではなく、基盤エンジンの生のエラーで失敗します。したがって、埋め込みを CSV で読み込む場合は、宣言した幅になるようにファイルを作成するか、配列を Parquet としてステージングしてからインポートしてください。そうすればチェックが自動的に実行されます。

幅は読み込む前に宣言してください。ベクトル幅には1以上の整数を指定します。空の値に戻すことはできず、フィールドを空にすると保存されている値に戻ります。そのため、この宣言は列の設計の一部として扱ってください。

検索も、この幅に基づいて動作します。幅が宣言されていない列では、検索はクエリと照合する前に、保存されているベクトルの幅を調べるために行をサンプリングする必要があります。

ベクトルの読み込み

ベクトル列は、標準のインポートステップと変換ステップで読み込みます。列が32ビット浮動小数点数のリストである Parquet ファイルが最も直接的な方法で、Parquetのインポートステップなら、ベクトル列にそのまま読み込めます。

すべて標準ステップで構成する、典型的なエンドツーエンドの流れは次のとおりです。

Parquetのインポート（または他のインポートステップ）: 埋め込みとそのビジネスキーを、埋め込み列がベクトル型で、ベクトル幅が宣言されているテーブルに読み込みます。
Table Inner Joinステップ: そのテーブルを、埋め込みが説明するファクトテーブルまたは参照テーブルとビジネスキーで結合します。
AI: ベクトル検索ステップ: クエリベクトルに最も近い行を見つけ、一致した行をターゲットテーブルに書き込みます。
Table Lookupステップ: 表示したい説明用の列を、一致した行に戻します。

ファイルを読み取れる場所

幅をチェックするには、ベクトル列だけを単独で読み取る必要があるため、列単位で読み取れるドキュメントアカウントが必要です。S3、Google Cloud Storage、Azure Blob Storage が該当します。他のドキュメントアカウントから、ベクトル幅が宣言されたテーブルへ Parquet をインポートすると、チェックなしで読み込まれることはなく、拒否されます。そのため、ファイルを S3、Google Cloud Storage、Azure Blob Storage のいずれかにステージングし、そこからインポートしてください。このようなアカウントからのアーカイブの復元も同様です。復元は回復のための操作なので、アーカイブは復元で読み取れるアカウントに保管してください。ベクトル幅が宣言されていないテーブルや、他のインポートステップには影響しません。

最も近い行の検索

AI: ベクトル検索ステップは、検索するテーブル、1つ以上のクエリベクトル、クエリごとに保持する一致件数を受け取り、最も近い行を、各行の順位付けに使った距離とともにターゲットテーブルに書き込みます。

距離の指標は2つあり、どちらも距離が小さいほど近い行です。

コサイン: 2つのベクトルのなす角で、大きさは無視します。テキスト埋め込みでは、これが適切なデフォルトです。
ユークリッド（L2）: 直線距離で、大きさも考慮します。

内積は意図的に提供していません。正規化されていないベクトルでは、内積は距離として成り立たず、ベクトル自身との距離が負になります。そのため、順位がたまたま保たれていても、それに対して設定するしきい値や、ステップが示すスコアは意味を持ちません。正規化された埋め込みでは、コサインで順位付けすれば内積と同じ順序になるため、失うものはありません。

パラメーターの一覧は、AI: ベクトル検索をご覧ください。

検索は近似ではなく厳密

このステップは、フィルターを通過したすべての行を、すべてのクエリベクトルと比較します。ベクトルインデックスも近似もありません。結果は真に最も近い集合であり、処理量は、検索対象の行数にクエリベクトルの数を掛けた分だけ増えます。

それに応じて規模を見積もってください。コーパス全体をスキャンして一部についての問いに答えるのではなく、ステップのフィルターを使って、候補の行を重要な範囲（1つのエンティティ、1つの期間、1つのドキュメントセットなど）に絞り込みます。埋め込みテーブルを、常にフィルターに使うディメンションで分割し、該当するテーブルを検索することが、検索時間を短縮する最も効果的な方法です。

測定できない行は除外される

距離を測定できない行は、最も近い行であるかのように返されるのではなく、一致結果から除外されます。診断モードをオンにしてワークフローを実行すると、各クエリで除外された行数がログに報告されます。すべての行を測定できた場合は、その旨が報告されます。

配列の内部に欠損値があるベクトルが保存されている場合は、スキップされず拒否されます。欠損値を含む配列に対しては距離を測定できないため、部分的な結果を返さずに検索が停止し、列名が示されます。

ベクトル列でできないこと

埋め込みは座標であり、キーでも指標でもありません。そのため、ベクトル列は、そのように扱う役割では拒否されます。

結合キーにはできません。 ベクトルの隣にあるビジネスキーで結合してください。
グループ化の列にはできません。 生の埋め込みで行をグループ化すると、すべての行がそれぞれ独自のグループになります。
集計の対象にはできません。 埋め込みの合計、平均、最小値、最大値には意味がありません。

3つともすべて、列名と役割を示すメッセージとともに拒否されます。拒否は、ステップを保存するときと、以前に保存されたステップを実行するときの両方で行われます。これらのいずれかを含むワークフローは、実行されず、誤った数値を静かに出力することもありません。ベクトルを通常の出力列としてステップ間で引き継ぐことや、行数や一意の値の数を数えることは問題ありません。

ベクトル列は、テーブルエクスプローラーの列プロファイルと値リストからも除外され、ダッシュボードでグラフ化できず、データエディターでは読み取り専用で、ディメンションにリンクすることもできません。最小値、平均、上位の値のリストは、埋め込みについて何も示しません。また、埋め込みは何かのメンバーでもありません。

ベクトル値の読み取り

ベクトル列全体を、プレビュー、エクスポート、MCP 経由の AI アシスタントなどで読み取ると、数値ではなく配列のテキスト表現が返されます。数値として取得するには、要素を個別に読み取ってください。

データグリッドでは、値は幅から始まる短いプレビューとして表示されます（例: 1536-dim [0.013,-0.046,0.079, ...]）。これにより、セルごとに1,000個もの数値を表示せずに、埋め込みの列を読みやすく保てます。