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)[source]

Считывает SQL-запрос или таблицу базы данных в DataFrame.

Эта функция представляет собой удобную обёртку над read_sql_table и read_sql_query (для обеспечения обратной совместимости). Она передаёт выполнение соответствующей функции в зависимости от предоставленных входных данных. SQL-запрос будет передан в read_sql_query, а имя таблицы базы данных — в read_sql_table. Обратите внимание, что в документации делегируемой функции могут содержаться более подробные примечания о её функциональности, не приведённые здесь.

Параметры:

sql:str или SQLAlchemy Selectable (объект select или text)

SQL-запрос для выполнения или имя таблицы.

con:подключение ADBC, подключаемый объект SQLAlchemy, строка или подключение sqlite3

ADBC обеспечивает высокую производительность ввода-вывода с поддержкой собственных типов, если она доступна. Использование SQLAlchemy позволяет работать с любой базой данных, поддерживаемой этой библиотекой. Если передан объект DBAPI2, поддерживается только sqlite3. Пользователь отвечает за освобождение ресурсов движка и закрытие подключений ADBC и подключаемого объекта SQLAlchemy; строковые подключения закрываются автоматически. См. здесь.

index_col:str или список str, необязательный, по умолчанию: None

Столбец или столбцы, которые нужно задать в качестве индекса (MultiIndex).

coerce_float:bool, по умолчанию True

Пытается преобразовать значения объектов, не являющихся строками или числами (например, decimal.Decimal), в числа с плавающей точкой; это полезно для наборов результатов SQL-запросов.

params:list, tuple или dict, необязательный, по умолчанию: None

Список параметров, передаваемых методу execute. Синтаксис передачи параметров зависит от драйвера базы данных. В документации драйвера базы данных проверьте, какой из пяти стилей синтаксиса, описанных в параметре paramstyle PEP 249, поддерживается. Например, psycopg2 использует %(name)s, поэтому следует использовать params={‘name’ : ‘value’}.

parse_dates:list или dict, по умолчанию: None

• Список имён столбцов, которые нужно разобрать как даты.

• Словарь {column_name: format string}, где строка формата совместима со strftime при разборе строкового времени или является одним из значений (D, s, ns, ms, us) при разборе целочисленных меток времени.

• Словарь {column_name: arg dict}, где словарь аргументов соответствует именованным аргументам pandas.to_datetime(). Особенно полезно для баз данных без встроенной поддержки Datetime, например SQLite.

columns:list, по умолчанию: None

Список имён столбцов, которые нужно выбрать из таблицы SQL (используется только при чтении таблицы).

chunksize:int, по умолчанию None

Если указано, возвращается итератор, в котором chunksize задаёт количество строк в каждом фрагменте.

dtype_backend:{‘numpy_nullable’, ‘pyarrow’}, по умолчанию ‘numpy_nullable’

Тип данных внутреннего механизма, применяемый к результирующему объекту DataFrame (экспериментальная функциональность). Поведение следующее:

• "numpy_nullable": возвращает объект DataFrame с типами данных, поддерживающими значения null (по умолчанию).

• "pyarrow": возвращает DataFrame с типами, поддерживающими значения null, на основе pyarrow ArrowDtype.

Добавлено в версии 2.0.

dtype:имя типа или словарь столбцов

Тип данных для данных или столбцов. Например, np.float64 или {‘a’: np.float64, ‘b’: np.int32, ‘c’: ‘Int64’}. Аргумент игнорируется, если вместо запроса передана таблица.

Добавлено в версии 2.0.0.

Возвращает:

DataFrame или Iterator[DataFrame]

См. также

read_sql_table

Считывает таблицу базы данных SQL в DataFrame.

read_sql_query

Считывает SQL-запрос в DataFrame.

Примеры

Считывайте данные из 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')  

Применяйте разбор дат к столбцам с помощью аргумента 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

Добавлено в версии 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