MatrixOne 通用 Python SDK¶
matrixone-python-sdk 的导入入口是 from matrixone import Client, AsyncClient,提供关系型 SQL、事务、ORM 和 MatrixOne 功能管理接口。它与独立的 mo-vector / mo_vector 包不同;向量包装器不能替代通用 SDK,也不能由方法名称推断全文或混合检索已经实现。
选用哪个 Python 接口¶
接口 |
使用方式 |
适用场景 |
|---|---|---|
PyMySQL |
|
MySQL 协议、游标与驱动层控制,见Python 连接 |
SQLAlchemy |
Engine、Core、ORM |
通用 SQL 和事务;使用 SDK 的 Engine 时保留其连接生命周期 |
通用 SDK |
|
Client/AsyncClient、Session、MatrixOne 特有功能管理 |
独立向量包 |
|
另一套向量 API,见向量 SDK 示例 |
Python UDF |
数据库服务端调用 Python |
与客户端 SDK、Notebook 分属不同执行位置,见Python UDF |
版本与安装¶
本页及基础实验核对 PyPI matrixone-python-sdk==0.1.16、MO v4.2.5 与 Python 3.12.14。SDK 元数据声明 Python>=3.8;本次没有认证全部 Python/依赖组合。读取 importlib.metadata.version('matrixone-python-sdk'),不要将模块的 matrixone.__version__ 当作发行版本:该发行包实测返回 1.0.0,而包元数据为 0.1.16。
python -m venv .venv
. .venv/bin/activate
python -m pip install matrixone-python-sdk==0.1.16 PyMySQL==1.1.1 aiomysql==0.3.2 SQLAlchemy==2.0.43
python -c "from importlib.metadata import version; print(version('matrixone-python-sdk'))"
包名、SDK 版本、数据库版本和依赖版本分别记录。SDK 0.1.16 的发行元数据分类为 Beta;数据库稳定版与 SDK 的发布状态分别判断。源码开发路径是 clients/python;固定服务端 v4.2.5 对应源码,不要使用旧文档中的 clients/python-wrapper 路径。该 tag 下 48 个 SDK Python 源文件与本次安装的 0.1.16 wheel 内容一致;外部 ReadTheDocs 的 latest 会变化。
能力与文档入口¶
下面是公开接口与拥有文档的入口,表示 API/文档存在;不表示本次已验证所有组合、权限或生产行为。SDK 自带文档已有 25 个顶层 RST 文件和 28 个 API RST 文件,手册需要统一入口和中文说明,而不是只介绍向量。
能力 |
SDK 入口 |
固定版本参考与验收重点 |
|---|---|---|
连接、连接池、登录租户/角色、连接钩子 |
Client.connect、from_engine、on_connect |
|
同步/异步 SQL |
Client、AsyncClient |
|
事务与结果 |
client.session、Session、ResultSet |
|
ORM 与查询构造 |
client.query、SQLAlchemy 表达式 |
ORM;类型、命名、实际生成 SQL |
向量/索引 |
vector_ops、Vectorf32/Vectorf64 |
向量;距离含义、维度、索引存在和执行计划 |
全文与 JSON |
fulltext_index、boolean_match、JSON 运算 |
|
元数据与索引检查 |
metadata、索引验证方法 |
|
文件加载、导出、Stage |
load_data、export、stage |
|
快照、恢复、PITR |
snapshots、restore、pitr |
快照/恢复;权限、保留期、恢复后的新写入处理 |
Clone、Branch |
clone、branch |
|
租户、用户、权限、发布订阅 |
account、pubsub |
|
CDC 管理 |
client.cdc、CDCManager |
实现;MO 源端任务控制,不等于 MySQL 源入站 CDC;独立 API/流程文档仍需补齐 |
诊断、运维与版本 |
mo-diag、moctl、version |
|
pandas/NumPy/机器学习 |
SQL 取数后交给 Python 库 |
SDK 没有内置 DataFrame/模型训练执行器;见教程目录,Python 计算不自动下推数据库 |
英文手册另有向量、全文、混合检索、Clone 等专题;这些内容的中文覆盖和版本验收仍不完整。外部功能指南的存在不能代替实际测试。
必须解释的边界¶
connect()使用关键字参数;账号有目标库权限,数据库已存在。示例设置on_connect=[],不自动开启与关系型实验无关的功能钩子。Client.execute()的返回对象是已缓冲的 ResultSet;client.session().execute()返回 SQLAlchemy Result。scalar()、rows/columns、rowcount/affected_rows不能在两者之间任意替换。多条 DML 要求共同提交时,放进一个
client.session(),异常必须传播出上下文。不要把 DDL、快照、账号管理等所有操作都称为同一可回滚事务。原始字符串的
?替换与驱动绑定不是同一机制;包含字面量问号的 SQL 实测会被错误替换。示例采用session.execute(text(sql), params)的真实绑定;值与标识符分别处理,表/列名不能用值参数绑定。fetchmany()切分已经缓冲的结果,不限制服务端取数内存。先用 WHERE/聚合减少数据,或按稳定唯一键分页;不断变化的数据还需要明确一致性边界。load_data.read_csv/read_parquet 的 pandas 风格名称表示加载到数据库,并不返回 DataFrame;export.to_csv 的文件也不一定落到 Notebook 本机。按 INFILE/LOCAL/INLINE/Stage 方向及权限验证。
AsyncClient 在 SDK 0.1.16 / SQLAlchemy 2.0.43 / aiomysql 0.3.2 / PyMySQL 1.2.3 下实测发生
ping() missing ... reconnect;同一查询固定 PyMySQL 1.1.1 后通过。不要把无限制升级依赖作为已经验证的异步安装方案。见依赖兼容问题 #30242。需要 TLS 时同步客户端设置
ssl_mode='required'与 CA,并检查服务器身份;本次本地实验未认证远端 TLS、故障转移或生产连接池容量。关闭普通 SQL 日志也不保证错误信息不含数据。
实测依赖组合¶
以下均为 SDK 0.1.16、Python 3.12.14、MO v4.2.5;不同范围不能当作等价认证:
SQLAlchemy |
PyMySQL |
aiomysql |
验收结果 |
|---|---|---|---|
2.0.43 |
1.1.1 |
0.3.2 |
同步 CRUD、事务、数据科学完整实验与异步取数通过;本教程固定组合 |
2.0.43 |
1.2.3 |
0.3.2 |
异步 pre-ping 报 reconnect 参数错误 |
2.1.4 |
1.2.3 |
0.3.2 |
同步/异步 SELECT VERSION 通过;未重验全部 CRUD、管理器与科学教程 |
升级 SQLAlchemy 也可解决本次基础查询的依赖错误;不要把旧组合的失败泛化为所有 SDK 或所有 PyMySQL 1.2.3 组合失败。
验证范围¶
2026-10-14:官方 MO v4.2.5 单节点,已验证同步/固定依赖异步取数、绑定参数的 Decimal/Unicode/字节/微秒时间、DML 提交/回滚与 CRUD。公开 mo-vector 0.1.13 的 L2 向量读写也重新测试。没有把存在的管理器、ANN 查询成功或 SDK 方法名称写成全部能力已认证。