MatrixOne 通用 Python SDK

matrixone-python-sdk 的导入入口是 from matrixone import Client, AsyncClient,提供关系型 SQL、事务、ORM 和 MatrixOne 功能管理接口。它与独立的 mo-vector / mo_vector 包不同;向量包装器不能替代通用 SDK,也不能由方法名称推断全文或混合检索已经实现。

选用哪个 Python 接口

接口

使用方式

适用场景

PyMySQL

import pymysql

MySQL 协议、游标与驱动层控制,见Python 连接

SQLAlchemy

Engine、Core、ORM

通用 SQL 和事务;使用 SDK 的 Engine 时保留其连接生命周期

通用 SDK

matrixone-python-sdk → matrixone

Client/AsyncClient、Session、MatrixOne 特有功能管理

独立向量包

mo-vector → mo_vector

另一套向量 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

配置、钩子;核对 pool_size/max_overflow、TLS 与角色

同步/异步 SQL

Client、AsyncClient

客户端 API、异步 API;固定依赖并实际执行

事务与结果

client.session、Session、ResultSet

事务、结果;回滚、返回对象、取数内存

ORM 与查询构造

client.query、SQLAlchemy 表达式

ORM;类型、命名、实际生成 SQL

向量/索引

vector_ops、Vectorf32/Vectorf64

向量;距离含义、维度、索引存在和执行计划

全文与 JSON

fulltext_index、boolean_match、JSON 运算

全文、JSON;SQL 语义与版本

元数据与索引检查

metadata、索引验证方法

元数据、索引验证

文件加载、导出、Stage

load_data、export、stage

加载、导出、Stage;文件属于客户端还是服务端

快照、恢复、PITR

snapshots、restore、pitr

快照/恢复;权限、保留期、恢复后的新写入处理

Clone、Branch

clone、branch

Clone、Branch;隔离、冲突、写入后资源占用

租户、用户、权限、发布订阅

account、pubsub

账号、发布订阅

CDC 管理

client.cdc、CDCManager

实现;MO 源端任务控制,不等于 MySQL 源入站 CDC;独立 API/流程文档仍需补齐

诊断、运维与版本

mo-diag、moctl、version

诊断、moctl、版本

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 方法名称写成全部能力已认证。