pandas.read_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)

将 SQL 查询或数据库表读取到 DataFrame 中。

这个函数是围绕 read_sql_table 和 read_sql_query 的便捷包装（为了向后兼容）。它将根据提供的输入委托给特定函数。SQL 查询将被路由到 read_sql_query，而数据库表名将被路由到 read_sql_table。请注意，委托的函数可能会有更多关于其功能的特定说明，这里未列出。

参数:

sqlstr 或 SQLAlchemy 可选择对象（选择或文本对象）

要执行的SQL查询或表名。

conADBC 连接、SQLAlchemy 可连接对象、字符串或 sqlite3 连接

ADBC 提供了高性能的 I/O 和原生类型支持（如果可用）。使用 SQLAlchemy 可以使其支持该库支持的任何数据库。如果是一个 DBAPI2 对象，则仅支持 sqlite3。用户负责 ADBC 连接和 SQLAlchemy 可连接对象的引擎处置和连接关闭；字符串连接会自动关闭。详见 这里。

index_colstr 或 str 列表，可选，默认值：None

要设置为索引（MultiIndex）的列。

coerce_floatbool, 默认为 True

尝试将非字符串、非数字对象（如 decimal.Decimal）的值转换为浮点数，这对 SQL 结果集非常有用。

参数列表、元组或字典，可选，默认：无

传递给 execute 方法的参数列表。传递参数的语法依赖于数据库驱动。检查您的数据库驱动文档，了解支持 PEP 249 的 paramstyle 中描述的五种语法风格中的哪一种。例如，对于 psycopg2，使用 %(name)s，因此使用 params={‘name’ : ‘value’}。

parse_dates列表或字典，默认：无

• 要解析为日期的列名列表。

• {column_name: format string} 的字典，其中格式字符串在解析字符串时间时是与 strftime 兼容的，或者在解析整数时间戳时是 (D, s, ns, ms, us) 之一。

• {column_name: arg dict} 的字典，其中 arg dict 对应于 pandas.to_datetime() 的关键字参数。特别适用于没有原生日期时间支持的数据库，例如 SQLite。

列列表，默认：无

要从SQL表中选择的列名列表（仅在读取表时使用）。

chunksizeint, 默认为 None

如果指定，返回一个迭代器，其中 chunksize 是每个块中包含的行数。

dtype_backend{‘numpy_nullable’, ‘pyarrow’}

应用于结果 DataFrame 的后端数据类型（仍在实验中）。如果未指定，默认行为是不使用可空数据类型。如果指定，行为如下：

• "numpy_nullable": 返回支持可空数据类型的 DataFrame

• "pyarrow": 返回由 pyarrow 支持的可空 ArrowDtype DataFrame

Added in version 2.0.

dtype输入列名或列的字典

数据或列的数据类型。例如 np.float64 或 {‘a’: np.float64, ‘b’: np.int32, ‘c’: ‘Int64’}。如果传递的是表格而不是查询，则忽略该参数。

Added in version 2.0.0.

返回:

DataFrame 或 Iterator[DataFrame]

返回一个包含执行的 SQL 查询或基于提供的输入的 SQL 表的结果集的 DataFrame 对象，与指定的数据库连接相关。

参见

read_sql_table

将 SQL 数据库表读取到 DataFrame 中。

read_sql_query

将 SQL 查询读取到 DataFrame 中。

备注

pandas 不会尝试清理 SQL 语句；相反，它只是将您正在执行的语句转发给底层驱动程序，底层驱动程序可能会也可能不会从那里进行清理。有关详细信息，请参阅底层驱动程序文档。通常，在接受来自任意来源的语句时要小心。

例子

通过SQL查询或SQL表名从SQL读取数据。当使用SQLite数据库时，仅接受SQL查询，仅提供SQL表名将导致错误。

>>> from sqlite3 import connect
>>> conn = connect(":memory:")
>>> df = pd.DataFrame(
...     data=[[0, "10/11/12"], [1, "12/11/10"]],
...     columns=["int_column", "date_column"],
... )
>>> df.to_sql(name="test_data", con=conn)
2

>>> pd.read_sql("SELECT int_column, date_column FROM test_data", conn)
   int_column date_column
0           0    10/11/12
1           1    12/11/10

>>> pd.read_sql("test_data", "postgres:///db_name")  

对于参数化查询，建议使用 params 而不是字符串插值。

>>> from sqlalchemy import text
>>> sql = text(
...     "SELECT int_column, date_column FROM test_data WHERE int_column=:int_val"
... )
>>> pd.read_sql(sql, conn, params={"int_val": 1})  
   int_column date_column
0           1    12/11/10

通过 parse_dates 参数对列应用日期解析 parse_dates 参数在提供的列上调用 pd.to_datetime。通过字典格式指定在列上应用 pd.to_datetime 的自定义参数值：

>>> pd.read_sql(
...     "SELECT int_column, date_column FROM test_data",
...     conn,
...     parse_dates={"date_column": {"format": "%d/%m/%y"}},
... )
   int_column date_column
0           0  2012-11-10
1           1  2010-11-12

Added in version 2.2.0: pandas 现在通过 ADBC 驱动程序支持读取

>>> from adbc_driver_postgresql import dbapi  
>>> with dbapi.connect("postgres:///db_name") as conn:  
...     pd.read_sql("SELECT int_column FROM test_data", conn)
   int_column
0           0
1           1