polars.DataFrame.write_database

DataFrame.write_database(
    table_name: str,
    connection: ConnectionOrCursor | str,
    *,
    if_table_exists: DbWriteMode = 'fail',
    engine: DbWriteEngine | None = None,
    engine_options: dict[str,
    Any] | None = None,
) → int

Записать данные из Polars DataFrame в базу данных.

Добавлено в версии 0.20.26: Поддержка экземпляров объектов подключений в дополнение к строкам URI, а также новый параметр engine_options.

Параметры:

table_name

Имя таблицы в целевой базе данных SQL, включая схему, которую нужно создать или в которую нужно добавить данные. Если имя таблицы содержит специальные символы, его следует заключить в кавычки.

connection

Существующее подключение SQLAlchemy или ADBC к целевой базе данных либо строка URI, которая будет использоваться для создания такого подключения, например:

• “postgresql://user:pass@server:port/database”
• “sqlite:////path/to/database.db”

if_table_exists{‘append’, ‘replace’, ‘fail’}

Режим вставки:

• ‘replace’ создаст новую таблицу базы данных, перезаписав существующую.
• ‘append’ добавит данные в существующую таблицу.
• ‘fail’ вызовет ошибку, если таблица уже существует.

engine{‘sqlalchemy’, ‘adbc’}

Выбрать движок для записи данных фрейма; необходимо только при передаче строки URI (по умолчанию используется ‘sqlalchemy’, если значение не задано)

engine_options

Дополнительные параметры, передаваемые методу вставки, связанному с движком, указанным параметром engine.

• При значении engine равном “sqlalchemy” для вставки в настоящее время используется метод to_sql из Pandas (хотя со временем он будет заменён встроенным решением).
• При значении engine равном “adbc” для вставки используется метод adbc_ingest курсора ADBC. Обратите внимание: при передаче экземпляра объекта подключения для драйверов SQLite и Snowflake требуется PyArrow.

Возвращает:

int

Количество затронутых строк, если драйвер предоставляет эту информацию. В противном случае возвращается -1.

Примеры

Вставка данных во временную таблицу с использованием URI PostgreSQL и движка ADBC:

>>> df.write_database(
...     table_name="target_table",
...     connection="postgresql://user:pass@server:port/database",
...     engine="adbc",
...     engine_options={"temporary": True},
... )  

Вставка данных в таблицу с использованием подключения pyodbc SQLAlchemy к SQL Server, созданного с параметром “fast_executemany=True” для повышения производительности:

>>> pyodbc_uri = (
...     "mssql+pyodbc://user:pass@server:1433/test?"
...     "driver=ODBC+Driver+18+for+SQL+Server"
... )
>>> engine = create_engine(pyodbc_uri, fast_executemany=True)  
>>> df.write_database(
...     table_name="target_table",
...     connection=engine,
... )