chdb 3.6.0__cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl → 3.7.0__cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

chdb/__init__.py

@@ -4,7 +4,38 @@ import threading
 
 
 class ChdbError(Exception):
-    """Base class for exceptions in this module."""
+    """Base exception class for chDB-related errors.
+
+    This exception is raised when chDB query execution fails or encounters
+    an error. It inherits from the standard Python Exception class and
+    provides error information from the underlying ClickHouse engine.
+
+    The exception message typically contains detailed error information
+    from ClickHouse, including syntax errors, type mismatches, missing
+    tables/columns, and other query execution issues.
+
+    Attributes:
+        args: Tuple containing the error message and any additional arguments
+
+    Examples:
+        >>> try:
+        ...     result = chdb.query("SELECT * FROM non_existent_table")
+        ... except chdb.ChdbError as e:
+        ...     print(f"Query failed: {e}")
+        Query failed: Table 'non_existent_table' doesn't exist
+
+        >>> try:
+        ...     result = chdb.query("SELECT invalid_syntax FROM")
+        ... except chdb.ChdbError as e:
+        ...     print(f"Syntax error: {e}")
+        Syntax error: Syntax error near 'FROM'
+
+    Note:
+        This exception is automatically raised by chdb.query() and related
+        functions when the underlying ClickHouse engine reports an error.
+        You should catch this exception when handling potentially failing
+        queries to provide appropriate error handling in your application.
+    """
 
 
 _arrow_format = set({"dataframe", "arrowtable"})
@@ -19,7 +50,7 @@ _process_result_format_funs = {
 # UDF script path will be f"{g_udf_path}/{func_name}.py"
 g_udf_path = ""
 
-chdb_version = ('3', '6', '0')
+__version__ = "3.7.0"
 if sys.version_info[:2] >= (3, 7):
     # get the path of the current file
     current_path = os.path.dirname(os.path.abspath(__file__))
@@ -36,17 +67,32 @@ if sys.version_info[:2] >= (3, 7):
 else:
     raise NotImplementedError("Python 3.6 or lower version is not supported")
 
-try:
-    # Change here if project is renamed and does not equal the package name
-    dist_name = __name__
-    __version__ = ".".join(map(str, chdb_version))
-except:  # noqa
-    __version__ = "unknown"
+chdb_version = tuple(__version__.split('.'))
 
 
 # return pyarrow table
 def to_arrowTable(res):
-    """convert res to arrow table"""
+    """Convert query result to PyArrow Table.
+
+    Converts a chDB query result to a PyArrow Table for efficient columnar data processing.
+    Returns an empty table if the result is empty.
+
+    Args:
+        res: chDB query result object containing binary Arrow data
+
+    Returns:
+        pa.Table: PyArrow Table containing the query results
+
+    Raises:
+        ImportError: If pyarrow or pandas are not installed
+
+    Example:
+        >>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
+        >>> table = chdb.to_arrowTable(result)
+        >>> print(table.to_pandas())
+           id    msg
+        0   1  hello
+    """
     # try import pyarrow and pandas, if failed, raise ImportError with suggestion
     try:
         import pyarrow as pa  # noqa
@@ -57,12 +103,34 @@ def to_arrowTable(res):
         raise ImportError("Failed to import pyarrow or pandas") from None
     if len(res) == 0:
         return pa.Table.from_batches([], schema=pa.schema([]))
-    return pa.RecordBatchFileReader(res.bytes()).read_all()
+
+    memview = res.get_memview()
+    return pa.RecordBatchFileReader(memview.view()).read_all()
 
 
 # return pandas dataframe
 def to_df(r):
-    """convert arrow table to Dataframe"""
+    """Convert query result to pandas DataFrame.
+
+    Converts a chDB query result to a pandas DataFrame by first converting to
+    PyArrow Table and then to pandas using multi-threading for better performance.
+
+    Args:
+        r: chDB query result object containing binary Arrow data
+
+    Returns:
+        pd.DataFrame: pandas DataFrame containing the query results
+
+    Raises:
+        ImportError: If pyarrow or pandas are not installed
+
+    Example:
+        >>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
+        >>> df = chdb.to_df(result)
+        >>> print(df)
+           id    msg
+        0   1  hello
+    """
     t = to_arrowTable(r)
     return t.to_pandas(use_threads=True)
 
@@ -73,6 +141,59 @@ g_conn_lock = threading.Lock()
 
 # wrap _chdb functions
 def query(sql, output_format="CSV", path="", udf_path=""):
+    """Execute SQL query using chDB engine.
+
+    This is the main query function that executes SQL statements using the embedded
+    ClickHouse engine. Supports various output formats and can work with in-memory
+    or file-based databases.
+
+    Args:
+        sql (str): SQL query string to execute
+        output_format (str, optional): Output format for results. Defaults to "CSV".
+            Supported formats include:
+
+            - "CSV" - Comma-separated values
+            - "JSON" - JSON format
+            - "Arrow" - Apache Arrow format
+            - "Parquet" - Parquet format
+            - "DataFrame" - Pandas DataFrame
+            - "ArrowTable" - PyArrow Table
+            - "Debug" - Enable verbose logging
+
+        path (str, optional): Database file path. Defaults to "" (in-memory database).
+            Can be a file path or ":memory:" for in-memory database.
+        udf_path (str, optional): Path to User-Defined Functions directory. Defaults to "".
+
+    Returns:
+        Query result in the specified format:
+
+        - str: For text formats like CSV, JSON
+        - pd.DataFrame: When output_format is "DataFrame" or "dataframe"
+        - pa.Table: When output_format is "ArrowTable" or "arrowtable"
+        - chdb result object: For other formats
+
+    Raises:
+        ChdbError: If the SQL query execution fails
+        ImportError: If required dependencies are missing for DataFrame/Arrow formats
+
+    Examples:
+        >>> # Basic CSV query
+        >>> result = chdb.query("SELECT 1, 'hello'")
+        >>> print(result)
+        "1,hello"
+
+        >>> # Query with DataFrame output
+        >>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
+        >>> print(df)
+           id    msg
+        0   1  hello
+
+        >>> # Query with file-based database
+        >>> result = chdb.query("CREATE TABLE test (id INT)", path="mydb.chdb")
+
+        >>> # Query with UDF
+        >>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")
+    """
     global g_udf_path
     if udf_path != "":
         g_udf_path = udf_path

chdb/dataframe/__init__.py

@@ -8,8 +8,13 @@ except ImportError as e:
     raise ImportError('Failed to import pyarrow or pandas') from None
 
 # check if pandas version >= 2.0.0
-if pd.__version__[0] < '2':
-    print('Please upgrade pandas to version 2.0.0 or higher to have better performance')
+try:
+    version_parts = pd.__version__.split('.')
+    major_version = int(version_parts[0])
+    if major_version < 2:
+        print('Please upgrade pandas to version 2.0.0 or higher to have better performance')
+except (ValueError, IndexError, AttributeError):
+    pass
 
 from .query import Table, pandas_read_parquet  # noqa: C0413
 

chdb/dataframe/query.py

@@ -8,11 +8,38 @@ from chdb import query as chdb_query
 
 
 class Table:
-    """
-    Table is a wrapper of multiple formats of data buffer, including parquet file path,
-    parquet bytes, and pandas dataframe.
-    if use_memfd is True, will try using memfd_create to create a temp file in memory, which is
-    only available on Linux. If failed, will fallback to use tempfile.mkstemp to create a temp file
+    """Wrapper for multiple data formats enabling SQL queries on DataFrames, Parquet files, and Arrow tables.
+
+    The Table class provides a unified interface for querying different data formats using SQL.
+    It supports pandas DataFrames, Parquet files (both on disk and in memory), and PyArrow Tables.
+    All data is internally converted to Parquet format for efficient querying with chDB.
+
+    Args:
+        parquet_path (str, optional): Path to an existing Parquet file
+        temp_parquet_path (str, optional): Path to a temporary Parquet file
+        parquet_memoryview (memoryview, optional): Parquet data in memory as memoryview
+        dataframe (pd.DataFrame, optional): pandas DataFrame to wrap
+        arrow_table (pa.Table, optional): PyArrow Table to wrap
+        use_memfd (bool, optional): Use memfd_create for temporary files (Linux only). Defaults to False.
+
+    Examples:
+        >>> # Create from pandas DataFrame
+        >>> import pandas as pd
+        >>> df = pd.DataFrame({'id': [1, 2], 'name': ['Alice', 'Bob']})
+        >>> table = Table(dataframe=df)
+        >>> result = table.query("SELECT * FROM __table__ WHERE id > 1")
+
+        >>> # Create from Parquet file
+        >>> table = Table(parquet_path="data.parquet")
+        >>> result = table.query("SELECT COUNT(*) FROM __table__")
+
+        >>> # Multi-table queries
+        >>> table1 = Table(dataframe=df1)
+        >>> table2 = Table(dataframe=df2)
+        >>> result = Table.queryStatic(
+        ...     "SELECT * FROM __table1__ JOIN __table2__ ON __table1__.id = __table2__.id",
+        ...     table1=table1, table2=table2
+        ... )
     """
 
     def __init__(
@@ -24,9 +51,18 @@ class Table:
         arrow_table: pa.Table = None,
         use_memfd: bool = False,
     ):
-        """
-        Initialize a Table object with one of parquet file path, parquet bytes, pandas dataframe or
-        parquet table.
+        """Initialize a Table object with one of the supported data formats.
+
+        Only one data source should be provided. The Table will wrap the provided data
+        and enable SQL querying capabilities.
+
+        Args:
+            parquet_path (str, optional): Path to existing Parquet file
+            temp_parquet_path (str, optional): Path to temporary Parquet file
+            parquet_memoryview (memoryview, optional): Parquet data in memory
+            dataframe (pd.DataFrame, optional): pandas DataFrame to wrap
+            arrow_table (pa.Table, optional): PyArrow Table to wrap
+            use_memfd (bool, optional): Use memory-based file descriptors on Linux
         """
         self._parquet_path = parquet_path
         self._temp_parquet_path = temp_parquet_path
@@ -46,15 +82,47 @@ class Table:
                 pass
 
     def rows_read(self):
+        """Get the number of rows read from the last query operation.
+
+        Returns:
+            int: Number of rows processed in the last query
+        """
         return self._rows_read
 
     def bytes_read(self):
+        """Get the number of bytes read from the last query operation.
+
+        Returns:
+            int: Number of bytes processed in the last query
+        """
         return self._bytes_read
 
     def elapsed(self):
+        """Get the elapsed time for the last query operation.
+
+        Returns:
+            float: Query execution time
+        """
         return self._elapsed
 
     def to_pandas(self) -> pd.DataFrame:
+        """Convert the Table data to a pandas DataFrame.
+
+        This method handles conversion from various internal formats (Parquet files,
+        memory buffers, Arrow tables) to a unified pandas DataFrame representation.
+
+        Returns:
+            pd.DataFrame: The table data as a pandas DataFrame
+
+        Raises:
+            ValueError: If no data source is available in the Table object
+
+        Example:
+            >>> table = Table(dataframe=df)
+            >>> result_table = table.query("SELECT * FROM __table__ LIMIT 5")
+            >>> df_result = result_table.to_pandas()
+            >>> print(df_result)
+        """
         if self._dataframe is None:
             if self._arrow_table is not None:
                 return self._arrow_table.to_pandas()
@@ -71,8 +139,20 @@ class Table:
         return self._dataframe
 
     def flush_to_disk(self):
-        """
-        Flush the data in memory to disk.
+        """Flush in-memory data to disk as a temporary Parquet file.
+
+        This method converts in-memory data (DataFrame, Arrow table, or memory buffer)
+        to a temporary Parquet file on disk. This can be useful for memory management
+        or when working with large datasets.
+
+        The method does nothing if data is already stored on disk.
+
+        Raises:
+            ValueError: If the Table object contains no data to flush
+
+        Example:
+            >>> table = Table(dataframe=large_df)
+            >>> table.flush_to_disk()  # Frees memory, keeps data accessible
         """
         if self._parquet_path is not None or self._temp_parquet_path is not None:
             return
@@ -112,10 +192,33 @@ class Table:
         return str(self.to_pandas())
 
     def query(self, sql: str, **kwargs) -> "Table":
-        """
-        Query on current Table object, return a new Table object.
-        The `FROM` table name in SQL should always be `__table__`. eg:
-            `SELECT * FROM __table__ WHERE ...`
+        """Execute SQL query on the current Table and return a new Table with results.
+
+        This method allows you to run SQL queries on the table data using chDB.
+        The table is referenced as '__table__' in the SQL statement.
+
+        Args:
+            sql (str): SQL query string. Must reference the table as '__table__'
+            **kwargs: Additional arguments passed to the chDB query engine
+
+        Returns:
+            Table: New Table object containing the query results
+
+        Raises:
+            ValueError: If SQL doesn't contain '__table__' reference or if Table is not initialized
+
+        Examples:
+            >>> table = Table(dataframe=df)
+            >>> # Filter rows
+            >>> result = table.query("SELECT * FROM __table__ WHERE age > 25")
+            >>>
+            >>> # Aggregate data
+            >>> summary = table.query("SELECT COUNT(*), AVG(salary) FROM __table__")
+            >>>
+            >>> # Complex operations
+            >>> processed = table.query(
+            ...     "SELECT name, age * 2 as double_age FROM __table__ ORDER BY age DESC"
+            ... )
         """
         self._validate_sql(sql)
 
@@ -138,6 +241,18 @@ class Table:
     sql = query
 
     def show(self):
+        """Display the Table data by printing the pandas DataFrame representation.
+
+        This is a convenience method for quickly viewing the table contents.
+        Equivalent to print(table.to_pandas()).
+
+        Example:
+            >>> table = Table(dataframe=df)
+            >>> table.show()
+               id    name
+            0   1   Alice
+            1   2     Bob
+        """
         print(self.to_pandas())
 
     def _query_on_path(self, path, sql, **kwargs):
@@ -220,12 +335,51 @@ class Table:
 
     @staticmethod
     def queryStatic(sql: str, **kwargs) -> "Table":
-        """
-        Query on multiple Tables, use Table variables as the table name in SQL
-        eg.
-            table1 = Table(...)
-            table2 = Table(...)
-            query("SELECT * FROM __table1__ JOIN __table2__ ON ...", table1=table1, table2=table2)
+        """Execute SQL query across multiple Table objects.
+
+        This static method enables complex queries involving multiple tables by referencing
+        them as '__tablename__' in the SQL and passing them as keyword arguments.
+
+        Args:
+            sql (str): SQL query with table references as '__name__' patterns
+            **kwargs: Table objects referenced in the SQL, where key matches the table name
+                     Can also include pandas DataFrames, which will be auto-converted to Tables
+
+        Returns:
+            Table: New Table object containing the query results
+
+        Raises:
+            ValueError: If referenced table names are missing from kwargs or have invalid types
+
+        Examples:
+            >>> users = Table(dataframe=users_df)
+            >>> orders = Table(dataframe=orders_df)
+            >>>
+            >>> # Join two tables
+            >>> result = Table.queryStatic(
+            ...     "SELECT u.name, COUNT(o.id) as order_count "
+            ...     "FROM __users__ u LEFT JOIN __orders__ o ON u.id = o.user_id "
+            ...     "GROUP BY u.name",
+            ...     users=users, orders=orders
+            ... )
+            >>>
+            >>> # Works with pandas DataFrames directly
+            >>> result = Table.queryStatic(
+            ...     "SELECT * FROM __df1__ UNION ALL SELECT * FROM __df2__",
+            ...     df1=dataframe1, df2=dataframe2
+            ... )
+            >>>
+            >>> # Complex multi-table operations
+            >>> analytics = Table.queryStatic(
+            ...     "SELECT p.category, AVG(o.amount) as avg_order "
+            ...     "FROM __products__ p "
+            ...     "JOIN __order_items__ oi ON p.id = oi.product_id "
+            ...     "JOIN __orders__ o ON oi.order_id = o.id "
+            ...     "GROUP BY p.category ORDER BY avg_order DESC",
+            ...     products=products_table,
+            ...     order_items=order_items_table,
+            ...     orders=orders_table
+            ... )
         """
         ansiTablePattern = re.compile(r"__([a-zA-Z][a-zA-Z0-9_]*)__")
         temp_paths = []
@@ -322,13 +476,47 @@ class Table:
 
 
 def pandas_read_parquet(path) -> pd.DataFrame:
+    """Read a Parquet file into a pandas DataFrame.
+
+    This is a convenience wrapper around pandas.read_parquet() for consistency
+    with the chdb.dataframe module interface.
+
+    Args:
+        path: File path or file-like object to read from
+
+    Returns:
+        pd.DataFrame: The loaded DataFrame
+    """
     return pd.read_parquet(path)
 
 
 def memfd_create(name: str = None) -> int:
-    """
-    Try to use memfd_create(2) to create a file descriptor with memory.
-    Only available on Linux 3.17 or newer with glibc 2.27 or newer.
+    """Create an in-memory file descriptor using memfd_create system call.
+
+    This function attempts to use the Linux-specific memfd_create(2) system call
+    to create a file descriptor that refers to an anonymous memory-backed file.
+    This provides better performance for temporary data operations.
+
+    Args:
+        name (str, optional): Name for the memory file (for debugging). Defaults to None.
+
+    Returns:
+        int: File descriptor on success, -1 on failure or if not supported
+
+    Note:
+        This function only works on Linux 3.17 or newer with glibc 2.27 or newer.
+        On other systems or if the call fails, it returns -1 and callers should
+        fall back to regular temporary files.
+
+    Example:
+        >>> fd = memfd_create("temp_data")
+        >>> if fd != -1:
+        ...     # Use memory-based file descriptor
+        ...     with os.fdopen(fd, 'wb') as f:
+        ...         f.write(data)
+        ... else:
+        ...     # Fall back to regular temp file
+        ...     fd, path = tempfile.mkstemp()
     """
     if hasattr(os, "memfd_create"):
         try:

chdb/dbapi/__init__.py

@@ -13,20 +13,58 @@ paramstyle = "format"
 
 
 class DBAPISet(frozenset):
+    """Extended frozenset for DB-API 2.0 type comparison.
+
+    This class extends frozenset to support DB-API 2.0 type comparison semantics.
+    It allows for flexible type checking where individual items can be compared
+    against the set using both equality and inequality operators.
+
+    This is used for type constants like STRING, BINARY, NUMBER, etc. to enable
+    comparisons like "field_type == STRING" where field_type is a single type value.
+
+    Examples:
+        >>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
+        >>> FIELD_TYPE.STRING == string_types  # Returns True
+        >>> FIELD_TYPE.INT != string_types     # Returns True
+        >>> FIELD_TYPE.BLOB in string_types    # Returns False
+    """
 
     def __ne__(self, other):
+        """Check inequality with flexible type comparison.
+
+        Args:
+            other: Value to compare against this set
+
+        Returns:
+            bool: True if other is not in this set (for non-set types) or
+                  True if sets are not equal (for set types)
+        """
         if isinstance(other, set):
             return frozenset.__ne__(self, other)
         else:
             return other not in self
 
     def __eq__(self, other):
+        """Check equality with flexible type comparison.
+
+        Args:
+            other: Value to compare against this set
+
+        Returns:
+            bool: True if other is in this set (for non-set types) or
+                  True if sets are equal (for set types)
+        """
         if isinstance(other, frozenset):
             return frozenset.__eq__(self, other)
         else:
             return other in self
 
     def __hash__(self):
+        """Return hash value for the set.
+
+        Returns:
+            int: Hash value of the underlying frozenset
+        """
         return frozenset.__hash__(self)
 
 
@@ -47,7 +85,17 @@ ROWID = DBAPISet()
 
 
 def Binary(x):
-    """Return x as a binary type."""
+    """Return x as a binary type.
+
+    This function converts the input to bytes type for use with binary
+    database fields, following the DB-API 2.0 specification.
+
+    Args:
+        x: Input data to convert to binary
+
+    Returns:
+        bytes: The input converted to bytes
+    """
     return bytes(x)
 
 
@@ -65,7 +113,14 @@ if _orig_conn.Connection.__init__.__doc__ is not None:
 del _orig_conn
 
 
-def get_client_info():  # for MySQLdb compatibility
+def get_client_info():
+    """Get client version information.
+
+    Returns the chDB client version as a string for MySQLdb compatibility.
+
+    Returns:
+        str: Version string in format 'major.minor.patch'
+    """
     version = chdb_version
     if len(chdb_version) > 3 and chdb_version[3] is None:
         version = chdb_version[:3]