Metadata-Version: 2.4
Name: alcedo-pdbc
Version: 0.1.3b0
Summary: Add your description here
Author-email: AI Lab 100 <ailab100@163.com>
Project-URL: Funding, https://donate.pypi.org
Project-URL: Source, https://github.com/
Keywords: pdbc,sql
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: connectorx==0.3.3
Requires-Dist: dask[dataframe]==2024.8.0
Requires-Dist: fastparquet==2024.11.0
Requires-Dist: mysql-connector-python-rf==2.2.2
Requires-Dist: numpy
Requires-Dist: openpyxl==3.1.5
Requires-Dist: pandas
Requires-Dist: polars==1.6.0
Requires-Dist: pyyaml==6.0.2
Requires-Dist: sqlalchemy
Requires-Dist: tables
Requires-Dist: xlrd==2.0.1
Requires-Dist: xlwt==1.3.0
Requires-Dist: redis==5.2.1
Requires-Dist: pyotp>=2.9.0
Requires-Dist: typer>=0.16.0
Provides-Extra: all
Requires-Dist: azure-storage-blob==12.15.0; extra == "all"
Requires-Dist: boto3==1.37.27; extra == "all"
Requires-Dist: elasticsearch==8.17.2; extra == "all"
Requires-Dist: google-cloud-storage==3.1.0; extra == "all"
Requires-Dist: minio==7.2.15; extra == "all"
Requires-Dist: pymongo==4.11.3; extra == "all"
Requires-Dist: pymysql>=1.1.1; extra == "all"
Requires-Dist: snowflake-connector-python>=3.0.2; extra == "all"
Provides-Extra: sql
Requires-Dist: pymysql>=1.1.1; extra == "sql"
Provides-Extra: nosql
Requires-Dist: pymongo==4.11.3; extra == "nosql"
Requires-Dist: elasticsearch==8.17.2; extra == "nosql"
Provides-Extra: datalake
Requires-Dist: boto3==1.37.27; extra == "datalake"
Requires-Dist: minio==7.2.15; extra == "datalake"
Requires-Dist: google-cloud-storage==3.1.0; extra == "datalake"
Requires-Dist: azure-storage-blob==12.15.0; extra == "datalake"
Provides-Extra: datawarehouse
Requires-Dist: snowflake-connector-python>=3.0.2; extra == "datawarehouse"
Provides-Extra: dev
Requires-Dist: pyotp>=2.9.0; extra == "dev"
Requires-Dist: build>=1.3.0; extra == "dev"
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: setuptools==80.9.0; extra == "dev"
Requires-Dist: wheel>=0.45.1; extra == "dev"
Requires-Dist: Cython==3.1.2; extra == "dev"
Requires-Dist: mkdocs==1.6.1; extra == "dev"
Requires-Dist: mkdocs-autorefs==1.2.0; extra == "dev"
Requires-Dist: mkdocs-get-deps==0.2.0; extra == "dev"
Requires-Dist: mkdocs-material==9.5.34; extra == "dev"
Requires-Dist: mkdocs-material-extensions==1.3.1; extra == "dev"
Requires-Dist: mkdocstrings==0.26.1; extra == "dev"
Requires-Dist: mkdocstrings-python==1.11.1; extra == "dev"
Requires-Dist: griffe; extra == "dev"
Requires-Dist: Markdown==3.7; extra == "dev"
Requires-Dist: markdown-it-py==3.0.0; extra == "dev"
Requires-Dist: twine==6.1.0; extra == "dev"
Dynamic: license-file




                         
# ALcedo PDBC 项目简介

## 一、概述

ALcedo PDBC &reg; (Python DataBase Connectivity) 是数智教育发展(山东)有限公司 AI Lab 100 团队开发的高效、灵活的数据接口(API)
，它能够使您以最快、最节省内存的方式将数据从数据库加载到 Python 中，它旨在简化大数据访问和处理，提供一种统一的方式来与各种数据源进行交互，加速
ML 和 ETL 开发过程。

ALcedo PDBC &reg; 与 JDBC、ODBC 类似，专注于为Python应用程序、AI模型提供访问数据的编程接口。它支持主流的
RMDBS (关系型数据库)、NoSQL (
非结构化数据库)、DataLake (数据湖) 和 Data
Warehouse (数据仓库) ，包括但不限于 MySQL、SQL SERVER、SQLite、ORACLE、MariaDB
、PostgreSQL、MongoDB、Redis、Elasticsearch、MinIO、Amazon
S3、Google Cloud Storage (GCS)等。

## 二、技术特点及应用场景

**ALcedo PDBC 具有以下技术特点：**

1. 兼容性广泛： 支持多种数据库系统和文件存储服务，包括 RMDBS 关系型数据库和 NoSQL 数据库，并且兼容 MinIO 和 Flink 等大数据处理框架。

2. 接口简明易用： 将复杂的技术细节封装在内部，对 RMDBS 而言，接口统一、简洁明了。

3. 性能优化： ALcedo PDBC  使用了缓存及多线程等技术，以提高查询速度和资源利用率。通过减少不必要的网络通信和提升批处理能力，性能比传统连接器有显著的提升。

4. 动态代码生成：  ALcedo PDBC  可以在运行时动态生成优化的查询执行代码，这种做法既保留了灵活性，又保证了效率。

5. 灵活配置： 允许用户自定义连接参数，满足不同环境和业务需求下的定制化要求。

**ALcedo PDBC 的应用场景包括不限于以下：**

- 大数据分析： 在Python中进行大规模数据处理和分析，利用 ALcedo PDBC 可大大提升查询速度。

- AI模型开发： 在Python中进行AI模型开发过程中，利用 ALcedo PDBC 可快速的实现多源数据读取，为AI模型提供实时的数据流处理；

- 数据集成： 可实现跨数据库迁移数据，或者将不同来源的数据集成到同一个处理平台。

- 云存储访问： 方便地读写云存储上的文件，如azure S3，提升云计算场景下的数据操作效率。

## 三、数据源及输出

 ALcedo PDBC 模块中通过mysql、nosql、datalake、datawarehouse 类的封装，实现了不同数据源接口的支持；

数据源:

- [x] Mysql
- [x] SQL Server
- [x] PostgreSQL
- [x] Oracle
- [x] MariaDB
- [x] SQLite
- [x] MongoDB
- [x] Elasticsearch
- [x] Redis
- [x] DynamoDB
- [x] MinIO
- [x] Amazon S3
- [x] Google Cloud Storage (GCS)
- [x] Microsoft AzureBlob
- [x] Doris
- [x] SnowFlake
- [x] BigQuery
- [x] Redshift
- [x] StarRocks
- [ ] ...

输出 DataFrame:

- [x] Pandas
- [x] Polars
- [x] Dask

输出 File:

- [x] CSV
- [x] Excel
- [x] JSON
- [x] HTML
- [x] HDF5
- [x] Feather
- [x] Parquet
- [x] Apache Avro

<table>
  <tr>
    <th rowspan="2">类型</th>
    <th style="min-width: 120px;" rowspan="2">数据源</th>
    <th colspan="3"> DataFrame数据框 </th>
    <th  style="min-width: 160px;" rowspan="2" > File文件 </th>
    <th  rowspan="2" >备注</th>
  </tr>
<tr>
    <th >Pandas</th>
    <th >Polars</th>
    <th >Dask</th>

  </tr>

<tr>
    <td rowspan="6">结构化SQL</td>
    <td>MySQL</td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br> ✖  write </td>
    <td>✅ CSV   ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet  ✖ Apache Avro  </td>
    <td></td>
  </tr>
  <tr>
    <td>SQL SERVER</td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br> ✖  write </td>
   <td>✅ CSV   ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet ✖ Apache Avro  </td>
    <td></td>
  </tr>
 <tr>
    <td>PostgreSQL</td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br> ✖  write </td>
   <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet ✖ Apache Avro  </td>
    <td></td>
  </tr>
  <tr>
    <td>Oracle</td>
   <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br> ✖  write </td>
   <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet ✖ Apache Avro  </td>
    <td></td>
  </tr>
  <tr>
    <td>MariaDB</td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br> ✖  write </td>
   <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet  ✖ Apache Avro  </td>
    <td></td>
  </tr>
  <tr>
    <td>SQLite</td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br> ✖  write </td>
    <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet  ✖ Apache Avro  </td>
    <td></td>
  </tr>
 <tr>
    <td rowspan="4">非结构化noSQL</td>
    <td>MongoDB</td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write</td>
    <td> ✖ </td>
    <td>✅ CSV ✅ Excel <br> ✖ JSON  ✅ HTML  <br> ✖  HDF5  ✖  Feather  <br> ✖  Parquet ✖ Apache Avro  </td>
  </tr>
  <tr>
    <td>ElasticSearch</td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br> ✖  write</td>
    <td> ✖ </td>
   <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet ✖ Apache Avro  </td>
  </tr>

<tr>
    <td>Redis</td>
    <td>✅ read </td>
    <td> ✖  </td>
    <td> ✖  </td>
   <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet  ✖ Apache Avro  </td>
    <td>    </td>
  </tr>
<tr>
    <td>DynamoDB</td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write</td>
    <td> ✖ </td>
   <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet ✖ Apache Avro  </td>
    <td>   </td>
  </tr>
<tr>
    <td rowspan="4">datalake</td>
    <td> MinIO </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write</td>
    <td>✅ read<br> ✖  write</td>
   <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet ✖ Apache Avro  </td>
    <td>✅ read<br> ✖  write</td>
  </tr>
<tr>
    <td> S3 </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write</td>
    <td>✅ read<br> ✖  write</td>
   <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet  ✖ Apache Avro  </td>
    <td>✅ read<br> ✖  write</td>
  </tr>
<tr>
    <td> GCS </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write</td>
    <td>✅ read<br> ✖  write</td>
   <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet  ✖ Apache Avro  </td>
    <td>✅ read<br> ✖  write</td>
  </tr>
<tr>
    <td> AzureBlob  </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write</td>
    <td>✅ read<br> ✖  write</td>
   <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet  ✖ Apache Avro  </td>
    <td>✅ read<br> ✖  write</td>
  </tr>
<tr>
    <td rowspan="5">dataware house</td>
    <td> Doris </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write</td>
    <td>✅ read<br> ✖  write</td>
  <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet  ✖ Apache Avro  </td>
    <td>✅ read<br> ✖  write</td>
  </tr>
<tr>
    <td> SnowFlake </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write</td>
    <td>✅ read<br> ✖  write</td>
   <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet  ✖ Apache Avro  </td>
    <td>✅ read<br> ✖  write</td>
  </tr>

<tr>
    <td> BigQuery </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write</td>
    <td>✅ read<br> ✖  write</td>
  <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet  ✖ Apache Avro  </td>
    <td>✅ read<br> ✖  write</td>
  </tr>
<tr>
    <td> Redshift </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write</td>
    <td>✅ read<br> ✖  write</td>
  <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet  ✖ Apache Avro  </td>
    <td>✅ read<br> ✖  write</td>
  </tr>
<tr>
    <td> StarRocks </td>
    <td>✅ read<br>✅ write </td>
    <td>✅ read<br>✅ write</td>
    <td>✅ read<br> ✖  write</td>
  <td>✅ CSV ✅ Excel <br> ✅ JSON  ✅ HTML  <br> ✅ HDF5  ✅ Feather  <br> ✅ Parquet ✖ Apache Avro  </td>
    <td>✅ read<br> ✖  write</td>
  </tr>


</table>


> 备注：导出xlsx需要openpyxl ；Parquet列式存储数据文件 ； Feather压缩二进制文件。

## 四、快速启动

可通过 pip 安装 ALcedo PDBC，考虑到国内镜像源更新问题，安装时指定从PyPI官方源下载。

```bash
pip install --index-url https://pypi.org/simple/ alcedo-pdbc

```


以MySQL为例，您仅需要几行代码：

```python

# 在 AI Lab 100 中通过ailab100.pdbc导入
# from ailab100.pdbc.sql import MySQL
from alcedo_pdbc.sql import MySQL

db_mysql = MySQL()
df = db_mysql.read_as_dataframe(table_name="public_rent_price_forecast_data",
                                params={"houseFloor":"低","totalFloor":2},
                                return_type='polars'
                                )

```

或者，您可以通过多线程加速数据加载。

```python
# 在 AI Lab 100 中通过ailab100.pdbc导入

# from ailab100.pdbc.datalake import MinIO
from alcedo_pdbc.datalake import MinIO

minio_client = MinIO('127.0.0.1:9000',
                     access_key='Q3AM3UQ867SPQQA43P2F',
                     secret_key='zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
                     )
minio_client.download_file(minio_path="s3://datalake/datasets/3财务困境研究数据集/ST财务预警.csv",num_threads=4)

```

该函数将通过将指定的线程数平均拆分为分区数来对查询进行分区，并为每个分区分配一个线程来并行加载和写入数据。

## 五、性能

实验室通过比较 Python 中的不同解决方案，采用 4 个线程并行处理，读取 MySQL 中一个 10,981,106 行的数据表 （1,092,616,192
字节，1.02 GB） 加载到 DataFrame 中，实验结果如下：

- **1.响应时间 (越短越好)**

![pg-time.png](./images/mysql_time.png)

- **2.内存消耗 (越低越好)**

![pg-time.png](./images/mysql_mem.png)

总之，ALcedo PDBC  使用的内存减少了 1/3 ，与 Pandas 相比响应时间减少了近 1 倍（与 Polars 相比，响应时间相差无几 ）。

## 六、生态系统

<div style="display: flex;align-items: center ">
<img src="./images/polars_logo.png" 
style="margin-bottom: -2px;height: 30px" />
<img src="./images/pandas_logo.png" 
style="margin-bottom: -2px;height: 50px"/>
</div>


## 七、版本更新

### 0.1.2b0 

- 此版本增加了redis缓存配置，提高数据读取速度；
- 可通过系统环境变量定义各类数据库的连接信息；

### 0.1.3b0 

- 增加命令行界面 CLI和docs文档集成，可通过alcedo-cli docs启动文档；
- 增加了自动化编译打包的脚本文件，支持
- 增加了各类数据库docker-compose部署模板,详见samples_docker目录中的docker-compose-db.yml
---
