MatrixOne Python SDK: ベクトル検索、スナップショット、診断ツール

MatrixOne 内の Python SDK

この README は matrixorigin/matrixone リポジトリの clients/python ディレクトリにあります。これは、MatrixOne に SQLAlchemy 風のインターフェースを提供する Python SDK を文書化しており、データベース操作、ベクトル検索、全文検索、スナップショット管理、ポイントインタイムリカバリ、テーブルクローン、mo-ctl ツールとの統合をカバーしています。README は、SDK が AI 支援開発を通じて生成および最適化されたと述べていますが、これはその由来に関する主張であり、品質の測定ではありません。SDK の機能リストには接続プーリング、非同期サポート、型ヒントが含まれますが、README はベンチマークや独立したパフォーマンス検証を提供していません。 実行日時、版、環境、入力識別子、出力要約、警告を記録し、再現不能な結果は成功例として扱いません。

インストールと開発環境のセットアップ

安定版は pip install matrixone-python-sdk で PyPI からインストールします。test.pypi 上のプレリリースチャネルも文書化されており、PyMySQL や SQLAlchemy などの依存関係を公式インデックスから取得するには --extra-index-url が必要であると注記されています。開発には、リポジトリをクローンし、仮想環境または conda を使用し、make dev-setup または pip install -e '.[dev]' を実行することを README は推奨しています。テスト依存関係は分離されています: テストスイートには pip install -e '.[test]'、Parquet サポートには pyarrow>=10.0.0 が必要です。README は SQLAlchemy 1.4 と 2.0 用の特定の requirements ファイルもリストしています。

クライアント、セッション、データ操作

Client クラスはキーワード引数で接続し、database 名が必須です。host、port、user、password にはデフォルト値があります。session() コンテキストマネージャーはアトミックなトランザクションを提供し、すべてがコミットまたはロールバックされます。データロードメソッドは pandas を模倣しています: read_csv、read_json、read_parquet は sep、quotechar、skiprows、encoding などのパラメータを受け入れ、ローカルファイル、インライン文字列、stage:// パスから読み取ることができます。エクスポートは to_csv と to_jsonl を使用し、pandas スタイルのオプションも備えています。AsyncClient は async/await をサポートし、SDK は既存の SQLAlchemy セッションをラップして、完全な書き直しなしで MatrixOne 固有の操作を追加できます。

ベクトル検索と全文検索

ベクトル検索は HNSW と IVF インデックスアルゴリズムをサポートし、f32 と f64 のベクトル精度、L2、コサイン、内積の距離メトリックを備えています。README は get_ivf_stats() を本番環境での重要なモニタリングツールとして強調し、セントロイド分布とバランス比率を表示し、ランキングモードを制御する IVF LIMIT BY RANK にも言及しています。全文検索は BM25 と TF-IDF を使用し、自然言語とブールモード、複数列インデックス、関連性スコアリングを備えています。ドキュメントは must、should、must_not 演算子を含む boolean_match の例を示していますが、再現率やレイテンシの数値は公開していません。

スナップショット、リカバリ、ブランチ、ステージ、メタデータ

SDK は複数レベルのスナップショット作成、ポイントインタイムリカバリ、テーブルとデータベースのクローン、そして README がデータベースの Git スタイルのバージョン管理と説明するブランチ管理を公開しています。ブランチは作成、差分、マージができ、競合解決オプションがあります。ステージ管理はローカルファイルシステム、S3、その他のクラウドストレージをカバーし、アトミックなマルチファイルロードのためのトランザクションサポートがあります。メタデータ分析はテーブルと列の統計（行数、NULL 数、圧縮サイズ）を返します。セカンダリインデックス検証はテーブルとそのインデックス間の行数整合性をチェックします。バージョン検出は 8.0.30-MatrixOne-v3.0.0 などのバックエンドバージョンを解析し、互換性チェックを提供します。アカウント管理と pub/sub が機能リストを完成させます。

mo-diag 診断ツール

mo-diag は SDK とともにインストールされるコマンドラインツールです。タブ補完、コマンド履歴、色付き出力を備えたインタラクティブシェルと、スクリプト用の非インタラクティブモードを提供します。コマンドはインデックス検査をカバーしています: show_indexes は IVF、HNSW、全文インデックスの物理テーブルを表示し、show_ivf_status はセントロイド数とバランスを報告し、verify_counts は行の整合性をチェックし、flush_table はメインテーブルとインデックステーブルをフラッシュします。テーブル統計はオブジェクトレベルの詳細で表示できます。README には、日常のヘルスチェック、カウント不一致のデバッグ、ストレージ分析の例が含まれています。また、mo-diag cdc による CDC タスクショートカットも文書化されています。

列命名と SQLAlchemy 統合

README には強い警告があります: 列名は小文字とアンダースコアでなければなりません。MatrixOne は SQL 標準の二重引用符付き識別子をサポートしていないため、キャメルケースの列名は SELECT ステートメントを失敗させますが、CREATE TABLE と INSERT は成功します。ドキュメント化されたパターンは、ORM モデルで常に snake_case を使用することです。SDK はクローンとブランチのための SQLAlchemy スタイルのステートメントビルダーも提供し、既存の SQLAlchemy セッションをラップして、レガシーコードが段階的に MatrixOne 機能を採用するのに役立ちます。

テストとドキュメント

README はオフラインモックテスト（450+）、オンライン統合テスト（100+）、Python 3.10/3.11 と SQLAlchemy 1.4/2.0 を横断するマトリックステストを説明しています。test-offline、test-online、test-sqlalchemy20 などの make ターゲットをリストしています。完全なドキュメントは ReadTheDocs でホストされ、クイックスタート、ベクターガイド、API リファレンスへのリンクがあります。README は examples/ ディレクトリを指し、接続、トランザクション、ベクトル検索、ロード操作、ステージ、ビルダーをカバーする 20 以上のサンプルスクリプトを含んでいます。

編集部の結論

SDK のドキュメントは広範な領域をカバーしています: ベクトル検索と全文検索、スナップショット、PITR、クローン、ブランチ、ステージ、メタデータ、アカウント管理、pub/sub。また、列命名に関する具体的な要求を行い、インデックスの健全性を監視するための診断ツールを提供します。README にはベンチマーク数値や本番保証は記載されておらず、それらの主張は他の情報源から確認する必要があります。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes