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

import 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

matrixone-python-sdk → matrixone

Client/AsyncClient, Session and MatrixOne feature managers

Separate vector package

mo-vector → mo_vector

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

Sessions, results; rollback, return types and memory

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

Fulltext, JSON; SQL/version semantics

Metadata/index inspection

metadata, index verification methods

Metadata, verification

Loading, exporting and Stage

load_data, export, stage

Loading, export, Stage; client/server file ownership

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

Accounts, pub/sub

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

Diagnostics, moctl, versions

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 use on_connect=[] to avoid unrelated feature hooks.

  • Client.execute() returns a buffered ResultSet. client.session().execute() returns SQLAlchemy Result. scalar(), rows/columns and rowcount/affected_rows differ 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 use session.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.