Lance Catalog
これは実験的な機能です。
Lance Catalog は Apache Doris 4.1.4 以降でサポートされています。
Lance は、分析および AI ワークロード向けに設計された列指向データ形式です。Doris は Lance Catalog を使用して Lance Namespace 内のデータベースとテーブルを検出し、ローカルファイルシステム、S3 互換オブジェクトストレージ、または Alibaba Cloud OSS に保存された Lance データセットを直接クエリできます。
現在、Doris から Lance へのアクセスは読み取り専用です。Lance テーブルの作成、書き込み、更新、削除はサポートされていません。
ユースケース
| ユースケース | 説明 |
|---|---|
| Lance データの直接クエリ | データを事前に移行またはインポートせずに、既存の Lance データセットを Doris SQL で分析します。 |
| AI ベクトル検索 | Lance に既存のベクトルインデックスを再利用し、vector_search() で検索して、スカラー条件によるフィルタリングや Doris SQL による分析と組み合わせます。 |
| 全文検索 | Lance に既存の FTS 転置インデックスを再利用し、full_text_search() で BM25 検索して、スカラー条件によるフィルタリングや Doris SQL による分析と組み合わせます。 |
| データ統合 | Lance データを Doris の内部テーブルに読み込み、追加処理、結合、長期保存に利用します。 |
| Namespace 管理 | 単純なディレクトリ構成には Filesystem Catalog を使用します。Namespace、テーブルの場所、一時的なストレージ認証情報を一元管理する必要がある場合は REST Catalog を使用します。 |
機能概要
| 機能 | サポート状況 |
|---|---|
| Filesystem Catalog | ローカルファイルシステム、file://、s3://、oss:// 上のウェアハウスをサポート |
| REST Catalog | 認証なし、Bearer Token、API Key、カスタム HTTP ヘッダーによる Lance REST Namespace をサポート |
| メタデータへのアクセス | SHOW DATABASES、SHOW TABLES、DESC、SHOW INDEX、lance_index_entries TVF をサポート。最後の二つは Filesystem Catalog のみ |
システムテーブル(table$...) | 非サポート。インデックスのメタデータには SHOW INDEX と lance_index_entries TVF を使用 |
| データクエリ | 列のプルーニング、Lance Fragment の並列スキャン、現在のバージョンのスナップショット一貫性を持つ読み取りをサポート |
| 述語プッシュダウン | 互換性のある静的スカラー述語と結合の Runtime Filter を Lance にプッシュダウン可能 |
| ファイル TVF | s3() と local() による Lance データセットの直接クエリをサポート |
| ベクトル検索 | 単一ベクトル列とマルチベクトル列をサポート。物理 Lance インデックスセグメントを並列 Split とし、未カバーの Fragment は Flat Search Split として扱い、Doris でグローバル Top-K をマージ |
| 全文検索 | full_text_search() で既存の Lance FTS 転置インデックスを使用。Match OR/AND と Phrase クエリをサポートし、Doris でグローバル Top-K をマージ |
| Lance Cache | 各 BE 内でインデックスとメタデータのキャッシュ、およびローカルディスク上のデータキャッシュを共有 |
| 二段階 TopN 読み取り | ベクトル検索と全文検索で対象となる出力列についてデフォルトで有効。enable_lance_lazy_materialization で独立して制御 |
| Lance への書き込み | 非サポート |
| Time Travel | REST Namespace がバージョンを管理するテーブルを含め、FOR VERSION AS OF、FOR TIME AS OF、@tag(...)、@branch(...) をサポート |
| Hybrid Search | 非サポート |
Lance のバージョンと互換性
Doris BE のデータリーダーは、マルチベクトル検索のサポートを追加し、組み込みの Lance Rust crate を 11.0.0(コミット ab6b5bbe)に更新する Doris パッチを適用した lance-c v0.1.9 で構築されています。Doris FE は org.lance:lance-core:12.0.0 で Namespace とデータセットのメタデータを読み取ります。FE はメタデータの読み取りのみを行い、データセットには書き込まないため、FE の Lance リリースが新しくても BE が読み取れる範囲は変わりません。データセットは FE によるメタデータ読み込みと BE によるデータ読み取りの両方に対応している必要があります。これらの実装バージョンは、データセットに記録される Lance の data_storage_version とは異なります。
次の表は、このリーダーのファイル形式の互換性を示します。
data_storage_version | 読み取りのサポート | 備考 |
|---|---|---|
0.1 / legacy | サポート | 初期の Lance ファイル形式。 |
2.0(writer-option の別名 0.3) | サポート | Lance v2 ファイル形式の初期バージョン。 |
2.1 / stable | サポート。デフォルトの安定形式 | 組み込み Lance バージョンでは、stable writer option と新しいデータセットのデフォルト形式はどちらも 2.1 になります。 |
2.2 | サポート | 組み込み Lance バージョンでは安定形式として扱われますが、デフォルトの書き込み形式ではありません。 |
2.3 / next | 実験的。動作保証なし | 組み込み Lance バージョンでは 2.3 は不安定な形式であり、next writer option は 2.3 になります。 |
| それ以降または不明なバージョン | 非サポート | データセットを開くかスキャンすると、ストレージバージョン非対応のエラーが発生する場合があります。 |
Lance SDK のリリース番号とファイル形式のバージョンは独立しています。古いまたは新しい Lance SDK で書き込まれたデータセットでも、そのストレージ形式、必須のテーブル機能フラグ、インデックス形式、Arrow/Lance データ型のすべてを Doris 組み込みのバージョンが理解できる場合に限り読み取れます。したがって、次の点に注意してください。
- Doris は、以下に記載する型の制限を満たす場合、
0.1、2.0、2.1、2.2のストレージ形式で書き込まれたデータセットを読み取れる見込みです。 - 将来のバージョンとの互換性は保証されません。新しい Lance リリースで書き込みまたは変更されたデータセットが、新しいストレージ形式、不明な必須 manifest 機能、新しいインデックス形式、未サポートの拡張型を使用している場合は読み取れないことがあります。
- この Doris リリースで継続して読み取る必要があるデータセットには、現在のデフォルト安定形式
2.1を使用し、nextは使用しないでください。新しい writer やオプションの Lance 機能を導入した場合は、本番利用前に対象の Doris リリースで生成されたデータセットを検証してください。
Catalog の設定
構文
CREATE CATALOG [IF NOT EXISTS] catalog_name PROPERTIES (
"type" = "lance",
"lance.catalog.type" = "<filesystem|rest>",
{CatalogProperties},
{StorageProperties},
{CommonProperties}
);
共通プロパティ
| プロパティ | 必須 | デフォルト | 説明 |
|---|---|---|---|
type | はい | - | lance にする必要があります。 |
lance.catalog.type | いいえ | filesystem | Catalog の種類。有効な値は filesystem と rest です。 |
lance.namespace.parent | いいえ | 空 | 指定した Lance Namespace とその子 Namespace にアクセスを限定します。たとえばデフォルトの区切り文字では、production$analytics は二階層の Namespace を表します。 |
lance.namespace.delimiter | いいえ | $ | lance.namespace.parent の解析に使用する区切り文字です。REST Namespace クライアントにも渡されます。このプロパティは、Doris における多階層 Namespace の表示方法を変更しません。 |
lance.namespace.root_database | いいえ | default | ルート Lance Namespace が対応付けられる Doris データベース名。 |
lance.table_access_cache_ttl_seconds | いいえ | 60 | 非負の整数。FE のテーブルアクセスキャッシュの最長存続時間を秒単位で指定します。0 は無効化です。Filesystem Catalog と REST Catalog に適用されます。Namespace がバージョンを管理するテーブル、および提供されたストレージオプションや認証情報を含む URI が返された結果はキャッシュしません。FE テーブルアクセスキャッシュを参照してください。 |
Filesystem Catalog
Filesystem Catalog は、ウェアハウスディレクトリから Lance Namespace とテーブルを直接検出します。
| プロパティ | 必須 | 説明 |
|---|---|---|
warehouse | はい | Lance ウェアハウスのルートパス。ローカルの絶対パス、file:// URI、s3:// URI、oss:// URI をサポートします。 |
次の二つのプロパティは役割が異なります。
fs.s3.support=trueは、S3 設定の解析を明示的に選択します。AWS S3 は通常、プロパティから検出できます。MinIO、カスタムエンドポイント、S3 互換 API 経由の OSS では、検出の失敗やドメインに基づく別のストレージ種別の選択を避けるため、明示的に設定してください。以下の S3 の例はすべて、このプロパティを含みます。use_path_styleはリクエスト URL 内のバケットの位置を制御し、デフォルトはfalseです。trueにするとendpoint/bucket/object-pathを使用し、falseにすると仮想ホスト形式でアクセスします。現在 Lance でデフォルトの S3 クライアントを使用する場合、明示的に設定する仮想ホスト形式のエンドポイントにはバケットを含める必要があります。サービスがサポートするアクセス方式に合わせ、エンドポイントとともにこのプロパティを設定してください。
| アクセス先 | ストレージ種別の設定 | use_path_style | エンドポイントの形式 |
|---|---|---|---|
| AWS S3 | fs.s3.support=true を推奨 | false。省略可能 | https://my-bucket.s3.us-east-1.amazonaws.com のようにバケットを含めます。 |
| MinIO(サービスドメインまたは IP 経由) | fs.s3.support=true を設定 | true を明示的に設定 | http://minio.example.com:9000 のようにバケットを含まないサービスアドレス。 |
| OSS S3 互換 API | fs.s3.support=true を設定 | false。例では明示的に設定 | https://my-bucket.oss-cn-beijing.aliyuncs.com のようにバケットを含めます。 |
| ネイティブ OSS API | fs.oss.support=true を推奨。fs.s3.support は設定しない | 汎用の use_path_style は設定不要 | oss.endpoint に、https://oss-cn-beijing.aliyuncs.com のようなバケットを含まない値を使用します。 |
これらの S3 エンドポイント規則は、Lance のデフォルトの S3 アクセス経路に適用されます。一種類のストレージを使用する Filesystem Catalog では、対応する fs.*.support=true だけを設定してください。「互換性を有効にする」ために複数のストレージ種別を有効にしないでください。このプロパティは設定の解析方法を選択するもので、ストレージサービスにプロトコルサポートを追加しません。
ウェアハウスのストレージに合う例を選び、バケット、パス、アドレス、認証情報を置き換えてください。
- AWS S3
- MinIO(パス形式)
- Alibaba Cloud OSS(S3 互換アクセス)
- Alibaba Cloud OSS(ネイティブアクセス)
- ローカルファイルシステム
CREATE CATALOG lance_fs_s3 PROPERTIES (
"type" = "lance",
"lance.catalog.type" = "filesystem",
"warehouse" = "s3://my-bucket/lance",
"fs.s3.support" = "true",
"use_path_style" = "false",
"s3.endpoint" = "https://my-bucket.s3.us-east-1.amazonaws.com",
"s3.region" = "us-east-1",
"s3.access_key" = "<ak>",
"s3.secret_key" = "<sk>"
);
この例では、バケットを含む AWS S3 エンドポイントを use_path_style=false とともに使用します。現在の Doris の S3 プロパティ検証ではエンドポイントが必須です。ここに示す s3://my-bucket/... URI を使用する場合、リージョンだけでは不十分です。バケットまたはリージョンを変更したときは、エンドポイントも更新してください。
CREATE CATALOG lance_fs_minio PROPERTIES (
"type" = "lance",
"lance.catalog.type" = "filesystem",
"warehouse" = "s3://my-bucket/lance",
"fs.s3.support" = "true",
"s3.endpoint" = "http://minio.example.com:9000",
"s3.region" = "us-east-1",
"use_path_style" = "true",
"s3.access_key" = "<ak>",
"s3.secret_key" = "<sk>"
);
この例ではパス形式のリクエストで MinIO のサービスドメインにアクセスするため、バケットごとのサブドメインは不要です。エンドポイントにバケットを含めず、リージョンはサービスに設定された値に置き換えてください。TLS が有効な場合は対応する https:// エンドポイントを使用し、FE とすべての BE から到達できることを確認してください。
S3 互換 API 経由で OSS にアクセスするには、s3:// ウェアハウスと s3.* 接続プロパティを使用します。
CREATE CATALOG lance_fs_oss_s3 PROPERTIES (
"type" = "lance",
"lance.catalog.type" = "filesystem",
"warehouse" = "s3://my-bucket/lance",
"fs.s3.support" = "true",
"s3.endpoint" = "https://my-bucket.oss-cn-beijing.aliyuncs.com",
"s3.region" = "cn-beijing",
"use_path_style" = "false",
"s3.access_key" = "<ak>",
"s3.secret_key" = "<sk>"
);
この例では、仮想ホスト形式のアクセスに use_path_style=false を設定します。現在 Lance のデフォルト S3 クライアントは、明示的に設定したエンドポイントにバケットを自動追加しません。そのため、s3.endpoint には https://my-bucket.oss-cn-beijing.aliyuncs.com のようにバケットを含め、warehouse は s3://my-bucket/lance のままにしてください。内部ネットワークからアクセスする場合は https://my-bucket.oss-cn-beijing-internal.aliyuncs.com を使用し、FE と BE の両方から到達できることを確認してください。
一時的な STS 認証情報を使用する場合は、"s3.session_token" = "<token>" を追加します。この方式では、データを移動せずに S3 互換 API 経由で既存の OSS データを読み取ります。ネイティブ OSS アクセスについては、隣の例を参照してください。
CREATE CATALOG lance_fs_oss PROPERTIES (
"type" = "lance",
"lance.catalog.type" = "filesystem",
"warehouse" = "oss://my-bucket/lance",
"fs.oss.support" = "true",
"oss.endpoint" = "https://oss-cn-beijing.aliyuncs.com",
"oss.region" = "cn-beijing",
"oss.access_key" = "<ak>",
"oss.secret_key" = "<sk>"
);
一時的な STS 認証情報を使用する場合は、"oss.session_token" = "<token>" を追加します。完全修飾形式の oss://my-bucket.oss-cn-beijing.aliyuncs.com/lance も受け付けられ、バケットパスに正規化されます。OSS-HDFS は現在サポートされていません。
CREATE CATALOG lance_fs_local PROPERTIES (
"type" = "lance",
"lance.catalog.type" = "filesystem",
"warehouse" = "/data/lance"
);
warehouse は絶対パスである必要があります。FE とクエリを実行するすべての BE が同じパスにアクセスできなければなりません。複数ノードの構成では、関連するすべてのノードに同じ共有ディレクトリをマウントしてください。
S3 と OSS では、warehouse に s3://bucket/path または oss://bucket/path のようにバケットを含める必要があります。
REST Catalog
REST Catalog は Lance REST Namespace を通じて Namespace、テーブルの場所、ストレージアクセスパラメータを取得します。REST Catalog では warehouse プロパティは不要であり、指定もできません。
| プロパティ | 必須 | デフォルト | 説明 |
|---|---|---|---|
lance.rest.uri | はい | - | REST サービスの URI。http:// または https:// を使用する必要があります。 |
lance.rest.security.type | いいえ | none | 認証の種類。有効な値は none、bearer、api_key です。 |
lance.rest.bearer-token | Bearer 認証の場合は必須 | - | Bearer Token。 |
lance.rest.api-key | API Key 認証の場合は必須 | - | x-api-key ヘッダーで送信する API Key。 |
lance.rest.header.<header-name> | いいえ | - | REST サービスへ送信するカスタム HTTP ヘッダー。認証ヘッダーには上記の専用認証プロパティを使用してください。 |
REST サービスの認証とオブジェクトストレージの認証は別です。lance.rest.* は Namespace サービスへの接続に使用し、s3.* / oss.* は FE と BE によるテーブルデータの読み取りに使用します。アクセス経路は Namespace が返すテーブル URI で決まり、s3:// は S3、oss:// はネイティブ OSS アクセスを使用します。返されるテーブル URI に応じてデフォルトのストレージプロパティを選択してください。
- AWS S3
- MinIO(パス形式)
- Alibaba Cloud OSS(S3 互換アクセス)
- Alibaba Cloud OSS(ネイティブアクセス)
CREATE CATALOG lance_rest_s3 PROPERTIES (
"type" = "lance",
"lance.catalog.type" = "rest",
"lance.rest.uri" = "https://lance.example.com",
"lance.rest.security.type" = "bearer",
"lance.rest.bearer-token" = "<token>",
"fs.s3.support" = "true",
"use_path_style" = "false",
"s3.endpoint" = "https://my-bucket.s3.us-east-1.amazonaws.com",
"s3.region" = "us-east-1",
"s3.access_key" = "<ak>",
"s3.secret_key" = "<sk>"
);
Namespace が返す AWS の s3://my-bucket/... テーブル向けです。デフォルトのエンドポイントにはそのバケットを含め、リージョンを一致させる必要があります。異なるバケットのテーブルには、後述のように対応するエンドポイントが必要です。
CREATE CATALOG lance_rest_minio PROPERTIES (
"type" = "lance",
"lance.catalog.type" = "rest",
"lance.rest.uri" = "https://lance.example.com",
"lance.rest.security.type" = "bearer",
"lance.rest.bearer-token" = "<token>",
"fs.s3.support" = "true",
"s3.endpoint" = "http://minio.example.com:9000",
"s3.region" = "us-east-1",
"use_path_style" = "true",
"s3.access_key" = "<ak>",
"s3.secret_key" = "<sk>"
);
Namespace が返す MinIO の s3:// テーブル向けです。FE と BE の両方から到達できる、バケットを含まないサービスエンドポイントを使用します。use_path_style=true により、各テーブルのバケットがリクエストパスに入ります。リージョンは MinIO サービスの設定と一致させてください。
CREATE CATALOG lance_rest_oss_s3 PROPERTIES (
"type" = "lance",
"lance.catalog.type" = "rest",
"lance.rest.uri" = "https://lance.example.com",
"lance.rest.security.type" = "bearer",
"lance.rest.bearer-token" = "<token>",
"fs.s3.support" = "true",
"s3.endpoint" = "https://my-bucket.oss-cn-beijing.aliyuncs.com",
"s3.region" = "cn-beijing",
"use_path_style" = "false",
"s3.access_key" = "<ak>",
"s3.secret_key" = "<sk>"
);
Namespace が返す s3://my-bucket/... テーブルへ OSS の S3 互換 API 経由でアクセスする場合の設定です。エンドポイントには同じバケットを含める必要があります。内部ネットワークでは https://my-bucket.oss-cn-beijing-internal.aliyuncs.com を使用します。Namespace は s3:// URI を返す必要があります。fs.s3.support=true を設定しても、返された oss:// URI が S3 アクセスに切り替わることはありません。
CREATE CATALOG lance_rest_oss PROPERTIES (
"type" = "lance",
"lance.catalog.type" = "rest",
"lance.rest.uri" = "https://lance.example.com",
"lance.rest.security.type" = "bearer",
"lance.rest.bearer-token" = "<token>",
"fs.oss.support" = "true",
"oss.endpoint" = "https://oss-cn-beijing.aliyuncs.com",
"oss.region" = "cn-beijing",
"oss.access_key" = "<ak>",
"oss.secret_key" = "<sk>"
);
Namespace が返す oss:// テーブルへネイティブ OSS でアクセスする場合の設定です。oss.endpoint にバケットを含めないでください。一時的な STS 認証情報を使用する場合は、"oss.session_token" = "<token>" を追加します。
認証なしの REST アクセスでは、lance.rest.security.type と認証プロパティを省略します。API Key 認証では、これらを "lance.rest.security.type" = "api_key" と "lance.rest.api-key" = "<api-key>" に置き換えます。
REST Namespace が各テーブルの storage_options で認証情報またはエンドポイントを提供する場合、Doris はオプションごとに対応する Catalog のデフォルト値を上書きし、統合した設定を FE と BE の両方で使用します。認証情報のみが提供される場合、Catalog のエンドポイントとアクセス形式は引き続き適用されます。Namespace が完全なアクセス設定を提供する場合に限り、Catalog のストレージプロパティをすべて省略できます。
S3 について Namespace は、aws_endpoint、aws_region、aws_access_key_id、aws_secret_access_key、aws_session_token、aws_virtual_hosted_style_request を使用できます。最後のオプションは Doris の use_path_style と逆です。仮想ホスト形式では aws_virtual_hosted_style_request=true、パス形式では false を使用します。fs.s3.support は Doris Catalog のプロパティであり、Lance の storage_options パラメータではありません。
ネイティブ OSS アクセスについて Namespace は、oss_endpoint、oss_access_key_id、oss_secret_access_key、oss_region、oss_security_token、または対応するネイティブ名 endpoint、access_key_id、access_key_secret、region、security_token を提供できます。
テーブルが異なるバケットにある場合、例の my-bucket に固定した S3 仮想ホスト形式のエンドポイントを共有しないでください。Namespace から各テーブルに一致するエンドポイントとアクセス形式を提供するか、バケットごとに Catalog を設定してください。パス形式をサポートするサービスでは、バケットを含まないサービスエンドポイントと use_path_style=true を使用し、各テーブル URI からバケットを読み取らせることもできます。
REST Namespace がテーブルのバージョンを管理する場合(DescribeTable の managed_versioning = true)、Doris は Namespace のバージョン API で最新バージョンと Time Travel セレクターを解決し、対応する manifest をストレージから読み取ります。詳細と制限は Time Travel を参照してください。
Namespace のマッピング
Lance は多階層 Namespace をサポートしますが、Doris Catalog では各 Namespace をデータベース名として表します。
| Lance Namespace | Doris データベース名 |
|---|---|
| ルート Namespace | default。lance.namespace.root_database で設定可能 |
doris | doris |
doris.analytics | doris.analytics |
Doris は多階層 Namespace の各階層を . で連結してデータベース名にします。. を含むデータベース名を参照する際は、バッククォートを使用します。
SHOW TABLES FROM lance_catalog.`doris.analytics`;
SELECT *
FROM lance_catalog.`doris.analytics`.user_features;
lance.namespace.parent を使用すると、Catalog を Namespace の部分木に限定できます。例を示します。
CREATE CATALOG lance_analytics PROPERTIES (
"type" = "lance",
"lance.catalog.type" = "filesystem",
"warehouse" = "s3://my-bucket/lance",
"lance.namespace.parent" = "production$analytics",
"fs.s3.support" = "true",
"s3.endpoint" = "https://my-bucket.s3.us-east-1.amazonaws.com",
"use_path_style" = "false",
"s3.region" = "us-east-1",
"s3.access_key" = "<ak>",
"s3.secret_key" = "<sk>"
);
この場合、Doris は production.analytics の下にあるテーブルと子 Namespace のみを表示します。
Lance テーブルのクエリ
Catalog を作成した後は、ほかの外部テーブルと同じように Lance テーブルを参照し、クエリできます。
SHOW DATABASES FROM lance_catalog;
SHOW TABLES FROM lance_catalog.default;
DESC lance_catalog.default.user_profiles;
SELECT user_id, name, age
FROM lance_catalog.default.user_profiles
WHERE age >= 18
ORDER BY user_id
LIMIT 100;
Lance のデータを Doris の内部テーブルへロードすることもできます。
INSERT INTO internal.demo.user_profiles
SELECT user_id, name, age
FROM lance_catalog.default.user_profiles;
通常の Catalog クエリでは、Doris は計画時に Lance データセットのバージョンを固定し、Fragment ごとにスキャンタスクを生成します。このためクエリは一貫したスナップショットを読み取り、複数の Scanner はそれぞれ異なる Fragment を並列に読み取れます。各 Scanner がデータセット全体を繰り返しスキャンすることはありません。
Time Travel
Lance データセットへのコミットごとに新しいバージョンが作成され、番号は 1 から始まります。クエリでは最新バージョンの代わりに過去のバージョンを読み取れます。
-- Read version 2 of the table.
SELECT * FROM lance_catalog.db.tbl FOR VERSION AS OF 2;
-- Read the latest version committed at or before the given time.
SELECT * FROM lance_catalog.db.tbl FOR TIME AS OF '2026-09-19 13:06:10';
FOR VERSION AS OFには正の整数のバージョン番号を指定します。Paimon テーブルや Iceberg のタグ名と同様に、引用符で囲んだタグ名も指定できます(FOR VERSION AS OF 'v2'は@tag(v2)と同じです)。FOR TIME AS OFには、セッションのタイムゾーンで秒またはミリ秒精度のタイムスタンプ(yyyy-MM-dd HH:mm:ssまたはyyyy-MM-dd HH:mm:ss.SSS)を指定します。Doris は指定時刻以前にコミットされたバージョンのうち、manifest に記録されたコミット時刻が最も遅いものを選びます。同時刻の場合は新しいバージョンを選びます。Iceberg の時刻によるスナップショット選択と同様に、コミット時刻は記録どおりに比較し、バージョン番号とともに増加するとは仮定しません。Lance はミリ秒未満の精度でコミット時刻を記録し、比較にはその全精度を使用します。指定したミリ秒内でも、指定時刻より後にコミットされたバージョンは選ばれません。cleanup で削除されたバージョンのコミット時刻も失われます。そのため、Iceberg が期限切れスナップショットより前の snapshot log を破棄するのと同様に、Doris は最後に削除されたバージョンより新しいバージョンだけを対象にします。それらすべてより前のタイムスタンプはエラーです。最初のバージョンより前か、cleanup で削除された履歴の範囲内(たとえばタグによって保持されたバージョンと、その次に残るバージョンの間)に該当し、その時点のテーブル状態が不明なためです。- 選択したバージョンは文全体で固定されます。スキーマ、Fragment の計画、述語プッシュダウン、BE のスキャンはすべてそのバージョンを使用します。同じ文で同じテーブルを二度参照する場合、それぞれ異なるバージョンを選択できます。
EXPLAINは選択したバージョンをlanceVersionとして表示します。 - Lance の
cleanup_old_versionsで削除されたバージョンは読み取れず、存在したことのないバージョンと同じように報告されます。REST Namespace がバージョンを管理するテーブルについては、後述の「REST Namespace が管理するバージョン」を参照してください。 vector_search()とfull_text_search()は、それぞれのversion、timestamp、tag、branchパラメータでバージョン、時刻、タグ、ブランチを選択します。過去のバージョンまたはブランチの検索を参照してください。これらのtable引数にFOR VERSION AS OF、@tag、@branchを含めることはできません。- インデックスの確認(
SHOW INDEX、lance_index_entries())は常にmainの最新バージョンを使用し、過去のバージョンやブランチのインデックスは表示しません。
Lance のタグとブランチは、Iceberg および Paimon テーブルと同じ構文で選択します。
-- Read the version the tag "v2" points at.
SELECT * FROM lance_catalog.db.tbl@tag(v2);
-- Read the latest version of the branch "dev".
SELECT * FROM lance_catalog.db.tbl@branch(dev);
-- Read version 2 of the branch "dev".
SELECT * FROM lance_catalog.db.tbl@branch(dev) FOR VERSION AS OF 2;
- タグはブランチ上のバージョンを指し、タグの読み取りではそのブランチのそのバージョンを選びます。
dev上で作成されたタグは、mainの同じ番号のバージョンではなくdevを読み取ります。@tagとFOR VERSION AS OFまたはFOR TIME AS OFは併用できません。 @branch(main)はmainを読み取ります。@branchを省略した場合と同じです。- 各ブランチは、作成元のバージョンから始まる独自のバージョン列を持ちます。
@branchの後のFOR VERSION AS OF/FOR TIME AS OFはそのブランチのバージョンだけから選択するため、ブランチ作成前のタイムスタンプでは何も選ばれません。@branch(main)を含め、@branchの後ではFOR VERSION AS OFにタグ名を指定できません。タグ自体がブランチを決めるためです。 - ブランチは
<table>/tree/<branch>/に、テーブルの shallow clone として保存され、その manifest はテーブルの場所を絶対 URI で記録します。そのため、ブランチは作成した場所でのみ読み取れます。データセットを別の場所へコピーまたは移動するとmainは引き続き読み取れますが、ブランチは読み取れません。 - ブランチのメタデータが削除された場合や作成が途中で止まった場合でも、Lance SDK はディレクトリからブランチをチェックアウトするため、
tree/以下のディレクトリが削除されるまでは@branchで読み取れます。REST Namespace がバージョンを管理するテーブルでは、ブランチの存在は Namespace が判断し、mainを読み取らずにブランチのディレクトリから読み取ります。 EXPLAINは読み取るブランチをlanceBranchとして表示します。存在しないタグまたはブランチはエラーです。
REST Namespace が管理するバージョン
REST Namespace はテーブルのバージョンを自ら管理できます(DescribeTable 応答の managed_versioning = true)。そのようなテーブルでは、どのバージョンが存在し、どれが最新かを Namespace が決定します。最新バージョンと FOR VERSION AS OF は Namespace の記録(ListTableVersions、DescribeTableVersion)に従います。FOR TIME AS OF は manifest のコミット時刻に基づき、Namespace が列挙したバージョンからのみ選択します。タグは通常の Lance テーブルと同様にデータセットの _refs/tags/ から読み取り、Namespace に記録されたバージョンを指している必要があります。ブランチのバージョンも Namespace に従います。バージョンの選択後、FE と BE はほかの Lance テーブルと同様に、テーブルの場所とバージョン番号を使用してストレージから読み取ります。
- manifest がストレージに残っていても、Namespace に記録されていないバージョンは見つからないものとして報告されます。ストレージにさらに新しい manifest が存在しても、最新バージョンは Namespace の記録に従います。
- Namespace の記録から消えたバージョンが、記録されたバージョンの間にある場合、
FOR TIME AS OFでは cleanup で削除されたバージョンと同様、削除された履歴として扱います。そのバージョンが該当しうるタイムスタンプは、古いバージョンを選ぶ代わりにエラーになります。 - テーブルまたはブランチについて Namespace がバージョンを記録していない場合、ストレージに manifest があってもエラーです。
- これらのテーブルでは、
EXPLAINにlanceManagedVersioning=trueが表示されます。
制限事項:
- Doris は
DescribeTableが返したtable_uri、またはtable_uriがない場合はlocationのデータセットを読み取ります。どちらも完全なストレージ URI である必要があります。locationが空の場合、あるいは併せて返されたtable_uriが別の場所を指す場合(署名付き認証情報などのクエリ文字列は除く)、クエリはエラーになり、データは読み取られません。s3+ddbURI も拒否されます。DynamoDB コミットハンドラーが読み取り時にバージョンを記録し確定するためです。Doris は管理対象テーブルをキャッシュせず、読み取りごとに記述情報を取得します。FE と BE はその応答の場所とストレージ設定を使用します。 - Doris はバージョン番号を使い、テーブルディレクトリ内の正規パス
_versions/<u64::MAX - version>.manifest(ブランチの場合はtree/<branch>/内)、または Lance の旧命名方式の_versions/<version>.manifestからバージョンを読み取ります。Namespace が選択バージョンに記録する manifest は、このパスまたはその隣のステージ済み manifest(<canonical path>-<id>)である必要があります。FOR TIME AS OFではコミット時刻で選択するため、そのmainまたはブランチに記録されたすべてのバージョンの manifest についても同じ条件が適用されます。ほかの場所に記録されたバージョンは読み取れず、クエリは記録されたパスと正規パスを示すエラーで失敗します。クエリ実行中に Namespace がテーブルを移動した場合も同じエラーが起こりえますが、再試行すると成功します。 - Namespace がステージ済み manifest にのみ記録し、正規の manifest が存在しないバージョンは読み取れません。コミットが確定していないか、cleanup によってバージョンが削除されたためです。クエリは両方の原因を示して失敗します。コミット時刻が不明なため、その
mainまたはブランチに対するFOR TIME AS OFは、そのバージョンが該当しうるタイムスタンプで失敗します。それが最新バージョンであれば、writer または Namespace を使用する別の reader が確定するまで、すべてのタイムスタンプで失敗します。この場合、FOR VERSION AS OFを指定しない読み取りとスキーマ読み込みも失敗します。Lance 自身の Namespace 実装はバージョンを記録する前に確定するため、未確定のバージョンが現れるのは、コミットが中断された場合か、Namespace がステージ済み manifest を記録する場合だけです。Doris は読み取り時にテーブルへ書き込みません。
Lance インデックスの確認
Filesystem Catalog 内のテーブルでは、SHOW INDEX に Lance データセットに記録された論理スカラーインデックス(FTS 転置インデックスを含む)とベクトルインデックスが表示されます。別構文の SHOW INDEXES、SHOW KEY、SHOW KEYS でも同じ結果が得られます。
SHOW INDEX FROM lance_catalog.default.items;
Doris は実行時に最新のデータセットスナップショットからインデックスのメタデータを読み取り、インデックス名と列位置で結果を並べ替えます。__lance_frag_reuse や __lance_mem_wal など、Lance が内部で管理するシステムインデックスは表示されません。インデックスのないテーブルは空の結果を返します。
SHOW INDEX は標準の 13 列の結果セットを返します。Lance テーブルで値が入るのは次の列のみで、ほかの列は常に空です。
| 列 | Lance テーブルでの値 |
|---|---|
Table | テーブル名。 |
Key_name | Lance の論理インデックス名。 |
Seq_in_index | インデックス内の列の位置。1 から始まります。複数フィールドのインデックスはフィールドごとに一行を返します。 |
Column_name | インデックス対象のフィールド。ネストされたフィールドでは . で連結したフィールドパスを表示し、英数字と _ 以外の文字を含むパス要素は、たとえば attributes.`child.with.dot` のようにバッククォートで囲みます。 |
Index_type | Lance SDK が報告するインデックス種別。BTree、INVERTED、IVF_FLAT、IVF_SQ、IVF_PQ、IVF_HNSW_FLAT、IVF_HNSW_SQ、IVF_HNSW_PQ など。 |
Properties | 固定のインデックス詳細項目を持つ JSON オブジェクト。最上位の metric_type と target_partition_size、compression 内の type、num_bits、num_sub_vectors、rotation_type、hnsw 内の construction_ef、max_connections、max_level を含みます。キーはソートされ、詳細にこれらの項目がない場合は {} です。 |
次の行は IVF_PQ ベクトルインデックスと、ネストされたフィールドの BTree インデックスの例です。
Table Key_name Seq_in_index Column_name Index_type Properties
vs_ivf_pq_f32 embedding_ivf_pq_f32 1 embedding IVF_PQ {"compression":{"num_bits":4,"num_sub_vectors":4,"type":"pq"},"metric_type":"L2"}
nested_index nested_label_btree 1 attributes.`child.with.dot` BTree {}
SHOW INDEX は既存のインデックスを確認するだけで、作成しません。Lance インデックスは Doris の外部で Lance SDK または別の Lance writer を使用して作成してください。記録されたインデックスのメタデータに不整合がある場合、たとえば存在しないフィールドを参照したり、複数のインデックス名が完全に一致したりすると、部分的なメタデータを返さずに文全体が失敗します。
SHOW INDEX にはテーブルの SHOW 権限が必要です。REST Catalog では、SHOW INDEX is not supported for Lance REST catalogs エラーで拒否されます。
lance_index_entries による物理インデックスエントリの一覧表示
lance_index_entries は Apache Doris 4.1.5 以降でサポートされています。
SHOW INDEX は Lance テーブルのインデックスを、インデックス名、対象列、種別、プロパティからなる論理ビューとして、固定の MySQL 形式の 13 列の結果セットで示します。物理インデックスエントリの識別情報である UUID とデータセットバージョンは、その固定スキーマには収まりません。読み取り専用のテーブル値関数 lance_index_entries は、この物理ビューを提供します。最新のデータセットスナップショットに記録された物理インデックスエントリごとに一行を返します。
SELECT *
FROM lance_index_entries("table" = "lance_catalog.default.vs_ivf_pq_f32");
table は完全修飾された三要素の catalog.database.table 名である必要があります。識別子にはバッククォートを使用できます。多階層 Namespace が . を含むデータベース名にマッピングされる場合は、データベース部分をバッククォートで囲んでください。
TVF は次の固定列を返します。
| 列 | 型 | 説明 |
|---|---|---|
CatalogName | STRING | Catalog 名。 |
DatabaseName | STRING | データベース名。 |
TableName | STRING | テーブル名。 |
IndexName | STRING | Lance の論理インデックス名。異なる UUID の物理エントリを複数持つ論理インデックスは複数行になります。 |
IndexUuid | STRING | この物理インデックスエントリの UUID。 |
DatasetVersion | BIGINT | この物理インデックスエントリに記録されたデータセットバージョン、つまりエントリを書き込んだときのバージョン。同じ論理インデックスの物理エントリが異なるデータセットバージョンを持つことがあります。値は常に 1 以上です。 |
次の行は、前述の IVF_PQ インデックスの結果例です。IndexUuid と DatasetVersion は説明用の値です。
CatalogName DatabaseName TableName IndexName IndexUuid DatasetVersion
lance_catalog default vs_ivf_pq_f32 embedding_ivf_pq_f32 3f9c2a1e-7b4d-4e6f-9a1c-2d5e8f0b3a47 12
lance_index_entries は Dataset.getIndexes() を通じてインデックスのメタデータだけを読み取ります。行数や統計情報は読み取らず、データセットも変更しません。結果には WHERE IndexName = ... のような通常の述語でフィルタをかけられます。行は (IndexName, IndexUuid) でソートされます。読み取りは完全に検証され、エラーがあれば全体が失敗します。空白または長すぎる名前、UUID の欠落、正でない DatasetVersion、重複 UUID、生のエントリ数が 16,384 を超える場合には、結果を切り詰めずにクエリ全体が失敗します。Lance が内部で管理する予約済みシステムインデックス __lance_frag_reuse と __lance_mem_wal は検証されますが、表示されません。
lance_index_entries にはテーブルの SHOW 権限が必要です。REST Catalog では、lance_index_entries is not supported for Lance REST catalogs エラーで拒否されます。
型のマッピング
Doris 4.2 の完全なマッピング表、精度に関する規則、未サポートの型については、Lance から Doris へのデータ型マッピングを参照してください。
述語プッシュダウン
Doris は意味的に互換性のある述語を Substrait 式に変換し、読み取り時の評価のために Lance に渡します。条件全体がプッシュダウンされた場合、Doris BE はその条件を再評価しません。安全にプッシュダウンできない条件は Doris 側に残ります。
プッシュダウン対応のデータ型
| Lance / Arrow 型 | プッシュダウンのサポート |
|---|---|
bool | 等価比較、NULL 判定、論理演算。大小比較は非サポート |
int8/16/32/64 | サポート |
uint8/16/32/64 | サポート |
float32/64 | サポート |
decimal128 | Precision は 1 から 38、Scale は 0 から Precision |
utf8、large_utf8 | サポート |
date32(day) | サポート |
タイムゾーンを持たない timestamp(s/ms/us) | サポート |
list<utf8> | NULL でない文字列リテラルを使う組み込みの array_contains。配列ラベル述語を参照 |
そのほかの読み取り可能な型に対する述語は、現在 Doris 側に残ります。これには float16、decimal256、Binary、date64、Time、ナノ秒精度の Timestamp、タイムゾーン付き Timestamp、および上記の配列包含判定以外の複合型が含まれます。
プッシュダウン対応の演算子
| SQL 述語 | プッシュダウンの条件 |
|---|---|
=、!=、<>、<、<=、>、>= | 列と定数の直接比較。定数を左辺に置くこともできます。 |
<=> | 列と定数の NULL 安全な直接等価比較。NOT、AND、OR 内でも NULL ではない二値の結果を保持します。 |
IN、NOT IN | NULL を含まない空でない定数リスト。 |
IS NULL、IS NOT NULL | 列の直接参照。 |
Boolean 列、Boolean 列に対する NOT | Boolean 列の直接参照。 |
LIKE、NOT LIKE | utf8 または large_utf8 列の直接参照と、バックスラッシュによるエスケープ、明示的な ESCAPE 句、埋め込み NUL 文字を含まない文字列リテラルのパターン。 |
starts_with、ends_with | utf8 または large_utf8 列の直接参照と文字列リテラルを引数に取る組み込み関数。 |
array_contains(labels, 'red') | list<utf8> 列の直接参照と NULL でない文字列リテラル。 |
AND | 最上位の各連言を個別にプッシュダウンでき、未サポートの連言は Doris 側に残ります。 |
OR | 両方の分岐を完全に変換できる必要があります。 |
NOT | オペランドを完全に変換できる必要があります。 |
通常、次の形式はプッシュダウンされません。
- 対応する組み込みの文字列関数と配列包含関数以外の関数、または列に適用した算術式。
like、starts_with、ends_with、array_containsという名前のユーザー定義関数は、対応する組み込み関数として扱われません。 - パターンに埋め込み NUL 文字を含む文字列述語。バックスラッシュによるエスケープや明示的な
ESCAPE句を使用するLIKEとNOT LIKEも Doris 側に残ります。 - 空の
INリスト、またはNULLを含むINリスト。 - 式の一部しか変換できない
ORまたはNOT式。 - 損失なく Lance に変換できないデータ型や定数値。
実際にプッシュダウンされる条件は、EXPLAIN の lancePushdownPredicate で確認できます。
EXPLAIN
SELECT user_id
FROM lance_catalog.default.user_profiles
WHERE active
AND starts_with(name, 'A')
AND country LIKE 'C%';
配列ラベル述語
Apache Doris 4.1.5 以降、配列ラベルのプッシュダウンでは、直接参照した Lance の list<utf8> 列に対する、NULL でない文字列リテラルを指定した array_contains をサポートします。古いビルドでは条件が Doris 側に残る場合があるため、この最適化を前提とする前に EXPLAIN で確認してください。NULL の配列は引き続き NULL を返し、空の配列は一致せず、ラベルの重複によって結果行が増えることはありません。
id 列と list<utf8> 型の labels 列を持つ Lance テーブルでは、次のようにします。
EXPLAIN
SELECT id
FROM lance_catalog.default.items
WHERE array_contains(labels, 'red')
AND array_contains(labels, 'blue');
これは、順序や隣接関係にかかわらず両方のラベルを含む配列に一致します。AND を OR に変えると、どちらかのラベルに一致します。NOT (array_contains(labels, 'red')) も変換でき、SQL の NULL セマンティクスが保たれます。これらの例は通常のテーブルスキャンに適用されます。検索 TVF の filter パラメータと外側の WHERE 条件の違いは変わりません。
次の条件は Doris 側の残余述語となります。
array_contains(labels, NULL): Doris はNULL要素に一致できますが、Lance の包含関数では探す値がNULLの場合のセマンティクスが異なります。array_contains_all(labels, ['red', 'blue']): Doris は順序のある連続した部分列を検査します。Lance の集合包含関数や、二つの独立した包含述語で置き換えることはできません。- 動的な検索値、配列列を囲む式やキャスト、および
large_list、固定長リスト、list<large_utf8>を含むほかの配列要素型やコンテナ型。
述語プッシュダウンとスカラーインデックスの使用
述語プッシュダウンは Lance が条件を評価することを意味し、インデックスの使用を保証しません。通常のスキャンでは、Doris は各スキャンタスクに物理 BTree、Bitmap、LabelList セグメントを割り当てられます。同じ列に対する IN、AND、OR、NOT の組み合わせは、Lance が式全体をサポートする場合、選択したインデックスを使用できます。OR では両分岐から安全な候補を得る必要があり、NOT では評価が不完全な部分木を反転できません。未サポートのインデックス式は、割り当てられた Fragment 範囲内のスキャンにフォールバックします。
各タスクが選択するのは一つの論理スカラーインデックスです。ラベル、カテゴリ、数値の述語を組み合わせたクエリでも、Doris が三つのインデックスの積集合を取るとは限りません。プッシュダウンされた条件全体はスキャンの制限を適用する前に再確認され、インデックスの範囲外にある Fragment も読み取られます。使用できるインデックスがなくても、互換性のある述語はプッシュダウンされ、Lance のスキャンで評価できます。
次の情報を組み合わせて確認してください。
| 確認する情報 | 意味 |
|---|---|
EXPLAIN の lancePushdownPredicate | Lance に送られた条件。残った predicates: 条件は Doris が評価します。 |
EXPLAIN の lanceScalarIndexScan=SEGMENT と lanceGroupingIndex | スカラーセグメントスキャンが計画され、選択された論理インデックスが示されます。これだけでは実行時のインデックス使用は証明できません。 |
Profile の LanceScalarIndexSegmentsSearched | 計測対象のスカラーセグメント経路で実際に実行された検索。 |
Profile の LanceScalarIndexCandidateRows | その経路から報告された候補行数であり、最終結果行数とは限りません。一部の NOT 式のような補集合マスクでは候補数が報告されない場合があります。 |
Profile の LanceScalarIndexSegmentFallbacks | 計画されたスカラーセグメント経路からフォールバックしたタスク数。 |
これらのカウンターを確認するには enable_profile を有効にします。最適化を測定するときは、同じ SQL、投影、データセットバージョン、キャッシュ状態を比較してください。これらのカウンターは通常のスカラーセグメントスキャンを表しており、ANN や全文検索の Prefilter 内部でのスカラーインデックス使用を単独で推定するには使用できません。
Runtime Filter のプッシュダウン
通常の Lance テーブルが結合に参加する場合、Doris は結合の build 側で生成された一部の Runtime Filter を Lance SQL 条件に変換し、Lance による読み取り中に適用できます。特に大きなテーブルを選択性の高い build 側テーブルと結合する場合、Doris に返すデータ量を減らせます。
SELECT l.user_id, l.name
FROM lance_catalog.default.user_profiles l
JOIN internal.demo.allowed_users a
ON l.user_id = a.user_id;
現在、次の Runtime Filter をプッシュダウンできます。
| Runtime Filter | Lance にプッシュダウンする形式 |
|---|---|
| IN Filter | column IN (...) |
| Min/Max Filter | column >= min_value、column <= max_value、または両方 |
Runtime Filter の列と値は、Lance SQL がサポートするスカラー型に安全に変換できる必要があります。ほかの Runtime Filter 種別、NULL を含む IN Filter、安全に変換できないデータ型や値はプッシュダウンされません。プッシュダウンされない Runtime Filter も Doris が評価するため、クエリの正しさは維持されますが、Lance で早期にフィルタリングする性能上の利点は得られません。
Lance Scanner の作成前に準備ができている Runtime Filter のみ、その Scanner のプッシュダウン条件に含められます。後から到着した Runtime Filter も Doris が評価しますが、作成済みの Scanner にはプッシュダウンされない場合があります。
Runtime Filter 条件は通常の SQL 述語から生成される Substrait 条件と組み合わされ、互いを置き換えません。EXPLAIN の runtime filters 項目には計画された Runtime Filter が表示されます。少なくとも一つがプッシュダウンされた場合、Runtime Profile の LanceRuntimeFilterPushedIds と LanceRuntimeFilterSkippedIds で、プッシュダウンされた Filter ID とスキップされた Filter ID を確認できます。
Runtime Filter のプッシュダウンは現在、通常の Lance テーブルスキャンにのみ適用されます。vector_search() や全文検索による候補生成には使用されません。
ファイル TVF で Lance をクエリする
既知のパスにある Lance データセットを読み取るだけなら、Catalog を作成せずに s3() または local() TVF を使用できます。uri または file_path は、内部のデータファイルではなく Lance データセットのルートディレクトリを指す必要があります。
S3 TVF
s3() TVF は S3 互換 API を使用します。OSS では s3.* プロパティと、バケットを含む仮想ホスト形式のエンドポイントを使用してください。ネイティブ OSS アクセスには前述の OSS Catalog の例を使用します。次の SQL はサンプルデータセットの先頭 10 行を読み取ります。実行前にアドレス、認証情報、列名を置き換えてください。
- AWS S3
- MinIO(パス形式)
- Alibaba Cloud OSS(S3 互換アクセス)
SELECT user_id, name
FROM s3(
"uri" = "s3://my-bucket/lance/user_profiles.lance",
"format" = "lance",
"fs.s3.support" = "true",
"use_path_style" = "false",
"s3.endpoint" = "https://my-bucket.s3.us-east-1.amazonaws.com",
"s3.region" = "us-east-1",
"s3.access_key" = "<ak>",
"s3.secret_key" = "<sk>"
)
ORDER BY user_id
LIMIT 10;
AWS S3 でもエンドポイントを明示的に設定します。この例は仮想ホスト形式を使用します。エンドポイント内のバケットとリージョンは、URI および s3.region と一致させてください。
SELECT user_id, name
FROM s3(
"uri" = "s3://my-bucket/lance/user_profiles.lance",
"format" = "lance",
"fs.s3.support" = "true",
"s3.endpoint" = "http://minio.example.com:9000",
"s3.region" = "us-east-1",
"use_path_style" = "true",
"s3.access_key" = "<ak>",
"s3.secret_key" = "<sk>"
)
ORDER BY user_id
LIMIT 10;
バケットを含まない MinIO サービスエンドポイントを使用し、use_path_style=true を設定します。FE とクエリを実行する BE の両方からサービスへ到達できる必要があります。FE ホストからしかアクセスできないアドレスは避けてください。
SELECT user_id, name
FROM s3(
"uri" = "s3://my-bucket/lance/user_profiles.lance",
"format" = "lance",
"fs.s3.support" = "true",
"s3.endpoint" = "https://my-bucket.oss-cn-beijing.aliyuncs.com",
"s3.region" = "cn-beijing",
"use_path_style" = "false",
"s3.access_key" = "<ak>",
"s3.secret_key" = "<sk>"
)
ORDER BY user_id
LIMIT 10;
この例は Filesystem Catalog と同じ OSS S3 互換設定を使用しますが、uri は特定の .lance データセットを指し、warehouse はデータセットを含むディレクトリを指します。fs.s3.support=true と use_path_style=false を維持し、エンドポイントのバケットが URI と一致することを確認してください。
OSS では、同じ s3.* プロパティと fs.s3.support=true を維持したまま、例の uri を oss://my-bucket/lance/user_profiles.lance としても指定できます。TVF は URI を s3:// に正規化し、ネイティブ OSS プロバイダーには切り替えません。ネイティブ OSS Catalog の oss.* 設定をそのままコピーしないでください。バケットを含まないエンドポイントと仮想ホスト形式の組み合わせではデータセットが存在しないと報告される場合があり、パス形式に変更すると OSS から SecondLevelDomainForbidden で拒否される場合があります。
S3 TVF では、FE がスキーマ、現在のバージョン、Fragment 一覧を取得します。Doris はそのバージョンを固定し、Fragment を並列にスキャンします。EXPLAIN には VTVF_SCAN_NODE が表示されます。複数の Split はデータセット URI を共有し、Fragment ID で区別されます。totalFileSize=0 や length=0 は Lance Split のプレースホルダーであり、データセットが空であることや各 Split がテーブル全体を繰り返しスキャンすることを示すものではありません。
Local TVF
SELECT user_id, name
FROM local(
"file_path" = "/data/lance/user_profiles.lance",
"backend_id" = "10001",
"format" = "lance"
);
file_path は指定されたとおりに対象 BE の Lance Reader へ渡されます。Doris は user_files_secure_path を前に付けず、Glob としてパスを展開しません。そのため、対象 BE がアクセスできる単一の Lance データセットのルートディレクトリを直接指す必要があります。絶対パスを推奨します。
Local TVF では、スキーマ検出と実行がそれぞれ独立してデータセットの最新バージョンを開きます。現在、スキーマ検出時に解決したバージョンは後続のスキャンに固定されません。クエリの解析から実行までの間にデータセットが変わると、検出したスキーマとスキャンしたスナップショットが異なる場合があります。Local TVF のクエリ解析および実行中は、データセットを変更しないでください。現在の Local Lance TVF は一つの Scanner を使用します。
Lance ファイル TVF には、さらに次の制限があります。
- サポートするのは
s3()とlocal()のみです。HDFS や HTTP など、ほかのファイル TVF は現在サポートされていません。 path_partition_keysはサポートされていません。- 一つの TVF パスで表せる Lance データセットは一つだけです。
DESC FUNCTIONでは未サポートの型を含むスキーマを表示できますが、SQL で未サポートの列を投影することはできません。
ベクトル検索
Doris 4.2 の Lance 自動検索を含むビルドでは、条件を満たす通常の SQL からネイティブのベクトル Top-N と MATCH/BM25 検索も利用できます。五つの近似関数、距離尺度の変換、入力のセマンティクス、JOIN/EXISTS の適用範囲については、通常の SQL からの自動検索を参照してください。以下の TVF は、明示的な検索調整や自動書き換えの対象外となるサポート済みのクエリ形状に引き続き使用します。
vector_search() は、Lance テーブルのベクトル列に対して Top-K 検索を行うリレーショナル TVF です。既存の Lance ベクトルインデックスを使用するか、Flat Search を実行できます。
構文と例
SELECT user_id, label, _distance
FROM vector_search(
"table" = "lance_catalog.default.items",
"column" = "embedding",
"query_vector" = "[0.1, 0.2, 0.3, 0.4]",
"top_k" = "10",
"offset" = "3",
"metric" = "l2",
"nprobes" = "20",
"refine_factor" = "10",
"prefilter" = "true",
"filter" = "category = 'book'",
"use_index" = "true"
)
ORDER BY _distance ASC, user_id;
vector_search() のリレーションスキーマには、Lance のソーステーブルのすべての列に加え、最近傍クエリのために Lance Scanner が生成する _distance 列が含まれます。最終的な SQL 結果には、SELECT で投影した列のみが含まれます。Doris は _distance を FLOAT として公開します。これは汎用的な類似度スコアではなく距離であり、値が小さいほど二つのベクトルは近くなります。ソーステーブルに _distance という列が既にあってはなりません。SQL リレーションでは最終的な表示順序は保証されません。最近傍順序を確定させる必要がある場合は ORDER BY _distance ASC を明示し、距離が同じ行には一意の列をタイブレーカーとして追加することを推奨します。
table は、正確に三要素の catalog.database.table 名として解析できる必要があります。多階層 Lance Namespace は . を含む一つの Doris データベース名にマッピングされるため、データベース部分をバッククォートで囲んでください。たとえば Namespace doris.analytics のテーブル items には次の値を使用します。
"table" = "lance_catalog.`doris.analytics`.items"
引用符なしの lance_catalog.doris.analytics.items は四要素の名前として解析され、拒否されます。テーブル名のみ、または database.table も拒否されます。
パラメータ
| パラメータ | 必須 | デフォルト | 説明 |
|---|---|---|---|
table | はい | - | 完全修飾された三要素の catalog.database.table 名。多階層 Namespace が . を含むデータベース名にマッピングされる場合は、その部分をバッククォートで囲みます。Lance Catalog 内のテーブルであり、ユーザーにそのテーブルの SELECT 権限が必要です。 |
column | はい | - | ベクトル列名。単一ベクトルの fixed_size_list<float16|float32|float64|uint8|int8> と、マルチベクトルの list<fixed_size_list<float16|float32|float64, D>> 列をサポートします。マルチベクトル検索を参照してください。 |
query_vector | はい | - | 単一ベクトル列では JSON の数値配列、マルチベクトル列では空でない JSON 行列。各サブベクトルの次元は列と一致し、各値は有限で、その要素型で表現可能である必要があります。 |
top_k | いいえ | 10 | offset をスキップした後に返す結果数。正の整数である必要があります。 |
offset | いいえ | 0 | ベクトル検索内でスキップする最近傍の数。非負の整数である必要があります。top_k + offset は符号なし 32 ビット整数の最大値を超えられません。 |
metric | いいえ | l2 | 距離尺度: l2、cosine、dot、hamming。dot_product は dot の別名です。uint8 ベクトルは hamming のみをサポートし、そのほかの現在サポートされるベクトル要素型は l2、cosine、dot をサポートします。cosine、dot、hamming のインデックスをクエリする場合は metric を明示してください。整数のマルチベクトル列とマルチベクトルの hamming はサポートされません。 |
distance_lower_bound | いいえ | 下限なし | 単一ベクトル検索の包含的な距離下限。有限の FLOAT である必要があります。 |
distance_upper_bound | いいえ | 上限なし | 単一ベクトル検索の排他的な距離上限。有限の FLOAT である必要があります。両方の境界を指定する場合、FLOAT への変換後に下限が上限より小さくなければなりません。 |
filter | いいえ | - | Lance が評価する Lance SQL 条件。実行のタイミングは prefilter で制御します。 |
prefilter | いいえ | false | TVF の filter を適用するタイミングを制御します。true はベクトル候補の生成前、デフォルトの false は候補生成後にフィルタリングするため、結果が top_k 行より少なくなる場合があります。外側の Doris の WHERE には影響しません。 |
nprobes | いいえ | 最小 1、最大値なし | 探索する IVF インデックスのパーティション数。正の整数である必要があります。未設定時、Lance は一つのパーティションから開始し、prefilter=true によって候補が不足すると追加のパーティションを探索できます。明示的に N に設定すると、最小・最大の探索数がともに N に固定されます。 |
refine_factor | いいえ | 単一ベクトル: 無効。マルチベクトル: 1 | 候補の再評価倍率。正の整数である必要があります。単一ベクトル検索で未設定の場合、Lance は元のベクトルから距離を再計算しないため、量子化インデックスの _distance は近似値になることがあります。N に設定すると、まず (top_k + offset) × N 個の候補を取得し、元のベクトルで正確な距離を再計算して並べ替えます。再評価では候補の元のベクトルデータを読み取ります。N が大きいほど読み取りと評価の対象が増え、I/O が大幅に増加してクエリ性能が低下する場合があります。 単一ベクトルでは 1 を設定すると再評価が有効になり、未設定とは異なります。マルチベクトルでは常に元の値を使って候補を再評価し、デフォルト倍率は 1 です。 |
ef | いいえ | floor(1.5 × (top_k + offset)) | HNSW グラフ検索中に保持する候補幅。正の整数である必要があります。refine_factor も設定した場合、デフォルトは floor(1.5 × (top_k + offset) × refine_factor) です。HNSW 以外のインデックスには影響しません。 |
approx_mode | いいえ | ネイティブのデフォルト。現在は normal | 近似検索の文字列ポリシー。fast、normal、accurate を指定し、大文字小文字と前後の空白は無視されます。数値文字列を含むほかの値は拒否されます。単一ベクトルとマルチベクトルの両方に適用されます。近似モードの選択を参照してください。 |
use_index | いいえ | true | true の場合、Doris はベクトル列と距離尺度に対応する Lance ベクトルインデックスを優先し、使用可能なインデックスがなければ自動的に Flat Search を使用します。false の場合、ベクトルインデックスを無効にしてデータ全体を Flat Search します。 |
version、timestamp、tag、branch | いいえ | - | main の最新バージョンの代わりに、過去のバージョン、指定時刻のバージョン、タグ、ブランチを検索します。過去のバージョンまたはブランチの検索を参照してください。 |
metric を省略すると、インデックス検索と Flat Search のどちらでも l2 が選ばれます。uint8 列では "metric" = "hamming" を明示してください。デフォルトの l2 はサポートされません。マルチベクトル検索には、後述の候補数の制限も適用されます。
近似モードの選択
最初の基準には normal を使用します。approx_mode はネイティブ検索アルゴリズムのポリシーを変更し、効果は選択したインデックスと実行経路によって異なります。nprobes、ef、refine_factor、保存済みインデックス、Split の計画は変更しません。省略した場合、現在 normal である Lance のデフォルトを維持します。
このオプションには、近似モードの実装を含む Doris ビルドが必要です。以下は、その実装で使用するネイティブ Lance リビジョンについて説明します。古い FE はこのプロパティを拒否し、古い BE はオプションのフィールドを無視します。ローリングアップグレード中、クエリの候補 BE プールに旧アップグレード元としてマークされた BE があると、FE は明示的な fast または accurate を拒否します。異なる Split に異なるポリシーが使われるのを防ぐためです。エラーには BE と要求したモードが示されます。該当する BE のアップグレードを完了するか、オプションを省略するか normal を使用してください。省略または明示的な normal はネイティブのデフォルトを維持し、これらのアップグレード元と互換性があります。デフォルト以外のモードを利用する前に、参加するすべての FE と BE をアップグレードしてください。この保護機能は、旧アップグレード元としてマークされていない任意の古いビルドは検出しません。
モード間の違い
| 検索経路 | fast | normal | accurate |
|---|---|---|---|
| RabitQ の生クエリ距離推定 | 複数ビットのインデックスでも一ビットのスコアを使用し、拡張ビットの計算とその下限ゲートを省略します。 | 標準の 8 ビット量子化距離ルックアップテーブルを使用し、利用可能であれば拡張ビットも計算します。 | 高精度の 16 ビット距離ルックアップテーブルを使用し、利用可能であれば拡張ビットも計算します。 |
| Prefilter 付き HNSW | 以下の実行時条件を満たすと ACORN 探索を有効にします。 | 通常のフィルタ付きグラフ探索を使用します。 | normal と同じ探索ポリシーを使用しますが、量子化距離の計算は異なる場合があります。 |
| IVF_FLAT または網羅的な Flat Search | モード固有の量子化変更はありません。 | 同じスコア計算ポリシーです。 | 同じスコア計算ポリシーです。 |
8 ビットと 16 ビットはクエリ時の距離ルックアップテーブルを表し、インデックスが各次元に保存するビット数ではありません。たとえば 5 ビットの RabitQ インデックスでは、生クエリ経路の fast は一ビットのスコアを使用します。ほかのモードでは追加の四ビットを使用できます。残差クエリのスコア計算など、ほかの RabitQ 経路では動作が異なる場合があります。モードの説明によって、対応するベクトル型と距離尺度の組み合わせが増えるわけではありません。
accurate も近似検索です。正確な Top-K、すべての候補の評価、量子化インデックスでの元のベクトルに基づく _distance は保証されません。refine_factor は元のベクトルを使用した再順位付けを制御します。値を増やすとスコアと再現率が改善する場合がありますが、前段で見落としたすべての候補を復元できるわけではありません。マルチベクトルクエリでは元のベクトルによる再評価が引き続き必須です。
各モードを使用する場面
| ワークロード | 最初の選択 | 確認すること |
|---|---|---|
| 一般的なワークロード、またはボトルネックが不明 | normal | ポリシー変更前に再現率とレイテンシーの基準値を確立します。 |
| 有効な Prefilter を持つ HNSW_FLAT でレイテンシーが重要 | fast と normal を比較 | ACORN は無駄な距離計算を減らせる場合があります。再現率、結果数、レイテンシーの中央値と p95 を確認してください。高速化は保証されません。 |
| 再現率が重要な複数ビット RabitQ | normal | fast は有用な符号化情報を捨て、再現率が大幅に低下する場合があります。代表的なクエリで品質目標を満たす場合にのみ使用します。 |
| 元のベクトルによる再順位付けがなく、近似スコアの誤差が重要な RabitQ | accurate と normal を比較 | 元のベクトルの距離を基準に、スコア誤差、順位の品質、追加レイテンシーを測定します。推定精度の向上は再現率の向上を保証しません。 |
| 元のベクトルによる再順位付けを既に使う RabitQ | normal | accurate の最終スコアへの効果は小さい可能性があります。候補選択はなお異なるため、再現率を別途検証します。 |
| IVF_FLAT、または有効な Prefilter のない HNSW_FLAT | normal を維持 | 現在の実装では、モード変更による量子化または ACORN の利点はありません。IVF_FLAT の再現率は探索するパーティションに依存します。 |
互換性のある RabitQ を使用する HNSW インデックスでは、fast によって ACORN 探索と、該当する生クエリ経路での RabitQ 距離推定の簡略化が同時に起こる場合があります。一つのオプションが両方に作用します。HNSW_FLAT のテスト結果から再現率を推定せず、この組み合わせのインデックスを独立して検証してください。normal と accurate は同じ HNSW 探索ポリシーですが、RabitQ のスコア計算は異なる場合があります。
推奨する調整順序:
- データセットスナップショット、クエリ集合、距離尺度、フィルタ、インデックスのカバー範囲を同じ条件に固定します。
use_index=falseを使用し、同じ対象行について正確な Top-K を基準値として取得します。対象条件は TVF のfilterに入れ、prefilter=trueを設定します。 normalの基準値を確立します。Recall@K、結果数、必要に応じたスコア誤差、レイテンシーの中央値と p95 を測定します。- 再現率が不足する場合は、IVF の
nprobesと HNSW のefを調整します。元のベクトルによるスコアや再順位付けする候補の増加が必要なら、追加のベクトル読み取りと計算を考慮してrefine_factorを設定します。 - ほかの設定を固定したうえで、フィルタ付き HNSW には
fast、RabitQ の推定精度にはaccurateを比較します。品質目標を満たし、測定上の利点が十分な場合にモードを選択してください。コールドキャッシュとウォームキャッシュを別々に測定します。
フィルタ付き HNSW で ACORN を有効にする
選択される互換インデックスには HNSW グラフが必要です。approx_mode="fast" を設定し、述語を TVF 内に置いて prefilter="true" を設定します。外側の Doris の WHERE はこの Prefilter にはならず、use_index=true だけでは HNSW インデックスの選択を強制できません。
構文例で使用した四次元の embedding、user_id、文字列の category 列があり、互換性のある L2 HNSW インデックスが既存で、SELECT 権限を持つ場合の例です。
SELECT user_id, _distance
FROM vector_search(
"table" = "lance_catalog.default.items",
"column" = "embedding",
"query_vector" = "[0.1,0.2,0.3,0.4]",
"metric" = "l2",
"top_k" = "10",
"filter" = "category = 'book'",
"prefilter" = "true",
"use_index" = "true",
"approx_mode" = "fast",
"ef" = "64"
)
ORDER BY _distance, user_id;
このクエリは条件を満たす最大十行を距離順で返します。実際の ID と再現率はデータと ANN 検索に依存します。このクエリの EXPLAIN には lanceApproxMode=FAST が表示され、要求したポリシーを確認できます。ただし、すべてのサブインデックスが ACORN を実行した証拠にはなりません。
現在のネイティブ実装は、各 HNSW サブインデックス(IVF パーティション)内で、Prefilter を通過するノード数に基づいて個別に経路を選択します。
| 実行時の条件 | 経路 |
|---|---|
| 有効な Prefilter がない、または全ノードが通過 | 通常の HNSW 探索。 |
| 通過するノードが約 10% 未満 | 残ったノードを Flat でスコア計算。 |
| 一部のみ通過し、上記の疎なフィルタの規則には該当しない | fast は ACORN を使用し、normal と accurate は通常のフィルタ付きグラフ探索を使用。 |
| ACORN で必要な候補が不足し、クエリに距離境界がない | 通常のフィルタ付きグラフ探索で再試行。 |
しきい値はテーブル全体ではなく、各サブインデックス内に適用されます。このインターフェイスに ACORN を強制する別のプロパティはありません。Doris では距離範囲の安全性規則により、ネイティブのグラフ探索より前に Flat Search が選ばれることもあります。半径および範囲検索を参照してください。
半径および範囲検索
半径クエリには distance_upper_bound を設定し、区間 [lower, upper) には両方の境界を設定します。省略した境界は無制限です。距離は選択した尺度に従います。l2 はユークリッド距離の二乗なので、幾何学的な半径 r に対応する上限は r * r です。dot のような尺度では負の境界も有用で、受け付けられます。保存されたベクトルが Float64 でも境界は FLOAT 精度を使用します。有限でない境界、オーバーフロー、同値の境界、逆順の区間は拒否されます。
たとえば、user_id と三次元 Float32 の embedding 列を持つ既存の Lance Catalog テーブル lance_catalog.default.items があるとします。
| user_id | embedding | [0, 0, 0] までの L2 距離の二乗 |
|---|---|---|
| 1 | [0, 0, 0] | 0 |
| 2 | [1, 0, 0] | 1 |
| 3 | [2, 0, 0] | 4 |
SELECT user_id, _distance
FROM vector_search(
"table" = "lance_catalog.default.items",
"column" = "embedding",
"query_vector" = "[0, 0, 0]",
"metric" = "l2",
"top_k" = "10",
"use_index" = "false",
"distance_lower_bound" = "1",
"distance_upper_bound" = "4"
)
ORDER BY _distance;
+---------+-----------+
| user_id | _distance |
+---------+-----------+
| 2 | 1 |
+---------+-----------+
下限を削除すると、行 1 も返ります。上限 0 だけを使用すると、行は返りません。prefilter=true では filter がベクトル検索前に候補を制限し、デフォルトの prefilter=false では候補生成後にフィルタリングします。offset は距離範囲を適用した後の結果をスキップします。出力スキーマは変わらず、テーブルの列と FLOAT 型の _distance を含みます。EXPLAIN には lanceDistanceRange=[1.0, 4.0) が表示されます。
距離境界は準備済みステートメントの ? パラメータをサポートします。実行ごとにその境界値を検証して使用し、NULL の境界は拒否します。片側を無制限にするには、そのプロパティを省略します。
これは引き続き Top-K クエリであり、半径内のすべての行を返す API ではありません。結果は top_k に制限され、それより少なくなることもあります。
範囲クエリでは、両方の境界が指定され、選択したインデックスが明示的に IVF_FLAT と識別される場合にのみ Doris はインデックス検索を使用します。片側だけの範囲、量子化インデックス、サブタイプが不明なインデックスでは、use_index=true でも正確な Flat Search にフォールバックします。範囲の安全性によってインデックスを選べない場合、EXPLAIN は lanceVectorIndexStatus=DISTANCE_RANGE_FALLBACK を報告します。このフォールバックはスキャンコストを増やす場合があります。
インデックス付き IVF_FLAT クエリも nprobes で選ばれるパーティションに依存します。すべての候補を評価するには use_index=false を使用します。インデックスに含まれない追加データは Flat Search されます。マルチベクトル列は距離境界をサポートしません。
サポートされるベクトルインデックス種別
単一ベクトル列では、Doris は次の Lance ベクトルインデックスの組み合わせをサポートします。マルチベクトルのインデックス制限についてはマルチベクトル検索を参照してください。
| インデックス種別 | 説明 | 主なクエリパラメータ |
|---|---|---|
IVF_FLAT | 各パーティション内で元のベクトルを使って距離を計算する IVF パーティション | nprobes |
IVF_SQ | Scalar Quantization を使用する IVF | nprobes、refine_factor |
IVF_PQ | Product Quantization を使用する IVF | nprobes、refine_factor |
IVF_HNSW_FLAT | グラフノードに元のベクトルを保持する HNSW と IVF | nprobes、ef |
IVF_HNSW_SQ | Scalar Quantization を使用する IVF と HNSW | nprobes、ef、refine_factor |
IVF_HNSW_PQ | Product Quantization を使用する IVF と HNSW | nprobes、ef、refine_factor |
vector_search() が使用するのは Lance に既存のベクトルインデックスだけです。インデックスを作成したり、ユーザーがインデックス種別や名前を指定したりすることはできません。use_index=true では、Doris はベクトル列と距離尺度に互換性のあるインデックスを自動選択します。使用可能なインデックスがないデータや、選択したインデックスに含まれないデータも、自動的に Flat Search され、除外されません。use_index=false ではすべてのデータを Flat Search します。
列に互換性のあるインデックスが複数ある場合、Doris はクエリごとに名前順で最初のものを一つ選びます。そのインデックスがカバーしない Fragment は、ほかのインデックスがカバーしていても Flat Search されるため、実行内容は EXPLAIN に示されるカバー範囲と一致します。Doris が計画に使用できないインデックスは一切使用されず、検索全体が Flat Search になります。たとえば Fragment のカバー範囲のメタデータがないもの(lanceVectorIndexStatus=UNKNOWN_COVERAGE)、距離尺度が記録されていないもの(METRIC_MISMATCH)、詳細がなく Lance もファイルから推定できないため Doris がスキップする古いインデックス(NO_MATCH)が該当します。Lance が詳細を推定できる古いインデックスは通常どおり使用されます。
サポートされるベクトル要素型と距離尺度
単一ベクトル列では、ベクトルインデックスがサポートする距離尺度は要素型によって異なります。次の表から対応する組み合わせを選んでください。未サポートの組み合わせはベクトルインデックスを使用できません。
| ベクトル要素型 | l2 | cosine | dot | hamming |
|---|---|---|---|---|
float16 | サポート [1] | サポート | サポート | 非サポート |
float32 | サポート | サポート | サポート | 非サポート |
float64 | サポート | サポート | サポート | 非サポート |
uint8 | 非サポート | 非サポート | 非サポート | IVF_FLAT と IVF_HNSW_FLAT のみ [2] |
int8 | Flat Search のみ [3] | Flat Search のみ [3] | Flat Search のみ [3] | 非サポート |
脚注に別記がない限り、「サポート」は上記の六種類すべてのインデックスで使用できることを意味します。「Flat Search のみ」はベクトルをクエリできるものの、ベクトルインデックスは使用しないことを意味します。
- 大きな値を持つ
float16データに対するl2インデックスの構築は、長時間かかるか失敗する場合があります。ベクトル値を管理された範囲に収めてください。インデックス作成に失敗した場合は Flat Search を使用するか、用途に適していればcosineを使用してください。 - Lance は
uint8ベクトルをバイナリベクトルとして扱い、hammingのみをサポートします。Product Quantization と Scalar Quantization はuint8をサポートしないため、使用できるのはIVF_FLATとIVF_HNSW_FLATのみです。 int8ベクトルは現在ベクトルインデックスを使用できず、Flat Search に限られます。
クエリの距離尺度はインデックスと一致させる
クエリの metric はインデックス作成時の距離尺度と一致する必要があります。一致しなくても、要求した尺度が列型に対応していれば、Doris は Flat Search を使用します。結果は正しいままですが、ベクトルを直接スキャンするため、通常は性能が低下します。
metric を省略すると、Doris はインデックス選択時に l2 として扱います。そのため cosine、dot、hamming で構築したインデックスには metric を明示してください。たとえば uint8 ベクトルインデックスでは "metric" = "hamming" が必要です。省略すると未サポートの l2 が使われ、クエリは失敗します。
インデックスの使用は EXPLAIN で確認します。lanceSearchIndexSegments が 0 より大きければインデックス検索、0 なら Flat Search を示します。
Doris はベクトル列ごとに一つのベクトルインデックスのみを考慮します。異なる距離尺度のインデックス間での選択が曖昧にならないよう、ベクトル列ごとのインデックスは最大一つにしてください。
マルチベクトル検索
マルチベクトル列は、たとえば文書の token embedding のように、テーブルの各行に複数のサブベクトルを格納します。クエリ行列からは、順位付けされたテーブル行の集合が一つ生成されます。独立したベクトル検索のバッチではなく、複数の列も検索しません。
データの準備とクエリの実行
上記の AWS S3 Filesystem Catalog の例を使用します。Catalog は lance_fs_s3、ウェアハウスは s3://my-bucket/lance です。書き込み環境に Lance Python SDK(pylance)と pyarrow をインストールします。たとえば AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_DEFAULT_REGION で S3 の認証情報とリージョンを設定します。writer には書き込み権限、Doris には同じ場所への読み取り権限が必要です。カスタムエンドポイントやほかの認証方式では、SDK のオブジェクトストアオプションを Catalog に合わせて設定します。
documents.lance をウェアハウスの直下に作成すると、Doris は lance_fs_s3.default.documents として検出します。Catalog と Python の例の両方でバケットを置き換え、新しいデータセットの場所を使用してください。
import lance
import pyarrow as pa
vector_type = pa.list_(pa.float32(), 2)
schema = pa.schema([
pa.field("id", pa.int64()),
pa.field("embeddings", pa.list_(
pa.field("item", vector_type, nullable=False)
)),
])
data = pa.Table.from_pylist([
{"id": 1, "embeddings": [[1.0, 0.0], [0.0, 1.0]]},
{"id": 2, "embeddings": [[1.0, 0.0]]},
{"id": 3, "embeddings": []},
{"id": 4, "embeddings": None},
], schema=schema)
lance.write_dataset(
data,
"s3://my-bucket/lance/documents.lance",
data_storage_version="2.1",
)
外側のリストにより、行ごとに異なる数のサブベクトルを持てます。内側の nullable=False は必須で、サブベクトル自体は null にできません。二次元の JSON 配列でテーブルをクエリします。
SELECT id, _distance
FROM vector_search(
"table" = "lance_fs_s3.default.documents",
"column" = "embeddings",
"query_vector" = "[[1,0],[0,1]]",
"top_k" = "2",
"metric" = "l2",
"use_index" = "false"
)
ORDER BY _distance, id;
期待される結果:
| id | _distance |
|---|---|
| 1 | 0.0 |
| 2 | 2.0 |
行 1 には各クエリサブベクトルに対する完全一致があります。行 2 は最初のクエリサブベクトルと距離 0 で一致し、二番目との L2 距離の二乗は 2 です。空または null の外側のリストは順位付けされません。"offset" = "1" を追加して "top_k" = "1" に変更すると、行 2 のみ返ります。"filter" = "id > 1" を追加し "prefilter" = "true" を設定すると、候補検索が一致する行に限定され、このデータセットではやはり行 2 のみ返ります。
行単位のスコア計算
クエリサブベクトルを Q、行に保存されたサブベクトルを V とすると、次のようになります。
_distance = sum(q in Q, min(v in V, distance(q, v)))
metric | 二つのサブベクトル間の距離 |
|---|---|
l2(デフォルト) | ユークリッド距離の二乗 |
cosine | 1 - cosine_similarity |
dot または dot_product | 1 - dot_product。負の値になる場合があります |
_distance は小さいほど良い値です。各クエリサブベクトルは一度寄与し、一つの保存されたサブベクトルが複数のクエリサブベクトルと一致することもあります。スコアは平均ではなく合計されるため、クエリサブベクトルを繰り返すとその寄与も繰り返されます。Float64 入力を含め、_distance の Doris 型は FLOAT です。top_k と offset はサブベクトルではなくテーブル行を数えます。Top-K の境界で同点の行が含まれるかどうかと、その順序は保証されません。外側の ORDER BY は返された行だけを並べ替えます。
型、次元、NULL 値
| 項目 | 要件 |
|---|---|
| Lance 列 | list<fixed_size_list<T, D>>。D > 0、T は float16、float32、float64 のいずれか |
| Doris 型 | Float16/Float32 は ARRAY<ARRAY<FLOAT>>、Float64 は ARRAY<ARRAY<DOUBLE>> |
| クエリの形状 | 空でない JSON 行列。内側の各配列には正確に D 個の要素が必要です。クエリサブベクトルが一つでも [[...]] と記述します。通常の単一ベクトル列では引き続き [...] を使用します。 |
| クエリ値 | T で表現できる有限の数値。空の行列、次元の不一致、null、数値以外の要素、範囲外の値は拒否されます。 |
| 保存された値 | サブベクトルは null 不可として宣言し、有限で null でない要素を含む必要があります。スコア計算経路は実際の null または有限でない要素に遭遇すると拒否します。要素のスキーマが nullable であること自体は許されます。 |
| 空または null の行 | 外側のリストが null または [] の場合、一致するサブベクトルがないため結果から除外されます。 |
| Cosine のゼロノルム | ゼロノルムの組の cosine 距離は定義されず、一致できません。いずれかのクエリサブベクトルに対して定義済みの一致がない行は除外されます。したがって、ゼロノルムのクエリサブベクトルがあると結果はありません。 |
| 未サポートの形状と型 | 外側の large_list または fixed_size_list、可変長の内側のリスト、整数のマルチベクトル要素、extension/dictionary エンコーディング、マルチベクトルの hamming 検索はサポートされません。 |
パラメータの制限
M をクエリサブベクトル数、K = top_k、O = offset、R = refine_factor(マルチベクトル検索ではデフォルト 1)とします。
| 制約 | 上限 |
|---|---|
| クエリサブベクトル数 | 1 <= M <= 128 |
| 結果数とオフセット | K > 0、O >= 0 |
| クエリ候補数の上限 | M × (K + O) <= 100000 |
| 再評価する候補数の上限 | R × (K + O) <= 100000。R > 0 |
明示的な nprobes、ef、refine_factor | 正の 32 ビット符号付き整数で、最大 2147483647。refine_factor はさらに候補数の制限を受けます |
use_index=false を含め、二つの候補数の制限はそれぞれ独立して適用されます。たとえば M=128, K=1000, O=0 はクエリ候補数の上限を超えるため拒否されます。M=4, K=1000, O=0, R=10 は両方の制限を満たします。これらの制限は候補処理量を抑えるものであり、特定のメモリ使用量やクエリレイテンシーを保証しません。
インデックスの使用と再評価
組み込まれた Lance バージョンは、cosine 距離尺度のマルチベクトルインデックスをサポートします。cosine の IVF_FLAT や IVF_PQ など、既存の互換インデックスを使用するには、"metric" = "cosine" を設定して use_index=true を維持してください。metric を省略すると l2 が選ばれます。互換インデックスがない L2 と dot の検索は Flat Search を使用します。この関数で Doris はインデックスを作成しません。インデックスのメタデータは SHOW INDEX(Filesystem Catalog のみ)で確認し、lanceSearchIndexSegments > 0 かどうかを EXPLAIN で確認してください。
インデックス付き検索の候補選択は近似的です。マルチベクトル候補は、refine_factor を省略または 1 に設定した場合も常に元のベクトルで再評価されるため、インデックス付き行とインデックスなし行で同じ行単位スコアを使用します。refine_factor を増やすと候補集合が広がり、ベクトルの読み取りと計算が増えますが、網羅的な再現率は保証されません。nprobes は IVF の探索を制御し、ef は HNSW インデックスに適用されます。これらは再現率とレイテンシーを測定した後に調整してください。インデックス作成後に追加された行も Flat Search に含まれます。
対象行の網羅的なスコア計算には "use_index" = "false" を使用します。検索前に候補を制限するには、TVF の filter と prefilter=true を使用します。デフォルトの prefilter=false では候補生成後に条件を適用します。外側の SQL の WHERE は、生成済み候補に対して常に Doris が評価し、Split の結果を補充しません。次節のフィルタリング規則は単一ベクトル検索とマルチベクトル検索の両方に適用されます。
Prefilter と Post-filter
Prefilter と Post-filter は同じクエリで使用できます。
SELECT user_id, category, _distance
FROM vector_search(
"table" = "lance_catalog.default.items",
"column" = "embedding",
"query_vector" = "[0.1, 0.2, 0.3, 0.4]",
"top_k" = "10",
"prefilter" = "true",
"filter" = "category = 'book'"
)
WHERE user_id > 100
ORDER BY _distance ASC, user_id;
| フィルタの種類 | 条件例 | 適用時点 | 結果への影響 |
|---|---|---|---|
| TVF Prefilter | TVF パラメータ "filter" = "category = 'book'" と "prefilter" = "true" | Lance がベクトル候補を生成する前 | category = 'book' の行の中だけで最近傍を検索します。 |
| TVF Post-filter | TVF パラメータ "filter" = "category = 'book'"。prefilter は省略または false | Lance が候補を生成した後 | 生成された候補から一致しない行を除きます。候補は補充されないため、結果が top_k 行より少なくなる場合があります。 |
| Doris Scan Post-filter | 外側の WHERE user_id > 100 | Lance による候補生成後、Doris の最終 TopN 前 | 生成された候補から一致しない行を除きます。候補は補充されないため、最終結果が top_k 行より少なくなる場合があります。 |
user_id > 100 も候補生成に参加させる必要がある場合は、"filter" = "category = 'book' AND user_id > 100" のように TVF の filter に含め、prefilter=true を設定します。デフォルトの prefilter=false では候補生成後に条件が適用されます。オプティマイザーが外側の WHERE を Doris Lance Scan に移動しても、Doris Scan Post-filter のままであり、Lance Prefilter には変換されません。
filter でのみ参照する列は Lance が内部で読み取り、評価します。その列が SELECT やほかの Doris 式で参照されない場合、Doris に返す必要はありません。
FE テーブルアクセスキャッシュ
この設定には、テーブルアクセスキャッシュの変更を含む Doris ビルドが必要です。
各 FE は、Catalog 内でテーブルの解決済み Dataset URI とアクセスオプションをキャッシュし、クエリ計画時にファイルシステムでの再検出や REST の describeTable リクエストの繰り返しを避けられます。各 Catalog クライアントが保持するエントリは最大 10,000 件です。lance.table_access_cache_ttl_seconds のデフォルトは 60 で、キャッシュヒットによって存続時間は延びません。このキャッシュは Dataset のバージョンを保存しません。各読み取りでは引き続き Dataset を開き、スナップショットを選択します。
Namespace がバージョンを管理するテーブルは読み取りごとに再解決されるため、FE と BE はその読み取りで Namespace が返した場所とストレージオプションを使用します。提供されたストレージオプションを含む応答も、expires_at_millis がある場合を含め、読み取りごとに再解決されます。ユーザー情報、クエリパラメータ(署名付きまたは SAS の認証情報を含む)、フラグメントを含む URI もキャッシュされません。認証情報の有効期限に固定の余裕を設けてもスキャン中の有効性は保証できず、BE はスキャン中に認証情報を更新できません。こうした応答フィールドを含まない REST Catalog はキャッシュを使用できます。
テーブルまたはデータベースの明示的な更新は、対応するローカルのデータベース/テーブルオブジェクトが削除済みである場合に更新を再生する follower FE も含め、その Catalog のテーブルアクセスエントリをすべて消去します。通常のローカルデータベースオブジェクトの削除ではアクセスキャッシュは消去されません。キャッシュ無効化を伴う Catalog の更新、Namespace の削除、Catalog 設定の変更でもアクセスエントリは無効になります。インデックスの確認とインデックスジョブ対象の検証では常にアクセスを新たに解決します。
リモートテーブルの URI またはアクセス設定を変更した後は、TTL の期限切れを待たずに済むよう明示的に更新してください。既存のテーブル example_lance.default.items の例です。
REFRESH TABLE example_lance.default.items;
次の読み取りでテーブルアクセスが再解決されます。これでネイティブの Lance Session キャッシュは消去されません。同じ URI の Dataset を置き換えた後は、キャッシュ無効化を伴う Catalog の更新を使用してください。その更新で消去されるのは FE の Lance Session のみで、BE のキャッシュは消去されません。過去のバージョンまたはブランチの検索を参照してください。
既存の Catalog でテーブルアクセスキャッシュを無効にするには、次のようにします。
ALTER CATALOG example_lance SET PROPERTIES (
"lance.table_access_cache_ttl_seconds" = "0"
);
以後の読み取りでは毎回テーブルアクセスを再解決します。後述の BE キャッシュは独立して設定されます。
Lance Cache
Lance Cache はインデックス、メタデータ、データファイルの内容を再利用し、繰り返し読み取る量を減らします。各 BE が独自のキャッシュを管理し、その BE 上の Lance クエリが共有します。容量と内容は BE 間では共有されません。通常のスキャン、ベクトル検索、全文検索、第二段階の取得は、追加の CREATE CATALOG プロパティなしで対応するキャッシュを再利用できます。
キャッシュの種類と範囲
| キャッシュ | 保存先 | キャッシュする内容 |
|---|---|---|
| インデックスキャッシュ | BE メモリ | 読み込んだ Lance インデックスの内容。繰り返しのインデックス読み込みを減らします。 |
| メタデータキャッシュ | BE メモリ | Lance リーダーが使用するメタデータ。繰り返しの読み取りと解析を減らします。 |
| データキャッシュ | BE ローカルディスクと、読み取りブロック一つ分の容量を持つメモリ階層 | Dataset の data/ ディレクトリ直下にあり、名前が .lance で終わるファイルから読み取ったデータをブロック単位でキャッシュします。 |
データキャッシュは Lance リーダー内の Foyer を使用し、以下の lance_* BE パラメータで独自のディレクトリと容量を設定します。Doris の汎用 File Cache のディレクトリや容量設定は使用しません。インデックスファイル、manifest、削除ファイルはこのディスクデータキャッシュを経由せず、Lance の既存の読み取り経路とキャッシュ経路を使用します。
データキャッシュは必要に応じて埋められ、Dataset 全体を事前にダウンロードしません。キャッシュミス時は元のストレージから読み取り、バックグラウンドでのディスクキャッシュ書き込みにデータを投入します。最初の読み取りには元ストレージの I/O とキャッシュ投入の負荷がかかります。キャッシュヒットは以後の元ストレージへの読み取りを減らせますが、デコード、フィルタリング、ソートのコストはなくなりません。
BE の設定
以下のパラメータはすべて任意です。各 BE の be.conf に設定し、反映するにはその BE を再起動してください。容量は BE ごとにバイト単位で指定します。
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
lance_index_cache_size_bytes | Int64 | 10737418240(10 GiB) | インデックスのメモリキャッシュ容量。0 は容量なしです。 |
lance_metadata_cache_size_bytes | Int64 | 1073741824(1 GiB) | メタデータのメモリキャッシュ容量。0 は容量なしです。 |
enable_lance_data_cache | Boolean | true | ディスクデータキャッシュを有効にします。無効にしてもインデックスとメタデータのキャッシュは維持されます。 |
lance_data_cache_path | String | ${DORIS_HOME}/lance_data_cache | データキャッシュのディレクトリ。BE プロセスにディレクトリ作成とファイルの読み書き権限が必要です。BE プロセスごとに別のディレクトリを使用してください。 |
lance_data_cache_disk_capacity_bytes | Int64 | 107374182400(100 GiB) | ディスクキャッシュ容量。4096 の倍数で、読み取りブロックサイズの少なくとも二倍である必要があります。 |
lance_data_cache_read_block_size_bytes | Int64 | 1048576(1 MiB) | データキャッシュの読み取りブロックサイズ。正の値で 4096 の倍数である必要があります。データキャッシュのメモリ階層の容量も決めます。 |
たとえば、デフォルトの容量を明示し、別のローカルディスクディレクトリにキャッシュを置くには次のようにします。
lance_index_cache_size_bytes = 10737418240
lance_metadata_cache_size_bytes = 1073741824
enable_lance_data_cache = true
lance_data_cache_path = /mnt/ssd/lance_data_cache
lance_data_cache_disk_capacity_bytes = 107374182400
lance_data_cache_read_block_size_bytes = 1048576
BE の再起動後、最初に Lance Dataset を開いたときに共有キャッシュが初期化されます。データキャッシュが有効な状態でディレクトリが使用できない、容量またはブロックサイズが無効な場合、初期化に失敗し、Lance クエリはエラーを返します。データキャッシュなしの動作へ自動的にフォールバックしません。ディスクデータキャッシュを無効にするには、enable_lance_data_cache を false にして BE を再起動します。
インデックスキャッシュとメタデータキャッシュの容量は、クエリの作業用メモリと合わせて計画してください。これらの容量は Lance クエリ全体や BE プロセス全体のメモリ上限ではありません。ディスクキャッシュはローカルディスク容量とファイルディスクリプタも消費します。読み取りブロックを大きくするとブロック数は減りますが、小さな読み取りでは余分な I/O が増える場合があります。ブロックサイズやディスク構成を変更するときは、新しいキャッシュディレクトリを使用してください。
ワークロード別の容量計算式、設定例、共有キャッシュの競合、インデックスセグメントの粒度については、Lance クエリのベストプラクティスを参照してください。フィルタリングと検索を組み合わせる場合は、Lance Hybrid Search の性能に関するベストプラクティスを参照してください。
キャッシュ効果の確認
完了したクエリの Profile で、インデックスキャッシュのカウンターは LanceReader → LanceIndex、データファイルキャッシュのカウンターは LanceReader → LanceDataCache にあります。
| カウンター | 意味 |
|---|---|
LanceIndexCacheHits、LanceIndexCacheMisses | この実行について、計測対象のインデックス経路が報告したキャッシュ参照。BE 全体の Session メトリクスとは別です。 |
LanceIndexObjectLoads、LanceIndexComponentsLoaded | 読み込んだ最上位のインデックスオブジェクトと内部コンポーネント。どちらもキャッシュミス数とは同一視できません。 |
LanceDataCacheBytesReadFromCache | この Dataset ハンドルでデータファイルキャッシュから供給された論理リクエストバイト数。 |
LanceDataCacheBytesReadFromRemote | キャッシュミスまたはフォールバック後に元のストレージから供給された論理リクエストバイト数。元のストレージはローカルファイルの場合もあります。 |
二つのデータキャッシュのバイトカウンターには、ブロック読み取りによる増幅や、インデックスおよび manifest の読み取りなどデータキャッシュを経由しない I/O は含まれません。リモート通信量の全体を示すものではなく、合計が LanceIOReadBytes と一致する必要もありません。データキャッシュが無効な場合は両方とも 0 ですが、元のストレージからの読み取りがなかったことを意味しません。Doris は Dataset ハンドルを閉じる前に、その累積スナップショットを記録します。第二段階の取得には別のリーダー統計があり、Row ID Fetch/Materialization の Profile 情報にも出力されます。スキャンのカウンターだけではクエリ全体の取得 I/O を把握できません。収集タイミングとメトリクスの範囲については、Lance クエリ Profile リファレンスを参照してください。
BE の /metrics エンドポイントには、doris_be_lance_session_index_cache_ と doris_be_lance_session_metadata_cache_ を接頭辞とするメトリクスもあります。接尾辞 capacity_bytes、usage_bytes、entries、hits_total、misses_total は、それぞれ設定容量、現在の使用量、エントリ数、累積ヒット数、累積ミス数を表します。これらは共有 Lance Session の初期化後に登録され、個々のクエリではなく BE 全体のキャッシュを示します。
キャッシュ効果を比較するには、同じ Dataset バージョンとクエリパラメータを使用し、クエリが実際に同じ BE で実行されることを確認して、最初と繰り返しの読み取りにおけるレイテンシー、キャッシュカウンター、元ストレージの I/O を記録します。合計レイテンシーだけでは、キャッシュの効果とインデックス検索、デコード、第二段階の取得コストを区別できません。
二段階 TopN 読み取りと遅延マテリアライズ
vector_search() と full_text_search() は、最終的な top_k より多くの候補行を生成することが一般的です。検索中に title や payload などの幅広い出力列を読み取ると、大半の候補行が TopN で破棄されるため無駄になります。二段階読み取りでは、これらの列を後回しにします。第一段階ではフィルタリング、並べ替え、TopN に必要な列のみを読み取り、グローバル TopN の後、第二段階で残った行の出力列を読み取ります。
これによりストレージ I/O、ネットワーク転送、メモリ使用量を減らせます。top_k が小さい、候補が多い、または幅広い文字列列や JSON 列などを返すクエリで、効果が大きくなる傾向があります。
| 段階 | 読み取るデータ |
|---|---|
| 第一段階 | 検索内部で使う列、_distance または _score、Post-filter や並べ替えに必要な列、内部 Row Location。 |
| 第二段階 | 最終的な投影だけに使う最上位の列。グローバル TopN に残った行についてのみ読み取ります。 |
適用条件
Doris は、次の条件をすべて満たす場合にのみ二段階読み取りを使用します。
- クエリが
vector_search()またはfull_text_search()で Lance を読み取り、計画に遅延マテリアライズの対象となる TopN がある。通常の SQL クエリがこれらの検索 TVF に書き換えられた場合も対象になりえます。書き換えられていないスカラーテーブルスキャンと Lance ファイル TVF は対象外です。 - Boolean のセッション変数
enable_lance_lazy_materializationが、デフォルト値のtrueになっている。 - 少なくとも一つの最上位の列を後回しにできる。最終
SELECTの投影にのみ使う列は後回しにできます。Post-filter、ORDER BY、TopN 前のほかの式に使う列は第一段階で読み取る必要があります。ネストされたサブカラムは現在後回しにできません。
enable_lance_lazy_materialization は topn_lazy_materialization_threshold から独立しています。後者が -1 の場合や top_k がそのしきい値を超える場合も、Lance は二段階読み取りを使用できます。遅延マテリアライズをサポートするほかのテーブルは、引き続き一般的なしきい値に従います。スイッチを有効にすると最適化が許可されますが、適用の可否は計画構造と対象列によって決まります。
次のクエリでは、Post-filter のために category を第一段階で読み取る必要があります。一方、user_id、title、payload は TopN 後に取得できます。
SET enable_lance_lazy_materialization = true;
SELECT user_id, title, payload, _distance
FROM vector_search(
"table" = "lance_catalog.default.items",
"column" = "embedding",
"query_vector" = "[0.1, 0.2, 0.3, 0.4]",
"top_k" = "10",
"offset" = "3"
)
WHERE category = 'book';
TVF の filter に含まれる列は Lance が内部で使用します。filter の文字列に現れるだけでは、Doris に返される第一段階の結果列にはなりません。prefilter は、候補生成との前後関係のみを変更します。
計画の確認
上記のクエリの先頭に EXPLAIN VERBOSE を付けます。二段階読み取りが有効な場合、計画には VMaterializeNode が含まれ、その column_descs_lists に第二段階で取得する列が列挙されます。スイッチを無効にし、同じ単純な検索クエリで EXPLAIN VERBOSE を再度実行すると、対応するマテリアライズノードは消えるはずです。有効にしても表示されない場合は、出力列が TopN 前のフィルタリング、並べ替え、ほかの計算に使われていないか、また計画がこの最適化に対応するか確認してください。
二段階読み取りの無効化
二段階読み取りを無効にするには、次のセッション設定を使用します。
SET enable_lance_lazy_materialization = false;
後回しにできる列がない場合や計画が最適化に対応しない場合、Doris は単一段階の読み取りを使用します。top_k が大きいだけでは Lance の二段階読み取りは自動的に無効になりません。次の場合は無効にして性能を比較することを検討してください。
top_kが大きく、第二段階でも候補行の大部分を読み取る場合。- クエリが少数の幅の狭い列だけを返し、二段階読み取りで削減できる I/O が少ない場合。
- 基盤ストレージでランダムな Row-ID 読み取りのレイテンシーが高く、第二段階の Fetch の追加コストが後回しにした読み取りの節約分を上回る場合。
この最適化を無効にしても変わるのは出力列の読み取り時点だけです。ベクトルインデックスや FTS インデックスは無効にならず、Prefilter、Post-filter、TopN のセマンティクスも変わりません。代表的なクエリとストレージ条件で両設定を比較してください。
全文検索
full_text_search() は、Lance テーブルに既存の FTS 転置インデックスを使用して BM25 検索を行うリレーショナル TVF です。解析されたクエリ語を OR または AND で組み合わせたり、Phrase クエリで語順と距離を照合したりできます。Doris は物理インデックスセグメントからの候補をグローバル Top-K にマージし、ソース列に _score を追加します。スコアが高いほど関連性が高くなります。
TVF の使用前に、Lance SDK または別の Lance writer で対象の文字列列に FTS 転置インデックスを作成してください。Phrase クエリでは、インデックス作成時に token position の保存も有効にする必要があります。たとえば Lance のインデックスパラメータで with_position=true を設定します。Doris はこのインデックスを作成せず、FTS インデックスがない場合に行ごとの全文スキャンにもフォールバックしません。
構文と例
次のクエリは、カテゴリが storage の文書から lance database を検索し、その後 Doris の Post-filter として published = true を適用します。
SELECT document_id, title, _score
FROM full_text_search(
"table" = "lance_catalog.default.documents",
"column" = "body",
"query" = "lance database",
"query_type" = "match",
"operator" = "and",
"top_k" = "10",
"offset" = "0",
"prefilter" = "true",
"filter" = "category = 'storage'",
"coverage_mode" = "strict"
)
WHERE published = true
ORDER BY _score DESC, document_id;
この例は Match AND を使用するため、文書には解析された lance と database の両語が必要です。prefilter=true では Lance は FTS 候補の生成前に filter を評価します。prefilter を省略するとデフォルトの false になり、候補生成後に filter を適用するため、結果が top_k 行より少なくなる場合があります。外側の WHERE は Doris の Post-filter であり、除かれた候補は補充されません。published = true を候補生成に反映する必要がある場合は filter に含め、prefilter=true を設定します。
次の Phrase クエリは、隣接するクエリ語の間に最大一つの語を許します。たとえば lance search engine に一致します。
SELECT document_id, title, _score
FROM full_text_search(
"table" = "lance_catalog.default.documents",
"column" = "body",
"query" = "lance engine",
"query_type" = "phrase",
"slop" = "1",
"top_k" = "10"
)
ORDER BY _score DESC, document_id;
返されるリレーションには、ソースの Lance テーブルの全列と、nullable な FLOAT 型の _score 列が含まれます。ソーステーブルに同名の列が既にあってはなりません。TVF は _score の降順で Top-K を選択しますが、SQL リレーションでは最終的な表示順序は保証されません。安定した順序が必要な場合は ORDER BY _score DESC を明示し、同点に対して一意のタイブレーカーを追加してください。
パラメータ
| パラメータ | 必須 | デフォルト | 説明 |
|---|---|---|---|
table | はい | - | Lance Catalog 内のテーブルを示す、完全修飾された三要素の catalog.database.table 名。多階層 Namespace が . を含むデータベース名にマッピングされる場合は、その部分をバッククォートで囲みます。ユーザーにはそのテーブルの SELECT 権限が必要です。 |
column | はい | - | FTS 転置インデックスを持つ文字列列。Doris の TEXT にマッピングされる Arrow の utf8 と large_utf8 をサポートします。 |
query | はい | - | 空でない検索テキスト。FTS インデックス作成時に設定したトークナイザーで処理されます。 |
query_type | いいえ | match | クエリ種別。有効な値は match と phrase です。 |
operator | いいえ | or | Match クエリ専用。or は一つ以上のクエリ語、and はすべてのクエリ語に一致する必要があります。Phrase クエリでは設定できません。 |
slop | いいえ | 0 | Phrase クエリ専用。0 から 2147483647 の整数です。0 は語句の完全一致を要求し、正の値は隣接するクエリ語の間に許す語の最大数です。Match クエリでは設定できません。 |
top_k | いいえ | 10 | offset をスキップした後に返す結果数。正の整数である必要があります。 |
offset | いいえ | 0 | 関連性に基づいてスキップする結果数。非負の整数で、top_k + offset は符号なし 32 ビット整数の最大値を超えられません。 |
filter | いいえ | - | Lance SQL 条件。実行タイミングは prefilter で制御します。 |
prefilter | いいえ | false | TVF の filter を適用するタイミングを制御します。true は全文検索の候補生成前、デフォルトの false は候補生成後にフィルタリングするため、結果が top_k 行より少なくなる場合があります。外側の Doris の WHERE には影響しません。 |
coverage_mode | いいえ | strict | FTS インデックスが現在のスナップショットの全 Fragment をカバーしない場合の動作。有効な値は strict と index_only です。 |
version、timestamp、tag、branch | いいえ | - | main の最新バージョンの代わりに、過去のバージョン、指定時刻のバージョン、タグ、ブランチを検索します。過去のバージョンまたはブランチの検索を参照してください。 |
クエリ種別
| クエリ種別 | 一致条件 | 関連パラメータ | インデックスの要件 |
|---|---|---|---|
| Match OR | 解析されたクエリ語のうち一つ以上に一致します。デフォルトです。 | query_type=match、operator=or | 標準の FTS 転置インデックス。 |
| Match AND | 解析されたクエリ語すべてに一致します。 | query_type=match、operator=and | 標準の FTS 転置インデックス。 |
| Phrase | 解析されたクエリ語の順序を保ち、slop で指定した距離を適用します。 | query_type=phrase、slop=N | FTS インデックスに token position の保存が必要です。 |
Boolean、Boost、Prefix、Wildcard、Regex、およびフィールドをまたぐ複合 FTS クエリは現在サポートされていません。
インデックスのカバーモード
| モード | 動作 | 使用する場面 |
|---|---|---|
strict | 選択した FTS インデックスが、クエリで固定したスナップショットのすべての Fragment をカバーする必要があります。未カバーの Fragment があればクエリは失敗します。 | デフォルトで推奨されるモード。データの欠落を許容できない場合に使用します。データ追加後は検索前に FTS インデックスを更新または再構築してください。 |
index_only | FTS インデックスがカバーする Fragment だけを検索し、未カバーのデータは無視します。 | 不完全な結果を許容でき、インデックス更新待ちの間も検索を続ける必要がある場合にのみ使用します。 |
どちらのモードでも、対象列にコミット済みでカバー範囲のメタデータが完全な FTS インデックスが必要です。使用可能なインデックスがなければクエリは失敗します。一つの列には論理 FTS インデックスを一つだけ保持してください。一致するインデックスが複数あると、Doris は一意に選べずクエリを拒否します。
実行方法は EXPLAIN で確認します。lanceFtsQueryType は Match または Phrase、lanceFtsMatchOperator は Match の OR/AND 演算子、lanceFtsPhraseSlop は Phrase の距離を表示します。lanceFtsCoverageMode はカバーモード、lanceSearchIndexSegments は使用する物理 FTS インデックスセグメント数、lanceSearchUnindexedFragments は現在のスナップショットでインデックスにカバーされない Fragment 数を示します。
過去のバージョンまたはブランチの検索
デフォルトでは vector_search() と full_text_search() は main の最新バージョンを検索します。四つの任意パラメータで、テーブルの Time Travel 構文と同じ意味で別のスナップショットを選択できます。
| パラメータ | 値 | 同等のテーブル構文 | 併用可能なパラメータ |
|---|---|---|---|
version | 正の整数のバージョン番号 | FOR VERSION AS OF N | branch |
timestamp | セッションのタイムゾーンでの yyyy-MM-dd HH:mm:ss または yyyy-MM-dd HH:mm:ss.SSS | FOR TIME AS OF '...' | branch |
tag | タグ名 | @tag(name) | なし |
branch | ブランチ名。main はメインの系列 | @branch(name) | version または timestamp |
-- Search version 3.
SELECT id, _distance
FROM vector_search(
"table" = "lance_catalog.db.documents",
"column" = "embedding",
"query_vector" = "[0.1, 0.2, 0.3]",
"version" = "3")
ORDER BY _distance;
-- Search the branch "dev" as it was at a point in time.
SELECT id, _score
FROM full_text_search(
"table" = "lance_catalog.db.documents",
"column" = "content",
"query" = "database",
"branch" = "dev",
"timestamp" = "2026-09-20 12:00:00")
ORDER BY _score DESC;
- スナップショットはテーブル構文と同じ規則で選択されます。ブランチを指すタグや、REST Namespace がバージョンを管理するテーブルも同様です。
versionはバージョン番号のみを受け付けます。FOR VERSION AS OFとは異なり、タグ名は受け付けません。tagで曖昧さなく指定できるためです。123という名前のタグは"tag" = "123"で選択します。 versionとtimestampは併用できず、tagは残りの三つのどれとも併用できません。空の値を設定したパラメータは無視されず、エラーになります。- 出力スキーマ、検索列、ベクトルおよび FTS インデックスのメタデータ、Fragment はすべて選択したスナップショットから取得します。候補生成、フィルタリング、Top-K、二段階読み取りも同じスナップショットを使用します。過去のバージョンでは、そのバージョンでコミットされたインデックスを使用します。ベクトルインデックス作成前のバージョンでは Flat Search になり、FTS インデックス作成前のバージョンは
full_text_search()で検索できません。coverage_modeはそのバージョンの Fragment を検査します。 - スナップショットを選択できない場合やインデックスファイルが欠けている場合はエラーです。最新バージョンへのフォールバックはありません。Lance の cleanup で削除されたバージョンは見つからないものとして報告されます。タグで保持されたバージョンのインデックスファイルは cleanup 後も保持されます。別の方法で削除された場合は実行時に失敗し、エラーにはデータセットバージョンが示されます。
- 準備済みステートメントの各
EXECUTEを含め、実行ごとにスナップショットが再選択されます。そのため、最新バージョン、将来の時刻、ブランチ、移動したタグでは、実行ごとに別のバージョンが選ばれる場合があります。四つのパラメータは定数である必要があります。準備済みステートメントでvector_search()がプレースホルダー(?)を受け付けるのはquery_vector、top_k、offset、filterのみで、full_text_search()はどのパラメータにも受け付けません。 - 各検索リレーションは独自のスナップショットを選択します。同じ文で同じテーブルに対する二つのリレーション、たとえば
vector_search()とテーブル自体を結合する場合、その間に新しいバージョンがコミットされると異なるバージョンを読み取る可能性があります。同じバージョンを読むには、検索関数のversionとテーブルのFOR VERSION AS OFの両方を固定してください。 CREATE TABLE AS SELECTは新しいテーブルのスキーマ用と行用にクエリを二度計画するため、変動するセレクターでは異なるバージョンが選ばれる場合があります。一つのバージョンを正確にコピーするにはversionを設定してください。EXPLAINは選択したバージョンをlanceVersion、ブランチをlanceBranch、REST Namespace がバージョンを管理するかどうかをlanceManagedVersioningとして表示します。EXPLAINでもスナップショットが再選択されるため、実際の実行で読み取った内容はクエリ Profile のLanceDatasetVersionとLanceDatasetUriに記録され、LanceSearchTypeなど Lance Scanner の情報とともに表示されます。URI にはブランチディレクトリが含まれ、クエリ文字列とパスワードは含まれません。- 別のブランチまたは shallow clone から作成したブランチでは、継承したインデックスファイルが見つからない場合があります。バージョン 13 より前の Lance writer が中間のブランチの下に記録するためです。その場合、検索はエラーで失敗しますが、そのブランチ自身のインデックスには影響しません。
- ブランチを削除後に同じ名前で再作成するか、同じ URI の Dataset を置き換えると、新しいデータで古いバージョン番号が再利用されます。BE はエントリが削除されるか再起動するまで、それらの番号についてキャッシュした古い内容を使用し続ける場合があります。安定した row ID を持つ Dataset では、ベクトル検索と全文検索が古いデータの有効行に基づいてフィルタリングし、新しいデータでは削除済みの行を含めたり、現在有効な行を見落としたりする場合があります。manifest が Lance の旧命名方式(
_versions/<version>.manifest)を使用する場合や、オブジェクトストアが ETag を返さない場合、BE と FE が古いインデックスのメタデータを使用することもあります。FE は Catalog の更新後に古いメタデータの使用をやめます。再作成するブランチには新しい名前を付けるか、BE を再起動してください。Catalog の更新ではこれらの BE キャッシュは消去されません。 - token position を保存していない FTS インデックスでは Phrase クエリを実行できません。過去のバージョンが引き続き使用する、古い writer によって作られたインデックスには、位置情報がないことがよくあります。
現在の実行モデル
vector_search() と full_text_search() の実行順序は次のとおりです。
Dataset snapshot selected by version / timestamp / tag / branch, or the latest version of main
-> FE search Split planning
-> Vector search: physical vector Index Segments + Flat Search for uncovered Fragments
-> Full-text search: physical FTS Index Segments (coverage checked by coverage_mode)
-> Per Split: vector/full-text search; the TVF `filter` runs before candidate generation when `prefilter=true`, and after candidate generation when `prefilter` is omitted or `false`
-> at most K+n candidates
-> Doris Scan Post-filter
-> Doris local TopN
-> Exchange
-> Doris global TopN (applies offset=n and limit=K)
-> Optional lazy-materialization Fetch
クエリ Profile
Profile の収集と表示については、クエリ Profile 分析ガイドを参照してください。Lance 固有のグループ、カウンター、計測時間の境界、第二段階の取得統計については、Lance クエリ Profile リファレンスを参照してください。
現在の制限と推奨事項
- Lance Catalog と Lance TVF は読み取り専用です。
CREATE TABLE、INSERT、UPDATE、DELETE、TRUNCATE TABLE、Lance へのデータの書き戻しはサポートされていません。 - 未サポートの列型を含むテーブルでは、
SELECT *で未サポートの列を投影せず、読み取る列を明示的に列挙してください。 - 通常のスキャンでは
EXPLAINのlancePushdownPredicateを確認し、プッシュダウンされた条件を検証してください。 - インデックス付きベクトル検索の前に、意図するクエリに一致するベクトルインデックスを Lance に作成してください。小さなデータセットや検証には
"use_index" = "false"を設定し、Flat Search を実行できます。 - 全文検索の前に Lance に FTS 転置インデックスを作成してください。デフォルトの
strictモードでは、インデックスが現在のスナップショットのすべての Fragment をカバーしない場合、クエリは拒否されます。データの欠落を許容できる場合にのみindex_onlyを使用してください。 - Phrase クエリでは FTS インデックスに token position の保存が必要です。Phrase クエリが必要な場合、インデックス作成時に
with_position=trueを設定してください。 - Filesystem Catalog のテーブルでは
SHOW INDEXで Lance の論理インデックスを確認できます。たとえばベクトル検索や全文検索の前にインデックス名、種別、対象フィールドを確認します。REST Catalog ではSHOW INDEXはサポートされません。 - ベクトル検索結果の順序を確定させるには、
ORDER BY _distance ASCを明示して一意のタイブレーカーを追加してください。 - 全文検索結果の順序を確定させるには、
ORDER BY _score DESCを明示して一意のタイブレーカーを追加してください。 - ベクトルまたは全文検索の候補生成前にフィルタリングするには、TVF の
filterとprefilter=trueを設定してください。デフォルトのprefilter=falseでは、TVF のfilterは候補生成後に適用されます。外側のWHEREは各検索 Split が生成した候補に対して Doris がグローバル TopN 前に評価するため、最終結果がtop_k行より少なくなる場合があります。 EXPLAINでlanceSearchFragmentsとlanceSearchIndexSegmentsを確認してください。前者は固定されたスナップショットで可視の Fragment 数、後者は FE が選択した物理インデックスセグメント Split 数です。ベクトル検索にはフォールバック用の Flat Search Fragment Split が含まれる場合もあります。全文検索は Flat Search にフォールバックしません。