SDK Python MatrixOne : recherche vectorielle, instantanés et shell de diagnostic
Base de données HTAP native pour l'IA avec Git-for-Data et recherche vectorielle intégrée, servant de base de données et de mémoire pour les agents et applications intelligents.
En bref
- De quoi s’agit-il ?
- Le README du répertoire clients/python décrit un SDK Python pour MatrixOne qui enveloppe les opérations de base de données dans une API de type SQLAlchemy, ajoute un chargement de données façon pandas et fournit un outil mo-diag pour l'inspection des index et des tables.
- À qui s’adresse-t-il ?
- La documentation du SDK couvre une large surface : recherche vectorielle et plein texte, instantanés, PITR, clonage, branches, stages, métadonnées, gestion des comptes et pub/sub. Elle impose également une exigence spécifique concernant le nommage des colonnes et fournit un outil de diagnostic pour surveiller la santé des index.
- Puis-je l’utiliser commercialement ?
- Oui. Apache-2.0 est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 1 jour.
- En quel langage est-il écrit ?
- Principalement Go, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 14 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Le SDK Python à l'intérieur de MatrixOne
Ce README se trouve dans le répertoire clients/python du dépôt matrixorigin/matrixone. Il documente un SDK Python qui expose une interface de type SQLAlchemy à MatrixOne, couvrant les opérations de base de données, la recherche vectorielle, la recherche en plein texte, la gestion des instantanés, la récupération à un instant précis, le clonage de tables et l'intégration avec l'outil mo-ctl. Le README note que le SDK a été généré et optimisé grâce au développement assisté par IA, ce qui est une affirmation sur sa provenance, pas une qualité mesurée. La liste des fonctionnalités du SDK comprend le pooling de connexions, la prise en charge asynchrone et les indications de type, mais le README ne fournit pas de benchmarks ni de validation indépendante des performances.
Installation et configuration de développement
La version stable s'installe depuis PyPI avec pip install matrixone-python-sdk. Un canal de pré-version sur test.pypi est également documenté, avec la note que --extra-index-url est nécessaire pour récupérer les dépendances telles que PyMySQL et SQLAlchemy depuis l'index officiel. Pour le développement, le README recommande de cloner le dépôt et d'utiliser soit un environnement virtuel, soit conda, puis d'exécuter make dev-setup ou pip install -e '.[dev]'. Les dépendances de test sont séparées : pip install -e '.[test]' pour la suite de tests, et pyarrow>=10.0.0 est requis pour le support Parquet dans les opérations de chargement. Le README liste également des fichiers d'exigences spécifiques pour SQLAlchemy 1.4 et 2.0.
Client, sessions et déplacement de données
La classe Client se connecte avec des arguments nommés, exigeant un nom de base de données ; host, port, user et password ont des valeurs par défaut. Un gestionnaire de contexte session() fournit des transactions atomiques qui valident ou annulent ensemble. Les méthodes de chargement de données imitent pandas : read_csv, read_json et read_parquet acceptent des paramètres comme sep, quotechar, skiprows et encoding, et peuvent lire à partir de fichiers locaux, de chaînes en ligne ou de chemins stage://. L'exportation utilise to_csv et to_jsonl, également avec des options de style pandas. Un AsyncClient prend en charge async/await, et le SDK peut envelopper une session SQLAlchemy existante pour ajouter des opérations spécifiques à MatrixOne sans réécriture complète.
Recherche vectorielle et plein texte
La recherche vectorielle prend en charge les algorithmes d'index HNSW et IVF, avec une précision vectorielle f32 et f64 et des métriques de distance L2, cosinus et produit scalaire. Le README met en avant get_ivf_stats() comme outil de surveillance critique en production, montrant la distribution des centroïdes et le ratio d'équilibre, et mentionne IVF LIMIT BY RANK pour contrôler les modes de classement. La recherche plein texte utilise BM25 et TF-IDF, avec des modes naturel et booléen, des index multi-colonnes et un score de pertinence. La documentation donne des exemples de boolean_match avec les opérateurs must, should et must_not. Elle ne publie pas de chiffres de rappel ou de latence.
Instantanés, récupération, branches, stages et métadonnées
Le SDK expose la création d'instantanés à plusieurs niveaux, la récupération à un instant précis, le clonage de tables et de bases de données, et la gestion de branches que le README décrit comme un contrôle de version de type Git pour les bases de données. Les branches peuvent être créées, comparées et fusionnées avec des options de résolution de conflits. La gestion des stages couvre le système de fichiers local, S3 et d'autres stockages cloud, avec un support transactionnel pour les chargements atomiques de plusieurs fichiers. L'analyse des métadonnées renvoie des statistiques sur les tables et les colonnes, notamment les nombres de lignes, les nombres de nulls et les tailles compressées. La vérification des index secondaires contrôle la cohérence des nombres de lignes entre une table et ses index. La détection de version analyse les versions backend telles que 8.0.30-MatrixOne-v3.0.0 et fournit des contrôles de compatibilité. La gestion des comptes et pub/sub complètent la liste des fonctionnalités.
L'outil de diagnostic mo-diag
mo-diag est un outil en ligne de commande installé avec le SDK. Il offre un shell interactif avec complétion par tabulation, historique des commandes et sortie colorée, ainsi qu'un mode non interactif pour les scripts. Les commandes couvrent l'inspection des index : show_indexes affiche les tables physiques pour les index IVF, HNSW et plein texte ; show_ivf_status rapporte le nombre de centroïdes et l'équilibre ; verify_counts vérifie la cohérence des lignes ; et flush_table vide les tables principales et d'index. Les statistiques de table peuvent être affichées avec des détails au niveau des objets. Le README inclut des exemples pour les contrôles de santé quotidiens, le débogage des incohérences de comptage et l'analyse de stockage. Il documente également les raccourcis de tâches CDC via mo-diag cdc.
Nommage des colonnes et intégration SQLAlchemy
Le README contient un avertissement ferme : les noms de colonnes doivent être en minuscules avec des underscores. MatrixOne ne prend pas en charge les identifiants entre guillemets doubles du standard SQL, donc les noms en camelCase provoquent des échecs de SELECT même si CREATE TABLE et INSERT réussissent. Le modèle documenté est de toujours utiliser snake_case dans les modèles ORM. Le SDK fournit également des constructeurs de déclarations de style SQLAlchemy pour le clonage et les branches, et peut envelopper une session SQLAlchemy existante, ce qui vise à aider le code hérité à adopter progressivement les fonctionnalités de MatrixOne.
Les verifications propres au SDK MatrixOne
Un essai utile combine `Client`, `session()` et une table dont les colonnes restent en `snake_case`. Chargez un CSV avec `read_csv`, creez un index IVF ou HNSW, puis utilisez `mo-diag show_ivf_status` et `verify_counts` pour comparer les statistiques et les comptages. La documentation ne publie ni rappel de recherche ni latence : ces valeurs doivent etre mesurees sur votre version de MatrixOne et vos donnees.
Conclusion éditoriale
La documentation du SDK couvre une large surface : recherche vectorielle et plein texte, instantanés, PITR, clonage, branches, stages, métadonnées, gestion des comptes et pub/sub. Elle impose également une exigence spécifique concernant le nommage des colonnes et fournit un outil de diagnostic pour surveiller la santé des index. Aucun chiffre de référence ou garantie de production n'apparaît dans le README ; ces affirmations devraient provenir d'ailleurs.
Notes de la communauté