pandas pd.read_sql() 读取数据库数据

看过来

《pandas 教程》持续更新中，提供建议、纠错、催更等加作者微信: gairuo123（备注：pandas教程）和关注公众号「盖若」ID: gairuo。跟作者学习，请进入 Python学习课程。欢迎关注作者出版的书籍：《深入浅出Pandas》和《Python之光》。

pandas.read_sql() 是 pandas 库中用于从数据库中读取数据并将其转换为 DataFrame 的函数。它支持多种数据库接口，允许用户通过 SQL 查询直接获取数据，非常适合数据分析和处理工作。

语法

pandas.read_sql(
    sql,
    con,
    index_col=None,
    coerce_float=True,
    params=None,
    parse_dates=None,
    columns=None,
    chunksize=None,
    dtype_backend=<no_default>,
    dtype=None
)

此函数是 read_sql_table 和 read_sql_query的便利包装器（用于向后兼容性）。它将根据提供的输入委托给特定功能。SQL查询将被路由到 read_SQL_query，而数据库表名将被路由到read_SQL_table。请注意，委托功能可能有更多关于其功能的具体说明，此处未列出。

参数详解

sql:
- 类型: str 或 sqlalchemy.sql.Selectable
- 说明: 要执行的 SQL 查询语句，可以是 SQL 字符串或 SQLAlchemy 的 Select 对象。
con:
- 类型: SQLAlchemy connectable 或 DBAPI2 connection
- 说明: 数据库连接对象，支持多种数据库，如 SQLite、PostgreSQL、MySQL 等。
index_col:
- 类型: str 或 list，默认 None
- 说明: 指定用作行索引的列名或列名列表。
coerce_float:
- 类型: bool，默认 True
- 说明: 是否尝试将非字符串、数字类型的数据转换为浮点数。
params:
- 类型: list, tuple 或 dict，默认 None
- 说明: 用于 SQL 查询的参数，可以防止 SQL 注入。
parse_dates:
- 类型: list 或 dict，默认 None
- 说明: 指定需要解析为日期时间的列。
columns:
- 类型: list，默认 None
- 说明: 指定要返回的列名列表。
chunksize:
- 类型: int，默认 None
- 说明: 如果设置，返回一个迭代器，每次读取指定行数的数据块。
dtype_backend:
- 类型: str，默认 <no_default>
- 说明: 指定后端数据类型支持（如 Arrow）。
dtype:
- 类型: dict 或 pandas.Series.dtype，默认 None
- 说明: 指定列的数据类型。

返回值

类型: pandas.DataFrame 或 pandas.io.sql.DatabaseError
说明: 执行 SQL 查询后返回的结果数据，默认以 DataFrame 形式返回。如果设置了 chunksize，则返回一个迭代器，每次迭代返回一个 DataFrame。

使用场景

数据提取: 从关系型数据库中提取数据进行分析。
数据集成: 将多个数据库的数据整合到 pandas 中进行处理。
实时数据处理: 使用 chunksize 处理大型数据集，节省内存。

示例

假设我们有一个 SQLite 数据库 example.db，其中有一个表 users，结构如下：

CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT,
    age INTEGER,
    signup_date TEXT
);

并插入了一些示例数据：

INSERT INTO users (name, age, signup_date) VALUES
('Alice', 30, '2023-01-15'),
('Bob', 25, '2023-02-20'),
('Charlie', 35, '2023-03-10');

示例 1：基本用法

读取 users 表的所有数据。

import pandas as pd
import sqlite3

# 连接到 SQLite 数据库
conn = sqlite3.connect('example.db')

# 执行 SQL 查询并读取数据
df = pd.read_sql("SELECT * FROM users", conn)

print(df)

输出

   id     name  age signup_date
0   1    Alice   30  2023-01-15
1   2      Bob   25  2023-02-20
2   3  Charlie   35  2023-03-10

示例 2：指定索引列

将 id 列设置为 DataFrame 的索引。

df = pd.read_sql("SELECT * FROM users", conn, index_col='id')
print(df)

输出

       name  age signup_date
id                          
1     Alice   30  2023-01-15
2       Bob   25  2023-02-20
3   Charlie   35  2023-03-10

示例 3：参数化查询

使用参数防止 SQL 注入，查询年龄大于某个值的用户。

age_threshold = 28
df = pd.read_sql("SELECT * FROM users WHERE age > ?", conn, params=(age_threshold,))
print(df)

输出

   id     name  age signup_date
0   1    Alice   30  2023-01-15
1   3  Charlie   35  2023-03-10

示例 4：解析日期列

将 signup_date 列解析为日期时间类型。

df = pd.read_sql(
    "SELECT * FROM users",
    conn,
    parse_dates=['signup_date']
)
print(df.dtypes)

输出

id                     int64
name                  object
age                    int64
signup_date    datetime64[ns]
dtype: object

示例 5：分块读取大型数据

假设 users 表有大量数据，使用 chunksize 分块读取。

chunks = pd.read_sql("SELECT * FROM users", conn, chunksize=2)

for chunk in chunks:
    print(chunk)

输出

   id     name  age signup_date
0   1    Alice   30  2023-01-15
1   2      Bob   25  2023-02-20
   id     name  age signup_date
2   3  Charlie   35  2023-03-10

总结

pandas.read_sql() 是一个功能强大的工具，可以方便地将数据库中的数据导入到 pandas DataFrame 中进行分析。通过灵活的参数设置，可以满足各种数据读取需求，从简单的数据提取到复杂的参数化查询和大数据分块处理。

参考

https://pandas.pydata.org/docs/reference/api/pandas.read_sql.html