MatrixOne general Python SDK¶
The matrixone-python-sdk distribution exposes from matrixone import Client, AsyncClient. It provides relational SQL, sessions, ORM integration and MatrixOne feature managers. It is distinct from the separate mo-vector / mo_vector package. A vector wrapper is not a replacement for the general SDK, and a method name does not establish implemented fulltext or hybrid search.
Choose a Python interface¶
Interface |
Entry point |
Use |
|---|---|---|
PyMySQL |
|
MySQL protocol and driver/cursor control; see Python connection |
SQLAlchemy |
Engine, Core, ORM |
General SQL and transactions; preserve ownership of an SDK-provided Engine |
General SDK |
|
Client/AsyncClient, Session and MatrixOne feature managers |
Separate vector package |
|
A different vector API; see vector SDK example |
Python UDF |
Server-side Python invocation |
A different execution location from the SDK or Notebook; see Python UDF |
Versions and installation¶
This page and the basic lab check PyPI matrixone-python-sdk==0.1.16, MO v4.2.5 and Python 3.12.14. Package metadata declares Python>=3.8; the complete Python/dependency matrix has not been certified. Use importlib.metadata.version('matrixone-python-sdk'): the tested distribution has matrixone.__version__ == '1.0.0' but distribution metadata is 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'))"
Record package name, SDK distribution, server and dependencies separately. SDK 0.1.16 distribution metadata classifies it as Beta; assess SDK release status separately from server stability. Development sources are under clients/python, not the old clients/python-wrapper path. All 48 SDK Python files in the v4.2.5 source match the installed 0.1.16 wheel. External ReadTheDocs latest can change.
Capability and documentation map¶
These are public APIs and documentation entry points, not certification of every permission, combination or production behavior. The SDK already has 25 top-level RST files and 28 API RST files; the database manual needs a clear entry point and Chinese coverage beyond vectors.
Capability |
SDK entry |
Pinned reference and acceptance focus |
|---|---|---|
Connections, pooling, tenant/role login, hooks |
Client.connect, from_engine, on_connect |
Configuration, hooks; pool_size/max_overflow, TLS and roles |
Sync/async SQL |
Client, AsyncClient |
Client API, async API; execute with pinned dependencies |
Transactions and results |
client.session, Session, ResultSet |
|
ORM/query construction |
client.query, SQLAlchemy expressions |
ORM; types, identifiers and generated SQL |
Vectors/indexes |
vector_ops, Vectorf32/Vectorf64 |
Vectors; distances, dimensions, actual indexes/plans |
Fulltext and JSON |
fulltext_index, boolean_match, JSON operations |
|
Metadata/index inspection |
metadata, index verification methods |
|
Loading, exporting and Stage |
load_data, export, stage |
|
Snapshot, restore and PITR |
snapshots, restore, pitr |
Snapshots/restore; privileges, retention and later writes |
Clone and Branch |
clone, branch |
Clone, Branch; isolation, conflicts and storage after writes |
Tenants, accounts, privileges and pub/sub |
account, pubsub |
|
CDC management |
client.cdc, CDCManager |
Implementation; MO-source task control is not inbound MySQL CDC; dedicated API/workflow docs remain needed |
Diagnostics, operations and versions |
mo-diag, moctl, version |
|
pandas/NumPy/ML |
Fetch SQL results into Python libraries |
No built-in DataFrame or model-training execution engine; see tutorials; Python computation is not automatically pushed down |
The English manual also has vector, fulltext, hybrid and Clone examples. Chinese parity and version acceptance remain incomplete. A feature guide does not replace execution checks.
Important contracts¶
connect()takes keyword arguments and an existing database with appropriate privileges. The relational examples useon_connect=[]to avoid unrelated feature hooks.Client.execute()returns a buffered ResultSet.client.session().execute()returns SQLAlchemy Result.scalar(),rows/columnsandrowcount/affected_rowsdiffer between these objects.Put DML needing one commit inside one
client.session()and let failures escape the context. Do not claim DDL, snapshots or account operations all participate in the same rollback boundary.Raw-string
?substitution is distinct from driver binding: a literal question mark was incorrectly substituted in the tested query. Examples usesession.execute(text(sql), params)for binding. Values and identifiers require different handling; value parameters cannot bind table/column names.fetchmany()slices already buffered data. Reduce results with WHERE/aggregation or stable unique-key pages. Changing data also needs an explicit consistency boundary.pandas-style load_data.read_csv/read_parquet load into SQL tables rather than returning DataFrames. export.to_csv files may belong to the server or a Stage rather than the Notebook machine; verify INFILE/LOCAL/INLINE/Stage direction and privileges.
SDK 0.1.16 / SQLAlchemy 2.0.43 / aiomysql 0.3.2 / PyMySQL 1.2.3 failed with
ping() missing ... reconnect. The same async query passed with PyMySQL 1.1.1. Unbounded dependency upgrades are not a verified async installation. See dependency issue #30242.For synchronous TLS use
ssl_mode='required'and a CA with server identity verification. Local tests do not certify remote TLS, failover or production pool capacity. Disabling ordinary SQL logs does not guarantee errors contain no data.
Tested dependency combinations¶
All rows use SDK 0.1.16, Python 3.12.14 and MO v4.2.5. Their acceptance scopes differ:
SQLAlchemy |
PyMySQL |
aiomysql |
Result |
|---|---|---|---|
2.0.43 |
1.1.1 |
0.3.2 |
Sync CRUD/transactions, complete scientific labs and async reads pass; pinned tutorial tuple |
2.0.43 |
1.2.3 |
0.3.2 |
Async pre-ping fails on the reconnect argument |
2.1.4 |
1.2.3 |
0.3.2 |
Sync/async SELECT VERSION pass; complete CRUD/managers/scientific labs not requalified |
Upgrading SQLAlchemy also resolves this basic-query interoperability failure. Do not generalize the old tuple failure to every SDK or every PyMySQL 1.2.3 combination.
Verification scope¶
2026-10-14, official MO v4.2.5, single node: synchronous and pinned-dependency async reads, bound Decimal/Unicode/bytes/microseconds, DML commit/rollback and CRUD pass. Public mo-vector 0.1.13 L2 reads/writes were also retested. Managers, successful ANN queries and method names do not certify all capabilities.