polars.read_database

polars.read_database(
    query: str | TextClause | Selectable,
    connection: ConnectionOrCursor | str,
    *,
    iter_batches: bool = False,
    batch_size: int | None = None,
    schema_overrides: SchemaDict | None = None,
    infer_schema_length: int | None = 100,
    execute_options: dict[str,
    Any] | None = None,
) → DataFrame | Iterator[DataFrame]

Считывает результаты SQL-запроса в DataFrame, используя объект подключения.

Параметры:

query

SQL-запрос для выполнения (при использовании объекта подключения SQLAlchemy это может быть подходящий объект «Selectable», в противном случае ожидается строка).

connection

Созданное подключение (или объект курсора/клиента), через которое можно выполнить запрос. Также можно передать допустимую строку подключения ODBC (определяется по наличию в ней строки «Driver={…}»); в этом случае для установки подключения и возврата данных в формате Arrow, пригодном для Polars, будет использоваться пакет arrow-odbc. Подключения асинхронных драйверов также поддерживаются, хотя сейчас эта возможность считается нестабильной. При использовании SQLAlchemy перед передачей в read_database можно настроить execution_options подключения, чтобы изменить его поведение (пример полезного применения приведён для параметра iter_batches).

Предупреждение

Использование асинхронных подключений сейчас считается нестабильным, поэтому могут возникнуть непредвиденные проблемы; если это произойдёт, сообщите о них.

iter_batches

Возвращает итератор DataFrame, где каждый DataFrame представляет собой пакет данных, полученный в результате запроса; это может быть полезно для более эффективной с точки зрения памяти обработки больших наборов результатов. Если серверная часть поддерживает эту возможность, значение передаётся базовому методу выполнения запроса (обратите внимание: меньшие значения обычно снижают производительность, поскольку приводят к большому количеству обращений к базе данных). Если серверная часть не поддерживает изменение размера пакета, итератор возвращает один DataFrame.

Примечание

При использовании SQLAlchemy для подключения может также потребоваться передать stream_results=True в метод execution_options при задании этого параметра — это создаст курсор на стороне сервера. Без этого параметра некоторые драйверы (например, «psycopg2») всё равно будут материализовывать весь набор результатов на стороне клиента, прежде чем локально разбить его на пакеты.

batch_size

Задаёт размер каждого пакета, если iter_batches имеет значение True (обратите внимание: этот параметр можно задать и при значении False для iter_batches. В таком случае результирующий DataFrame будет создан внутри функции с использованием пакетного возврата данных, прежде чем его вернут вам). Некоторые серверные части (например, Snowflake) могут поддерживать пакетную обработку, но не позволять задавать размер пакета явно; в этом случае вы всё равно получите пакеты, однако их размер будет определяться серверной частью (любое заданное здесь значение будет проигнорировано).

schema_overrides

Словарь, сопоставляющий названия столбцов с типами данных; используется для переопределения схемы, выведенной из курсора запроса или заданной входящими данными Arrow (в зависимости от драйвера/серверной части). Это может быть полезно, если указанные типы можно определить точнее (например, если известно, что для данного столбца можно объявить тип u32 вместо i64).

infer_schema_length

Максимальное количество строк для анализа при выводе схемы. Если задано значение None, может быть просканирован весь набор данных (это может выполняться медленно). Этот параметр применяется только в том случае, если данные считываются как последовательность строк и для данного столбца не задан параметр schema_overrides; драйверы, поддерживающие Arrow, также игнорируют это значение.

execute_options

Эти параметры будут переданы в базовый метод выполнения запроса в виде kwargs. Для подключений, созданных с использованием строки ODBC (где используется arrow-odbc), эти параметры передаются методу read_arrow_batches_from_odbc.

См. также

read_database_uri

Создаёт DataFrame из SQL-запроса с использованием URI-строки.

Примечания

• Эта функция поддерживает широкий спектр нативных драйверов баз данных (от локальных баз данных, таких как SQLite, до крупных облачных баз данных, таких как Snowflake), а также универсальные библиотеки, например ADBC, SQLAlchemy и различные варианты ODBC. Если серверная часть поддерживает прямой возврат данных Arrow, для эффективного создания DataFrame будет использоваться эта возможность; в противном случае DataFrame будет инициализирован построчными данными.
• Поддержка данных Arrow Flight SQL доступна через пакет adbc-driver-flightsql; дополнительные сведения об использовании этого драйвера см. на странице https://arrow.apache.org/adbc/current/driver/flight_sql.html (среди известных баз данных, реализующих Flight SQL, — Dremio и InfluxDB).
• Функция read_database_uri может быть заметно быстрее, чем read_database (которая напрямую поддерживает подключения SQLAlchemy и DBAPI2), поскольку движки connectorx и adbc, используемые в read_database_uri, оптимизируют преобразование набора результатов в формат Arrow. Чтобы использовать read_database_uri, необходимо передать строку URI, которую можно получить из объекта движка SQLAlchemy, вызвав conn.engine.url.render_as_string(hide_password=False).
• Если для выполнения запроса Polars потребуется создать курсор из вашего подключения, этот курсор будет автоматически закрыт после завершения запроса; однако Polars никогда не закроет другие открытые подключения или курсоры.
• Эта функция позволяет Polars работать не только с реляционными базами данных и SQL-запросами. Например, можно загрузить результаты локальной графовой базы данных через подключение KùzuDB вместе с запросом Cypher или использовать SurrealQL с SurrealDB.

Примеры

Создание DataFrame на основе SQL-запроса к предоставленному пользователем подключению:

>>> df = pl.read_database(
...     query="SELECT * FROM test_data",
...     connection=user_conn,
...     schema_overrides={"normalised_score": pl.UInt8},
... )  

Использование параметризованного запроса SQLAlchemy с передачей именованных значений через execute_options:

>>> df = pl.read_database(
...     query="SELECT * FROM test_data WHERE metric > :value",
...     connection=alchemy_conn,
...     execute_options={"parameters": {"value": 0}},
... )  

Использование параметризации в стиле «qmark»: значения по-прежнему передаются через execute_options, но в этом случае значение «parameters» представляет собой последовательность литералов, а не словарь:

>>> df = pl.read_database(
...     query="SELECT * FROM test_data WHERE metric > ?",
...     connection=alchemy_conn,
...     execute_options={"parameters": [0]},
... )  

Разбиение результатов большого запроса SQLAlchemy на пакеты DataFrame по 100 000 строк; явное создание курсора на стороне сервера с помощью метода «execution_options» подключения позволяет избежать загрузки всего набора результатов локально до разбиения на пакеты (это требуется не для всех драйверов, поэтому дополнительные сведения см. в документации к своему драйверу):

>>> for df in pl.read_database(
...     query="SELECT * FROM test_data",
...     connection=alchemy_conn.execution_options(stream_results=True),
...     iter_batches=True,
...     batch_size=100_000,
... ):
...     do_something(df)  

Создание DataFrame с использованием строки подключения ODBC (требуется пакет arrow-odbc) с заданием верхних пределов размера буфера для текстовых/двоичных столбцов переменной длины:

>>> df = pl.read_database(
...     query="SELECT * FROM test_data",
...     connection="Driver={PostgreSQL};Server=localhost;Port=5432;Database=test;Uid=usr;Pwd=",
...     execute_options={"max_text_size": 512, "max_binary_size": 1024},
... )  

Загрузка данных с помощью асинхронного драйвера/движка SQLAlchemy; обратите внимание, что здесь также поддерживаются асинхронные подключения и сеансы:

>>> from sqlalchemy.ext.asyncio import create_async_engine
>>> async_engine = create_async_engine("sqlite+aiosqlite:///test.db")
>>> df = pl.read_database(
...     query="SELECT * FROM test_data",
...     connection=async_engine,
... )  

Загрузка данных с помощью объекта клиентского подключения AsyncSurrealDB; обратите внимание, что поддерживаются протоколы «ws» и «http», а также синхронный клиент SurrealDB. Асинхронный цикл можно запустить с помощью стандартного asyncio или uvloop:

>>> import asyncio  # (or uvloop)
>>> async def surreal_query_to_frame(query: str, url: str):
...     async with AsyncSurrealDB(url) as client:
...         await client.use(namespace="test", database="test")
...         return pl.read_database(query=query, connection=client)
>>> df = asyncio.run(
...     surreal_query_to_frame(
...         query="SELECT * FROM test",
...         url="http://localhost:8000",
...     )
... )