pandas.DataFrame.to_sql

DataFrame.to_sql(name, con, schema=None, if_exists='fail', index=True, index_label=None, chunksize=None, dtype=None, method=None)[source]

Запись записей, хранящихся в DataFrame, в базу данных SQL.

Поддерживаются базы данных, поддерживаемые SQLAlchemy [1]. Таблицы могут быть созданы, добавлены или перезаписаны.

Параметры

name:str

Имя SQL таблицы.

con:sqlalchemy.engine.(Engine or Connection) or sqlite3.Connection

Использование SQLAlchemy позволяет использовать любую базу данных, поддерживаемую этой библиотекой. Предоставляется обратная совместимость с объектами sqlite3.Connection. Пользователь отвечает за утилизацию движка и закрытие соединения для SQLAlchemy connectable. См. здесь.

schema:str, необязательно

Укажите схему (если база данных поддерживает это). Если None, используется схема по умолчанию.

if_exists:{‘fail’, ‘replace’, ‘append’}, по умолчанию ‘fail’

Как действовать, если таблица уже существует.

• fail: Вызывает ValueError.

• replace: Удаляет таблицу перед вставкой новых значений.

• append: Вставляет новые значения в существующую таблицу.

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

Записывать индекс DataFrame в виде столбца. Использует index_label в качестве имени столбца в таблице.

index_label:str или последовательность, по умолчанию None

Метка столбца для столбца(ов) индекса. Если None (по умолчанию) и index True, используются имена индекса. Если используется MultiIndex, должна быть передана последовательность.

chunksize:int, необязательно

Укажите количество строк в каждой партии, которые будут записываться за раз. По умолчанию все строки записываются сразу.

dtype:dict или скаляр, необязательно

Укажите тип данных для столбцов. Если используется словарь, ключи должны быть именами столбцов, а значения — типами SQLAlchemy или строками для режима совместимости sqlite3. Если предоставлен скаляр, он будет применен ко всем столбцам.

method:{None, ‘multi’, callable}, необязательно

Управляет используемой SQL-оператор вставки:

• None : Использует стандартный SQL INSERT оператор (один на строку).

• ‘multi’: Передает несколько значений в одном INSERT операторе.

• callable со сигнатурой (pd_table, conn, keys, data_iter).

Подробности и пример реализации вызываемого объекта можно найти в разделе метод вставки.

Возвращает

None или int

Количество строк, затронутых to_sql. Возвращает None, если вызываемый объект, переданный в method, не возвращает целое число строк.

Возвращаемое число затронутых строк — это сумма rowcount атрибута sqlite3.Cursor или SQLAlchemy connectable, который может не отражать точное количество записанных строк, как указано в sqlite3 или SQLAlchemy.

В версии 1.4.0.

Возбуждает

ValueError

Когда таблица уже существует и if_exists равно ‘fail’ (по умолчанию).

См. также

read_sql

Чтение DataFrame из таблицы.

Примечания

Столбцы datetime со временем часового пояса будут записаны как Timestamp with timezone тип с SQLAlchemy, если это поддерживается базой данных. В противном случае даты и время будут храниться как не имеющие часового пояса метки времени, локальные для исходного часового пояса.

Ссылки

1

https://docs.sqlalchemy.org

2

https://www.python.org/dev/peps/pep-0249/

Примеры

Создание временной базы данных SQLite.

>>> from sqlalchemy import create_engine
>>> engine = create_engine('sqlite://', echo=False)

Создание таблицы с нуля с 3 строками.

>>> df = pd.DataFrame({'name' : ['User 1', 'User 2', 'User 3']})
>>> df
     name
0  User 1
1  User 2
2  User 3

>>> df.to_sql('users', con=engine)
3
>>> engine.execute("SELECT * FROM users").fetchall()
[(0, 'User 1'), (1, 'User 2'), (2, 'User 3')]

Также можно передать sqlalchemy.engine.Connection в con:

>>> with engine.begin() as connection:
...     df1 = pd.DataFrame({'name' : ['User 4', 'User 5']})
...     df1.to_sql('users', con=connection, if_exists='append')
2

Это разрешено для поддержки операций, требующих использования одного и того же соединения DBAPI для всей операции.

>>> df2 = pd.DataFrame({'name' : ['User 6', 'User 7']})
>>> df2.to_sql('users', con=engine, if_exists='append')
2
>>> engine.execute("SELECT * FROM users").fetchall()
[(0, 'User 1'), (1, 'User 2'), (2, 'User 3'),
 (0, 'User 4'), (1, 'User 5'), (0, 'User 6'),
 (1, 'User 7')]

Перезаписать таблицу только с df2.

>>> df2.to_sql('users', con=engine, if_exists='replace',
...            index_label='id')
2
>>> engine.execute("SELECT * FROM users").fetchall()
[(0, 'User 6'), (1, 'User 7')]

Указать dtype (особенно полезно для целых чисел с отсутствующими значениями). Обратите внимание, что, хотя pandas вынужден хранить данные в формате с плавающей точкой, база данных поддерживает целые числа с возможностью пропуска значений. При извлечении данных с помощью Python мы получаем целочисленные скаляры.

>>> df = pd.DataFrame({"A": [1, None, 2]})
>>> df
     A
0  1.0
1  NaN
2  2.0

>>> from sqlalchemy.types import Integer
>>> df.to_sql('integers', con=engine, index=False,
...           dtype={"A": Integer()})
3

>>> engine.execute("SELECT * FROM integers").fetchall()
[(1,), (None,), (2,)]