matrixone-python-sdk 0.1.9__tar.gz → 0.1.10__tar.gz

{matrixone_python_sdk-0.1.9/matrixone_python_sdk.egg-info → matrixone_python_sdk-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrixone-python-sdk
-Version: 0.1.9
+Version: 0.1.10
 Summary: A comprehensive Python SDK for MatrixOne database operations with vector search, fulltext search, and advanced features
 Home-page: https://github.com/matrixorigin/matrixone
 Author: MatrixOne Team
@@ -171,6 +171,37 @@ conda activate matrixone
 pip install matrixone-python-sdk
 ```
 
+## ⚠️ Important: Column Naming Convention
+
+**🚨 CRITICAL: Always use lowercase with underscores (snake_case) for column names!**
+
+MatrixOne does not support SQL standard double-quoted identifiers in queries, which causes issues with camelCase column names when using SQLAlchemy ORM.
+
+```python
+# ❌ DON'T: CamelCase column names (will fail in SELECT queries)
+class User(Base):
+    userName = Column(String(50))      # CREATE succeeds, SELECT fails!
+    userId = Column(Integer)           # Will cause SQL syntax errors
+
+# ✅ DO: Use lowercase with underscores (snake_case)
+class User(Base):
+    user_name = Column(String(50))     # Works perfectly
+    user_id = Column(Integer)          # All operations succeed
+```
+
+**Why this matters:**
+- ✅ CREATE TABLE works with both styles (uses backticks)
+- ✅ INSERT works with both styles  
+- ❌ **SELECT fails with camelCase** (uses double quotes, not supported by MatrixOne)
+
+**Example of the problem:**
+```python
+# CamelCase generates: SELECT "userName" FROM user  ❌ Fails!
+# snake_case generates: SELECT user_name FROM user  ✅ Works!
+```
+
+---
+
 ## Quick Start
 
 ### Basic Usage

{matrixone_python_sdk-0.1.9 → matrixone_python_sdk-0.1.10}/README.md

@@ -70,6 +70,37 @@ A comprehensive Python SDK for MatrixOne that provides SQLAlchemy-like interface
   - Non-interactive mode for scripting and automation
   - Batch operations on tables and indexes
 
+## ⚠️ Important: Column Naming Convention
+
+**🚨 CRITICAL: Always use lowercase with underscores (snake_case) for column names!**
+
+MatrixOne does not support SQL standard double-quoted identifiers in queries, which causes issues with camelCase column names when using SQLAlchemy ORM.
+
+```python
+# ❌ DON'T: CamelCase column names (will fail in SELECT queries)
+class User(Base):
+    userName = Column(String(50))      # CREATE succeeds, SELECT fails!
+    userId = Column(Integer)           # Will cause SQL syntax errors
+
+# ✅ DO: Use lowercase with underscores (snake_case)
+class User(Base):
+    user_name = Column(String(50))     # Works perfectly
+    user_id = Column(Integer)          # All operations succeed
+```
+
+**Why this matters:**
+- ✅ CREATE TABLE works with both styles (uses backticks)
+- ✅ INSERT works with both styles  
+- ❌ **SELECT fails with camelCase** (uses double quotes, not supported by MatrixOne)
+
+**Example of the problem:**
+```python
+# CamelCase generates: SELECT "userName" FROM user  ❌ Fails!
+# snake_case generates: SELECT user_name FROM user  ✅ Works!
+```
+
+---
+
 ## 🚀 Installation
 
 ### From PyPI (Stable Release)

{matrixone_python_sdk-0.1.9 → matrixone_python_sdk-0.1.10}/README_USER.md

@@ -103,6 +103,37 @@ conda activate matrixone
 pip install matrixone-python-sdk
 ```
 
+## ⚠️ Important: Column Naming Convention
+
+**🚨 CRITICAL: Always use lowercase with underscores (snake_case) for column names!**
+
+MatrixOne does not support SQL standard double-quoted identifiers in queries, which causes issues with camelCase column names when using SQLAlchemy ORM.
+
+```python
+# ❌ DON'T: CamelCase column names (will fail in SELECT queries)
+class User(Base):
+    userName = Column(String(50))      # CREATE succeeds, SELECT fails!
+    userId = Column(Integer)           # Will cause SQL syntax errors
+
+# ✅ DO: Use lowercase with underscores (snake_case)
+class User(Base):
+    user_name = Column(String(50))     # Works perfectly
+    user_id = Column(Integer)          # All operations succeed
+```
+
+**Why this matters:**
+- ✅ CREATE TABLE works with both styles (uses backticks)
+- ✅ INSERT works with both styles  
+- ❌ **SELECT fails with camelCase** (uses double quotes, not supported by MatrixOne)
+
+**Example of the problem:**
+```python
+# CamelCase generates: SELECT "userName" FROM user  ❌ Fails!
+# snake_case generates: SELECT user_name FROM user  ✅ Works!
+```
+
+---
+
 ## Quick Start
 
 ### Basic Usage

{matrixone_python_sdk-0.1.9 → matrixone_python_sdk-0.1.10}/examples/example_24_query_update.py

@@ -36,6 +36,7 @@ from matrixone import Client
 from matrixone.orm import declarative_base
 from matrixone.config import get_connection_params
 from sqlalchemy import Column, Integer, String, DECIMAL, TIMESTAMP, func
+from sqlalchemy.dialects.mysql import JSON
 
 # Create MatrixOne logger
 logger = logging.getLogger(__name__)
@@ -59,6 +60,7 @@ class User(Base):
     login_count = Column(Integer, default=0)
     last_login = Column(TIMESTAMP)
     created_at = Column(TIMESTAMP, server_default=func.current_timestamp())
+    preferences = Column(JSON, nullable=True)  # JSON field for user preferences
 
 
 class Product(Base):
@@ -87,7 +89,8 @@ def demo_simple_updates():
         # Create tables
         client.create_all(Base)
 
-        # Insert sample data
+        # Insert sample data with JSON fields
+        # Note: Python dict in JSON column is automatically serialized
         users_data = [
             {
                 "id": 1,
@@ -98,6 +101,7 @@ def demo_simple_updates():
                 "salary": 50000.00,
                 "status": "active",
                 "login_count": 5,
+                "preferences": {"theme": "dark", "language": "en", "notifications": True},
             },
             {
                 "id": 2,
@@ -108,6 +112,7 @@ def demo_simple_updates():
                 "salary": 60000.00,
                 "status": "active",
                 "login_count": 10,
+                "preferences": {"theme": "light", "language": "zh", "notifications": False},
             },
             {
                 "id": 3,
@@ -118,18 +123,22 @@ def demo_simple_updates():
                 "salary": 70000.00,
                 "status": "inactive",
                 "login_count": 2,
+                "preferences": {"theme": "auto", "language": "en", "email_digest": "daily"},
             },
         ]
+        # Using batch_insert with JSON dict - auto-serialization
         client.batch_insert("example_users_update", users_data)
+        print("   ✓ Inserted users with JSON preferences using batch_insert()")
 
         # 1. Simple update with key-value pairs
-        print("1. Simple update with key-value pairs")
+        print("\n1. Simple update with key-value pairs")
         query = client.query(User)
         result = query.update(full_name="Alice Updated", email="alice.updated@example.com").filter(User.id == 1).execute()
 
         # Verify the update
         updated_user = client.query(User).filter(User.id == 1).first()
         print(f"   Updated user: {updated_user.full_name}, {updated_user.email}")
+        print(f"   User preferences (JSON): {updated_user.preferences}")
 
         # 2. Update multiple records with condition
         print("\n2. Update multiple records with condition")
@@ -165,7 +174,7 @@ def demo_sqlalchemy_expressions():
         # Create tables
         client.create_all(Base)
 
-        # Insert sample data
+        # Insert sample data with JSON - Using batch_insert
         users_data = [
             {
                 "id": 1,
@@ -176,7 +185,14 @@ def demo_sqlalchemy_expressions():
                 "salary": 50000.00,
                 "status": "active",
                 "login_count": 5,
+                "preferences": {"theme": "dark", "language": "en"},
             },
+        ]
+        client.batch_insert("example_users_update", users_data)
+
+        # Insert another user using client.insert() with JSON dict
+        client.insert(
+            "example_users_update",
             {
                 "id": 2,
                 "username": "bob",
@@ -186,12 +202,13 @@ def demo_sqlalchemy_expressions():
                 "salary": 60000.00,
                 "status": "active",
                 "login_count": 10,
+                "preferences": {"theme": "light", "language": "zh", "notifications": False},
             },
-        ]
-        client.batch_insert("example_users_update", users_data)
+        )
+        print("   ✓ Inserted users using batch_insert() and insert() with JSON dicts")
 
         # 1. Update with SQLAlchemy expressions
-        print("1. Update with SQLAlchemy expressions")
+        print("\n1. Update with SQLAlchemy expressions")
         query = client.query(User)
         result = query.update(login_count=User.login_count + 1, salary=User.salary * 1.1).filter(User.id == 1).execute()
 

{matrixone_python_sdk-0.1.9 → matrixone_python_sdk-0.1.10}/examples/example_26_stage_operations.py

@@ -225,7 +225,7 @@ class StageOperationsDemo:
             self.results['files_created'].append(csv_file)
 
             # Load data from stage using client.load_data
-            result = client.load_data.from_stage_csv('demo_file_stage', 'stage_users.csv', StageUser)
+            result = client.load_data.read_csv_stage('demo_file_stage', 'stage_users.csv', StageUser)
             self.logger.info(f"✅ Loaded {result.affected_rows} rows from stage")
 
             # Verify data
@@ -392,7 +392,7 @@ class StageOperationsDemo:
             # Load data from stage within session
             with client.session() as tx:
                 # Load data from pre-existing stage in session
-                result = tx.load_data.from_stage_csv('tx_temp_stage', 'tx_data.csv', TxStageData)
+                result = tx.load_data.read_csv_stage('tx_temp_stage', 'tx_data.csv', TxStageData)
                 # Check for both ResultSet and SQLAlchemy Result
                 affected = result.affected_rows if hasattr(result, 'affected_rows') else result.rowcount
                 self.logger.info(f"✅ Loaded {affected} rows in session")
@@ -706,7 +706,7 @@ class StageOperationsDemo:
 
             # Load customers
             print("Loading customers dimension...")
-            stage.load_csv('customers.csv', Customer, ignore_lines=1)
+            stage.load_csv('customers.csv', Customer, skiprows=1)
             count = client.query(Customer).count()
             print(f"✅ Loaded {count} customers")
 
@@ -718,13 +718,13 @@ class StageOperationsDemo:
 
             # Load orders
             print("Loading orders fact table...")
-            stage.load_csv('orders.csv', Order, ignore_lines=1)
+            stage.load_csv('orders.csv', Order, skiprows=1)
             count = client.query(Order).count()
             print(f"✅ Loaded {count} orders")
 
             # Load shipping (TSV)
             print("Loading shipping logistics...")
-            stage.load_tsv('shipping.tsv', Shipping, ignore_lines=1)
+            stage.load_tsv('shipping.tsv', Shipping, skiprows=1)
             count = client.query(Shipping).count()
             print(f"✅ Loaded {count} shipping records")
 
@@ -794,7 +794,7 @@ class StageOperationsDemo:
             self.results['files_created'].append(delta_file)
 
             print("📥 Loading incremental orders...")
-            stage.load_csv('orders_delta.csv', Order, ignore_lines=1)
+            stage.load_csv('orders_delta.csv', Order, skiprows=1)
             count = client.query(Order).count()
             print(f"✅ Total orders now: {count} (+2 new)")
 

{matrixone_python_sdk-0.1.9 → matrixone_python_sdk-0.1.10}/matrixone/base_client.py

@@ -67,15 +67,22 @@ class BaseMatrixOneClient:
 
             SQL INSERT statement string
         """
+        import json
+
         columns = list(data.keys())
         values = list(data.values())
 
-        # Convert vectors to string format
+        # Convert values to appropriate SQL format
         formatted_values = []
         for value in values:
             if value is None:
                 formatted_values.append("NULL")
+            elif isinstance(value, dict):
+                # JSON type: serialize dict to JSON string
+                json_str = json.dumps(value)
+                formatted_values.append(f"'{json_str}'")
             elif isinstance(value, list):
+                # Vector type: format as [1,2,3]
                 formatted_values.append("'" + "[" + ",".join(map(str, value)) + "]" + "'")
             else:
                 formatted_values.append(f"'{str(value)}'")
@@ -98,6 +105,8 @@ class BaseMatrixOneClient:
 
             SQL batch INSERT statement string
         """
+        import json
+
         if not data_list:
             return ""
 
@@ -113,7 +122,14 @@ class BaseMatrixOneClient:
                 value = data[col]
                 if value is None:
                     formatted_values.append("NULL")
+                elif isinstance(value, dict):
+                    # JSON type: serialize dict to JSON string
+                    json_str = json.dumps(value)
+                    # Escape single quotes in JSON string to prevent SQL injection
+                    escaped_json = json_str.replace("'", "''")
+                    formatted_values.append(f"'{escaped_json}'")
                 elif isinstance(value, list):
+                    # Vector type: format as [1,2,3]
                     formatted_values.append("'" + "[" + ",".join(map(str, value)) + "]" + "'")
                 else:
                     # Escape single quotes in string values to prevent SQL injection

{matrixone_python_sdk-0.1.9 → matrixone_python_sdk-0.1.10}/matrixone/sqlalchemy_ext/__init__.py

@@ -99,6 +99,35 @@ from .vector_type import (
     within_distance,
 )
 
+# Import JSON functions
+from .json_functions import (
+    JSON_EXTRACT,
+    JSON_EXTRACT_FLOAT64,
+    JSON_EXTRACT_STRING,
+    JSON_INSERT,
+    JSON_QUOTE,
+    JSON_REPLACE,
+    JSON_ROW,
+    JSON_SET,
+    JSON_UNQUOTE,
+    json_extract,
+    json_extract_float64,
+    json_extract_string,
+    json_insert,
+    json_quote,
+    json_replace,
+    json_row,
+    json_set,
+    json_unquote,
+)
+
+# Import custom JSON type
+from .json_type import (
+    JSON,
+    JSONPathElement,
+    MATRIXONE_JSON,
+)
+
 __all__ = [
     "VectorType",
     "Vectorf32",
@@ -159,4 +188,27 @@ __all__ = [
     "boolean_match",
     "natural_match",
     "group",
+    # JSON functions
+    "json_extract",
+    "json_extract_string",
+    "json_extract_float64",
+    "json_set",
+    "json_insert",
+    "json_replace",
+    "json_quote",
+    "json_unquote",
+    "json_row",
+    "JSON_EXTRACT",
+    "JSON_EXTRACT_STRING",
+    "JSON_EXTRACT_FLOAT64",
+    "JSON_SET",
+    "JSON_INSERT",
+    "JSON_REPLACE",
+    "JSON_QUOTE",
+    "JSON_UNQUOTE",
+    "JSON_ROW",
+    # JSON type
+    "JSON",
+    "JSONPathElement",
+    "MATRIXONE_JSON",
 ]

matrixone_python_sdk-0.1.10/matrixone/sqlalchemy_ext/json_functions.py

@@ -0,0 +1,296 @@
+"""
+JSON functions for MatrixOne SQLAlchemy integration.
+
+This module provides JSON manipulation functions compatible with MatrixOne's
+JSON support. These functions handle path literals correctly to avoid parameter
+binding issues.
+"""
+
+from sqlalchemy import literal_column
+from sqlalchemy.sql.expression import ColumnElement
+from sqlalchemy.sql import functions
+
+
+class json_extract(functions.GenericFunction):
+    """
+    Extract values from JSON documents using JSON path expressions.
+
+    This function wraps MatrixOne's JSON_EXTRACT function and ensures
+    that path arguments are treated as literals rather than bound parameters.
+
+    Args:
+        json_column: The JSON column or expression
+        *paths: One or more JSON path expressions (e.g., '$.name', '$.age')
+
+    Returns:
+        SQLAlchemy function expression
+
+    Examples:
+        >>> from matrixone.sqlalchemy_ext.json_functions import json_extract
+        >>> from sqlalchemy import select
+        >>>
+        >>> # Extract single path
+        >>> stmt = select(json_extract(Product.specs, '$.brand'))
+        >>>
+        >>> # Extract multiple paths
+        >>> stmt = select(json_extract(Product.specs, '$.brand', '$.model'))
+        >>>
+        >>> # Use in WHERE clause
+        >>> stmt = select(Product).where(
+        ...     json_extract(Product.specs, '$.category') == 'Electronics'
+        ... )
+    """
+
+    type = None
+    name = 'json_extract'
+    inherit_cache = True
+
+    def __init__(self, json_column: ColumnElement, *paths: str, **kwargs):
+        # Convert paths to literal columns to avoid parameter binding
+        literal_paths = [literal_column(f"'{path}'") for path in paths]
+        super().__init__(json_column, *literal_paths, **kwargs)
+
+
+class json_extract_string(functions.GenericFunction):
+    """
+    Extract JSON value as string type.
+
+    Args:
+        json_column: The JSON column or expression
+        path: JSON path expression
+
+    Returns:
+        SQLAlchemy function expression returning string
+
+    Example:
+        >>> stmt = select(json_extract_string(Product.specs, '$.name'))
+    """
+
+    type = None
+    name = 'json_extract_string'
+    inherit_cache = True
+
+    def __init__(self, json_column: ColumnElement, path: str, **kwargs):
+        literal_path = literal_column(f"'{path}'")
+        super().__init__(json_column, literal_path, **kwargs)
+
+
+class json_extract_float64(functions.GenericFunction):
+    """
+    Extract JSON numeric value as float.
+
+    Args:
+        json_column: The JSON column or expression
+        path: JSON path expression
+
+    Returns:
+        SQLAlchemy function expression returning float
+
+    Example:
+        >>> stmt = select(json_extract_float64(Product.specs, '$.price'))
+    """
+
+    type = None
+    name = 'json_extract_float64'
+    inherit_cache = True
+
+    def __init__(self, json_column: ColumnElement, path: str, **kwargs):
+        literal_path = literal_column(f"'{path}'")
+        super().__init__(json_column, literal_path, **kwargs)
+
+
+class json_set(functions.GenericFunction):
+    """
+    Insert or update JSON values (upsert behavior).
+
+    Args:
+        json_column: The JSON column or expression
+        *path_value_pairs: Alternating path and value arguments
+
+    Returns:
+        SQLAlchemy function expression
+
+    Example:
+        >>> from sqlalchemy import update
+        >>>
+        >>> # Update single key
+        >>> stmt = update(Product).values(
+        ...     specs=json_set(Product.specs, '$.ram', 32)
+        ... )
+        >>>
+        >>> # Update multiple keys
+        >>> stmt = update(Product).values(
+        ...     specs=json_set(Product.specs, '$.ram', 32, '$.storage', '1TB')
+        ... )
+    """
+
+    type = None
+    name = 'json_set'
+    inherit_cache = True
+
+    def __init__(self, json_column: ColumnElement, *path_value_pairs, **kwargs):
+        # Process path-value pairs
+        # Paths should be literals, values can be bound parameters
+        processed_args = []
+        for i, arg in enumerate(path_value_pairs):
+            if i % 2 == 0:  # Path (even index)
+                processed_args.append(literal_column(f"'{arg}'"))
+            else:  # Value (odd index)
+                processed_args.append(arg)
+
+        super().__init__(json_column, *processed_args, **kwargs)
+
+
+class json_insert(functions.GenericFunction):
+    """
+    Insert JSON values only if path doesn't exist.
+
+    Args:
+        json_column: The JSON column or expression
+        *path_value_pairs: Alternating path and value arguments
+
+    Returns:
+        SQLAlchemy function expression
+
+    Example:
+        >>> stmt = update(Product).values(
+        ...     specs=json_insert(Product.specs, '$.warranty', '2 years')
+        ... )
+    """
+
+    type = None
+    name = 'json_insert'
+    inherit_cache = True
+
+    def __init__(self, json_column: ColumnElement, *path_value_pairs, **kwargs):
+        processed_args = []
+        for i, arg in enumerate(path_value_pairs):
+            if i % 2 == 0:  # Path
+                processed_args.append(literal_column(f"'{arg}'"))
+            else:  # Value
+                processed_args.append(arg)
+
+        super().__init__(json_column, *processed_args, **kwargs)
+
+
+class json_replace(functions.GenericFunction):
+    """
+    Update JSON values only if path exists.
+
+    Args:
+        json_column: The JSON column or expression
+        *path_value_pairs: Alternating path and value arguments
+
+    Returns:
+        SQLAlchemy function expression
+
+    Example:
+        >>> stmt = update(Product).values(
+        ...     specs=json_replace(Product.specs, '$.price', 999.99)
+        ... )
+    """
+
+    type = None
+    name = 'json_replace'
+    inherit_cache = True
+
+    def __init__(self, json_column: ColumnElement, *path_value_pairs, **kwargs):
+        processed_args = []
+        for i, arg in enumerate(path_value_pairs):
+            if i % 2 == 0:  # Path
+                processed_args.append(literal_column(f"'{arg}'"))
+            else:  # Value
+                processed_args.append(arg)
+
+        super().__init__(json_column, *processed_args, **kwargs)
+
+
+class json_quote(functions.GenericFunction):
+    """
+    Convert string to JSON string (add quotes and escape).
+
+    Args:
+        string_value: String to quote
+
+    Returns:
+        SQLAlchemy function expression
+
+    Example:
+        >>> stmt = select(json_quote('Hello "World"'))
+    """
+
+    type = None
+    name = 'json_quote'
+    inherit_cache = True
+
+
+class json_unquote(functions.GenericFunction):
+    """
+    Remove JSON string quotes and unescape.
+
+    Args:
+        json_string: JSON string to unquote
+
+    Returns:
+        SQLAlchemy function expression
+
+    Example:
+        >>> stmt = select(json_unquote('"Hello"'))
+    """
+
+    type = None
+    name = 'json_unquote'
+    inherit_cache = True
+
+
+class json_row(functions.GenericFunction):
+    """
+    Construct JSON object from key-value pairs.
+
+    Args:
+        *key_value_pairs: Alternating key and value arguments
+
+    Returns:
+        SQLAlchemy function expression
+
+    Example:
+        >>> stmt = select(json_row('name', 'John', 'age', 30))
+    """
+
+    type = None
+    name = 'json_row'
+    inherit_cache = True
+
+
+# Convenience aliases (lowercase versions)
+JSON_EXTRACT = json_extract
+JSON_EXTRACT_STRING = json_extract_string
+JSON_EXTRACT_FLOAT64 = json_extract_float64
+JSON_SET = json_set
+JSON_INSERT = json_insert
+JSON_REPLACE = json_replace
+JSON_QUOTE = json_quote
+JSON_UNQUOTE = json_unquote
+JSON_ROW = json_row
+
+
+__all__ = [
+    'json_extract',
+    'json_extract_string',
+    'json_extract_float64',
+    'json_set',
+    'json_insert',
+    'json_replace',
+    'json_quote',
+    'json_unquote',
+    'json_row',
+    'JSON_EXTRACT',
+    'JSON_EXTRACT_STRING',
+    'JSON_EXTRACT_FLOAT64',
+    'JSON_SET',
+    'JSON_INSERT',
+    'JSON_REPLACE',
+    'JSON_QUOTE',
+    'JSON_UNQUOTE',
+    'JSON_ROW',
+]