lancedb

LanceDB パイプラインの構築

このスキルを使って、ローカルテーブルとリモートテーブル（LanceDB Enterprise／Cloud）で移植可能な、選択した SDK に適した LanceDB パイプラインを作成します。

LanceDB のテーブルモード

LanceDB には、一般的な実行モードが 2 つあります。

• ローカルテーブル：埋め込み型のオープンソース版で、プロセス内で動作する LanceDB です。クライアントは、ローカルパスまたはオブジェクトストレージ URI からデータを開き、アプリケーションのプロセス内でクエリを実行します。
• リモートテーブル：db://... URI を使って開く LanceDB Enterprise／Cloud のテーブルです。データが非常に大きい場合があり、一般的にはオブジェクトストレージに保存され、リモートサービスを通じてクエリされます。

リモートテーブルで、ローカル専用のテーブルヘルパーが使えると想定しないでください。ユーザーが LanceDB Enterprise、Cloud、db://...、本番環境でのリモートアクセス、またはリモートテーブルを求めている場合は、リモートテーブルの方法に重点を置いてください。search()／query() を使い、select() と limit() で読み取り範囲を限定し、テーブル全体をメモリに展開する API は避けてください。

ワークフロー

1. SDKを確認します。Python、TypeScript、またはその両方です。
2. テーブルモードを確認します。ローカル／埋め込み OSS、リモート Enterprise／Cloud、または両方で利用可能なモードです。ユーザーが「LanceDB Enterprise」と指定した場合は、リモートテーブルのパスを選択します。ジョブに関する作業（一覧表示、調査、作成、キャンセルなど）が含まれる場合は、必ずリモートパスを選択し、リモートサーバーへの接続が必要です。何よりも先に、以下の「LanceDB リモートサーバーへの接続」を参照してください。
3. コードを作成または変更する前に、該当する言語ブランチを読みます。
   • Python のパターン：references/python/patterns.md
   • Python API クイックリファレンス：references/python/api_reference.md
   • Python のパフォーマンスガイダンス：references/python/performance.md
   • TypeScript のパターン：references/typescript/patterns.md
   • TypeScript API クイックリファレンス：references/typescript/api_reference.md
   • TypeScript のパフォーマンスガイダンス：references/typescript/performance.md
   • カラムメタデータの作成（両方の SDK）：references/column_metadata.md
   • ブランチ操作（両方の SDK）：references/branch_ops.md
   • リモートサーバー接続の解決（ジョブ、raw REST）：references/remote_connect.md
   • ジョブ操作 REST API（list／describe／cancel／query_events）：references/remote_jobs.md
4. 選択した SDK の patterns.md から読み始めます。メソッド名や戻り値のコレクターを選ぶ際は、api_reference.md を読みます。取り込み、インデックス作成、フィルタリング、クエリのチューニング、診断、大規模データセットに関する作業では、performance.md を読みます。テーブルのカラムの説明、タグ付け、分類、グループ化（フィールドの説明、lancedb:tag:* タグ、論理カラムファミリー）に関する作業では、column_metadata.md を読みます。ブランチのライフサイクル（一覧表示／作成／削除）、main 以外のブランチへの書き込み、または変更が main に反映されていないことの検証に関する作業では、branch_ops.md を読みます。ジョブまたは Enterprise デプロイメントへの直接の REST アクセスに関する作業では remote_connect.md を読み、ジョブの REST メソッド（list、describe、cancel、query_events）については remote_jobs.md を読みます。
5. Python のスキーマには Pydantic モデルを優先し、書き込み前にレコードを検証します。Arrow ネイティブ、ストリーミング、または高度に動的なデータによって明らかな利点がある場合は、PyArrow スキーマを使用します。
6. 読み取りには、明示的な select() と limit() を指定した search() または query() ビルダーを優先します。
7. リモートまたはポータブルなコードでは、テーブル全体のマテリアライズを避けます。これはローカルとリモート間の読み取りで最も注意すべき点です。
8. 埋め込み OSS への取り込みが成功したら、table.optimize() を呼び出します。Enterprise／Cloud では呼び出さないでください。リモートのメンテナンスは自動で行われます。
9. リモート Enterprise／Cloud への書き込みでは、同じテーブル名に対してテーブルを削除してから再利用したり、mode="overwrite" を使用したりしないでください。以下の「Enterprise：同じテーブル名を削除してから再利用しない」を参照してください。これはローカルとリモート間の書き込みで最も注意すべき点です。
10. 既存のファイルやリポジトリをレビューする場合は、該当するパスに対して scripts/check_materialization.py を実行し、編集前に各指摘を確認します。
11. 慣れていない API や複雑な API に関する主張は、記憶に頼らずソースツリーと照合します。

コアとなるポータビリティのルール

リモートテーブルでローカルテーブル API が利用できると想定したコードを書かないでください。リモートテーブルは非常に大きくなる可能性があるため、テーブル全体をマテリアライズするヘルパーは、意図的に利用できないか、安全ではありません。

これは、結果の変換が禁止されているという意味ではありません。範囲を限定したクエリ／検索結果の収集は一般的な方法です。

• Python：table.search(...).select([...]).limit(10).to_pandas()
• TypeScript：await table.search(...).select([...]).limit(10).toArray()

安全でないパターンは、テーブル全体または範囲を限定しない収集に加え、リモートコードでローカル専用のデータセットへのエスケープハッチを使用することです。

• Python：table.to_pandas()、table.to_arrow()、table.to_polars()。table.to_lance() はローカル／OSS 専用のデータセットアクセスであり、マテリアライズではありません
• TypeScript：await table.toArrow()、limit() のない await table.query().toArray()

Enterprise：同じテーブル名を削除後にすぐ再利用しないでください

LanceDB Enterprise/Cloud では、コントロールプレーン（DDL：作成／削除／名前変更）と、読み取りを処理するクエリノードからなるデータプレーンが分かれています。クエリノードはテーブル名に解決されたデータセットを、table_cache_ttl の期間（最大）キャッシュします。デフォルトは **300 秒（5 分）**です。テーブルを削除または上書きした後、コントロールプレーンはすぐに更新されますが、データプレーンはそのキャッシュエントリの期限が切れるまで 古い データセットを提供し続けます。この間、2 つのプレーンの状態は一致しません。

これにより、drop_table("t") の直後に create_table("t", ...)（または create_table("t", ..., mode="overwrite")）を実行すると、問題が発生します。DDL は成功を返しますが、t に対するすべてのクエリが 500 Internal Server Error を返します（クエリノードが古い、または削除済みのデータセットを解決するため）。新しい describe でも、古い スキーマ／バージョンが表示されることがあります。書き込みが密かに失敗したように見えますが、そうではありません。名前がキャッシュされているのです。

mode="overwrite" にも同じ問題があります — 内部では同じ名前の削除と作成が行われます。

Enterprise で移植性のあるデータ取り込みを行うためのルール：

1. 削除または上書きしたテーブル名は、キャッシュ TTL の期間内に再利用しないでください。 既存の Enterprise テーブルをその場で置き換えるために mode="overwrite" を使わないでください。
2. データを読み込み直す場合は、新しいテーブル名に書き込んでください（例：<table>_v2、または実行時刻を付けたサフィックス）。まったく新しい名前にはデータプレーンのキャッシュエントリがないため、書き込みと読み取りはすぐに動作します。
3. 作成前に list_tables() を実行し、名前がすでに存在する場合は上書きせず、エラーを明確に通知してください — 新しい名前を指定するよう求めます。
4. 現在、古いテーブルが使っている特定の最終名に移行する場合：古いテーブルを削除し、TTL が経過するまで（約 5 分）待ってから、rename_table(fresh_name, final_name) を実行してください。古いデータセットがまだキャッシュされている名前に変更すると、同じ競合が発生するため、待機が必須です。rename_table はサポートされているコントロールプレーン操作です。
5. テーブル名を人に伝える際は、伝播を待つ必要がある手順を明記してください（通常は「古い t は削除済みです。約 5 分後に名前変更を実行してください」）。

これは Enterprise/Cloud 固有の動作です。ローカル／OSS のテーブルには独立したデータプレーンがないため、そこでの mode="overwrite" と同じ名前の即時再利用は問題ありません。

LanceDB リモートサーバーへの接続

LanceDB Enterprise/Cloud のデプロイは、lance-namespace OpenAPI 仕様（https://github.com/lance-format/lance-namespace/blob/main/docs/src/spec.yaml）を実装するサーバーによって提供されます。すべてのリモート（db://...）接続はこのようなサーバーと通信し、一部の操作はサーバー上でのみ実行できます。特に、ジョブに関するすべての操作（ジョブの一覧表示、詳細確認、作成、キャンセル）はサーバー側で実行されます — ローカル／OSS に相当する機能はありません。ジョブ関連の作業、または Enterprise デプロイへの直接 REST 呼び出しを行う前に、references/remote_connect.md を読んでベース URL、認証情報、データベースヘッダーを確認し、接続を検証してください。その後、references/remote_jobs.md に記載されている 4 つのジョブ REST メソッド（list、describe、cancel、query_events）を使用してください。

スクリプト

既存のコードベースをレビューまたは変更する際は、スキャナーを実行してください：

python skills/lancedb/scripts/check_materialization.py path/to/file_or_dir

このスクリプトは、Python と TypeScript において、テーブル全体を安全でない方法でメモリに展開している可能性がある箇所を報告します。結果はレビューのきっかけとして扱い、バグの確定的な証拠とは見なさないでください。