Python API Reference

**Example**

```
@chdb_udf()
def sum_udf(lhs, rhs):
    return int(lhs) + int(rhs)

@chdb_udf()
def func_use_json(arg):
    import json
    # ... use json module
```

---

### `chdb.udf.generate_udf`[​](#generate-udf "Direct link to generate-udf")

Generate UDF configuration and executable script files.

This function creates the necessary files for a User Defined Function (UDF) in chDB:

1. A Python executable script that processes input data
2. An XML configuration file that registers the UDF with ClickHouse

**Syntax**

```
chdb.udf.generate_udf(func_name, args, return_type, udf_body)
```

**Parameters**

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Description|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `func_name` str Name of the UDF function|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `args` list List of argument names for the function|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `return_type` str ClickHouse return type for the function|  |  |  | | --- | --- | --- | | `udf_body` str Python source code body of the UDF function | | | | | | | | | | | | | | |

Note

This function is typically called by the @chdb\_udf decorator and shouldn't
be called directly by users.

---

## Utilities[​](#utilities "Direct link to Utilities")

Utility functions and helpers for chDB.

This module contains various utility functions for working with chDB, including
data type inference, data conversion helpers, and debugging utilities.

---

### `chdb.utils.convert_to_columnar`[​](#convert-to-columnar "Direct link to convert-to-columnar")

Converts a list of dictionaries into a columnar format.

This function takes a list of dictionaries and converts it into a dictionary
where each key corresponds to a column and each value is a list of column values.
Missing values in the dictionaries are represented as None.

**Syntax**

```
chdb.utils.convert_to_columnar(items: List[Dict[str, Any]]) → Dict[str, List[Any]]
```

**Parameters**

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| Parameter Type Description|  |  |  | | --- | --- | --- | | `items` `List[Dict[str, Any]]` A list of dictionaries to convert | | | | | |

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `Dict[str, List[Any]]` A dictionary with keys as column names and values as lists of column values | | | |

**Example**

```
>>> items = [
...     {"name": "Alice", "age": 30, "city": "New York"},
...     {"name": "Bob", "age": 25},
...     {"name": "Charlie", "city": "San Francisco"}
... ]
>>> convert_to_columnar(items)
{
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [30, 25, None],
    'city': ['New York', None, 'San Francisco']
}
```

---

### `chdb.utils.flatten_dict`[​](#flatten-dict "Direct link to flatten-dict")

Flattens a nested dictionary.

This function takes a nested dictionary and flattens it, concatenating nested keys
with a separator. Lists of dictionaries are serialized to JSON strings.

**Syntax**

```
chdb.utils.flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '_') → Dict[str, Any]
```

**Parameters**

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Default Description|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `d` `Dict[str, Any]` *required* The dictionary to flatten|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `parent_key` str `""` The base key to prepend to each key|  |  |  |  | | --- | --- | --- | --- | | `sep` str `"_"` The separator to use between concatenated keys | | | | | | | | | | | | | | | |

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `Dict[str, Any]` A flattened dictionary | | | |

**Example**

```
>>> nested_dict = {
...     "a": 1,
...     "b": {
...         "c": 2,
...         "d": {
...             "e": 3
...         }
...     },
...     "f": [4, 5, {"g": 6}],
...     "h": [{"i": 7}, {"j": 8}]
... }
>>> flatten_dict(nested_dict)
{
    'a': 1,
    'b_c': 2,
    'b_d_e': 3,
    'f_0': 4,
    'f_1': 5,
    'f_2_g': 6,
    'h': '[{"i": 7}, {"j": 8}]'
}
```

---

### `chdb.utils.infer_data_type`[​](#infer-data-type "Direct link to infer-data-type")

Infers the most suitable data type for a list of values.

This function examines a list of values and determines the most appropriate
data type that can represent all the values in the list. It considers integer,
unsigned integer, decimal, and float types, and defaults to “string” if the
values can't be represented by any numeric type or if all values are None.

**Syntax**

```
chdb.utils.infer_data_type(values: List[Any]) → str
```

**Parameters**

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| Parameter Type Description|  |  |  | | --- | --- | --- | | `values` `List[Any]` A list of values to analyze. The values can be of any type | | | | | |

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `str` A string representing the inferred data type. Possible return values are: ”int8”, “int16”, “int32”, “int64”, “int128”, “int256”, “uint8”, “uint16”,“uint32”, “uint64”, “uint128”, “uint256”, “decimal128”, “decimal256”, “float32”, “float64”, or “string”. | | | |

Note

- If all values in the list are None, the function returns “string”.
- If any value in the list is a string, the function immediately returns “string”.
- The function assumes that numeric values can be represented as integers,
  decimals, or floats based on their range and precision.

---

### `chdb.utils.infer_data_types`[​](#infer-data-types "Direct link to infer-data-types")

Infers data types for each column in a columnar data structure.

This function analyzes the values in each column and infers the most suitable
data type for each column, based on a sample of the data.

**Syntax**

```
chdb.utils.infer_data_types`(column_data: Dict[str, List[Any]], n_rows: int = 10000) → List[tuple]
```

**Parameters**

|  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Default Description|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `column_data` `Dict[str, List[Any]]` *required* A dictionary where keys are column names and values are lists of column values|  |  |  |  | | --- | --- | --- | --- | | `n_rows` int `10000` The number of rows to sample for type inference | | | | | | | | | | | |

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `List[tuple]` A list of tuples, each containing a column name and its inferred data type | | | |

## Abstract Base Classes[​](#abstract-base-classes "Direct link to Abstract Base Classes")

### **class** `chdb.rwabc.PyReader`(data: Any)`[​](#pyreader "Direct link to pyreader")

Bases: `ABC`

```
class chdb.rwabc.PyReader(data: Any)
```

---

#### **abstractmethod** `read`[​](#read "Direct link to read")

Read a specified number of rows from the given columns and return a list of objects,
where each object is a sequence of values for a column.

```
abstractmethod (col_names: List[str], count: int) → List[Any]
```

**Parameters**

|  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Description|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `col_names` `List[str]` List of column names to read|  |  |  | | --- | --- | --- | | `count` int Maximum number of rows to read | | | | | | | | |

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `List[Any]` List of sequences, one for each column | | | |

### **class** `chdb.rwabc.PyWriter`[​](#pywriter "Direct link to pywriter")

Bases: `ABC`