polars.read_database_uri

polars.read_database_uri(
    query: list[str] | str,
    uri: str,
    *,
    partition_on: str | None = None,
    partition_range: tuple[int,
    int] | None = None,
    partition_num: int | None = None,
    protocol: str | None = None,
    engine: DbReadEngine | None = None,
    schema_overrides: SchemaDict | None = None,
    execute_options: dict[str,
    Any] | None = None,
    pre_execution_query: str | list[str] | None = None,
) → DataFrame

Читает результаты SQL-запроса в DataFrame, используя URI.

Параметры:

query

Текст SQL-запроса (или запросов).

uri

Строка URI для подключения connectorx или ADBC, начинающаяся с имени драйвера серверной части, например:

• “postgresql://user:pass@server:port/database”
• “snowflake://user:pass@account/database/schema?warehouse=warehouse&role=role”

Вызывающая сторона отвечает за экранирование специальных символов в строке, которая будет передана базовому механизму «как есть» (чаще всего это необходимо, если пароль содержит специальные символы).

partition_on

Столбец, по которому следует разделить результат на части (connectorx).

partition_range

Диапазон значений столбца, используемого для разбиения на части (connectorx).

partition_num

Количество создаваемых частей (connectorx).

protocol

Директива протокола передачи, зависящая от серверной части (connectorx); дополнительные сведения см. в документации connectorx.

engine{‘connectorx’, ‘adbc’}

Выбирает механизм чтения из базы данных (по умолчанию — connectorx):

• 'connectorx' Поддерживает широкий спектр баз данных, таких как PostgreSQL, Redshift, MySQL, MariaDB, Clickhouse, Oracle, BigQuery, SQL Server и другие. Актуальный список см. в документации connectorx: https://github.com/sfu-db/connector-x#supported-sources–destinations
• 'adbc' Поддержка этого механизма пока ограничена, доступно относительно небольшое количество драйверов, большинство из которых всё ещё находятся в разработке. Актуальный список драйверов см. в документации ADBC: https://arrow.apache.org/adbc/

schema_overrides

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

execute_options

Эти параметры будут переданы в метод выполнения запроса базового механизма в виде kwargs. Обратите внимание: connectorx не поддерживает этот параметр, а ADBC на данный момент поддерживает только параметризацию позиционного стиля «qmark».

pre_execution_query

SQL-запрос или список SQL-запросов, выполняемых перед основным запросом (connectorx>=0.4.2). Можно использовать для задания конфигурации во время выполнения с помощью инструкций SET. Применимо только к источникам Postgres и MySQL. Работает только с механизмом connectorx.

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

Эта функциональность считается нестабильной. Она может быть изменена в любой момент, и такие изменения не будут считаться нарушением обратной совместимости.

См. также

read_database

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

Примечания

Для connectorx убедитесь, что у вас есть connectorx>=0.3.2. Документация доступна здесь.

Для adbc необходимо установить драйвер ADBC, соответствующий серверной части, к которой выполняется подключение, например: adbc-driver-postgresql. Для версий adbc-driver-manager < 1.7.0 также требуется pyarrow.

Если пароль содержит специальные символы, их необходимо экранировать. Обычно для этого требуется функция экранирования URL, например:

>>> from urllib.parse import quote, quote_plus
>>> quote_plus("pass word?")
'pass+word%3F'
>>> quote("pass word?")
'pass%20word%3F'

Примеры

Создание DataFrame из SQL-запроса в одном потоке:

>>> uri = "postgresql://username:password@server:port/database"
>>> query = "SELECT * FROM lineitem"
>>> pl.read_database_uri(query, uri)  

Создание DataFrame параллельно в 10 потоках с автоматическим разбиением переданного SQL-запроса по столбцу разбиения:

>>> uri = "postgresql://username:password@server:port/database"
>>> query = "SELECT * FROM lineitem"
>>> pl.read_database_uri(
...     query,
...     uri,
...     partition_on="partition_col",
...     partition_num=10,
...     engine="connectorx",
... )  

Создание DataFrame параллельно в 2 потоках с явным указанием двух SQL-запросов:

>>> uri = "postgresql://username:password@server:port/database"
>>> queries = [
...     "SELECT * FROM lineitem WHERE partition_col <= 10",
...     "SELECT * FROM lineitem WHERE partition_col > 10",
... ]
>>> pl.read_database_uri(queries, uri, engine="connectorx")  

Чтение данных из Snowflake с помощью драйвера ADBC:

>>> df = pl.read_database_uri(
...     "SELECT * FROM test_table",
...     "snowflake://user:pass@company-org/testdb/public?warehouse=test&role=myrole",
...     engine="adbc",
... )  

Передача одного параметра через execute_options в запрос с помощью драйвера ADBC:

>>> df = pl.read_database_uri(
...     "SELECT * FROM employees WHERE hourly_rate > ?",
...     "sqlite:///:memory:",
...     engine="adbc",
...     execute_options={"parameters": (30,)},
... )  

Или передача нескольких параметров:

>>> df = pl.read_database_uri(
...     "SELECT * FROM employees WHERE hourly_rate BETWEEN ? AND ?",
...     "sqlite:///:memory:",
...     engine="adbc",
...     execute_options={"parameters": (40, 20)},
... )