Выполнение запросов в Oracle

Warning

Методы, описанные ниже, считывают все строки из БД в память драйвера Spark, а затем преобразуют их в DataFrame.

НЕ используйте их для чтения больших объемов данных. Вместо этого используйте DBReader или Oracle.sql.

Как использовать

Существует 2 способа выполнения запросов в Oracle

Использование Oracle.fetch

Используйте этот метод для выполнения запроса SELECT, который возвращает небольшое количество строк, например, для чтения конфигурации Oracle или данных из справочной таблицы. Метод возвращает Spark DataFrame.

Метод принимает параметры Oracle.FetchOptions.

Соединение, открытое с помощью этого метода, следует затем закрыть с помощью connection.close() или конструкции with connection:.

Warning

Пожалуйста, учитывайте типы данных Oracle.

Поддержка синтаксиса в Oracle.fetch

Этот метод позволяет использовать любой синтаксис запросов, поддерживаемый Oracle, например:

• ✅︎ SELECT ... FROM ...
• ✅︎ WITH alias AS (...) SELECT ...
• ✅︎ SELECT func(arg1, arg2) FROM DUAL - вызов функции
• ✅︎ SHOW ...
• ❌ SET ...; SELECT ...; - множественные операторы не поддерживаются

Примеры с Oracle.fetch

```python
    from onetl.connection import Oracle

    oracle = Oracle(...)

    df = oracle.fetch(
        "SELECT value FROM some.reference_table WHERE key = 'some_constant'",
        options=Oracle.FetchOptions(queryTimeout=10),
    )
    oracle.close()
    value = df.collect()[0][0]  # получение значения из первой строки и первого столбца
```

Использование Oracle.execute

Используйте этот метод для выполнения операций DDL и DML. Каждый вызов метода выполняет операцию в отдельной транзакции, а затем фиксирует её.

Метод принимает параметры Oracle.ExecuteOptions.

Соединение, открытое с помощью этого метода, следует затем закрыть с помощью connection.close() или конструкции with connection:.

Поддержка синтаксиса в Oracle.execute

Этот метод поддерживает любой синтаксис запросов, применимый в Oracle, например:

• ✅︎ CREATE TABLE ..., CREATE VIEW ...
• ✅︎ ALTER ...
• ✅︎ INSERT INTO ... SELECT ..., UPDATE ..., DELETE ... и так далее
• ✅︎ DROP TABLE ..., DROP VIEW ..., TRUNCATE TABLE и так далее
• ✅︎ CALL procedure(arg1, arg2) ... или {call procedure(arg1, arg2)} - специальный синтаксис для вызова процедуры
• ✅︎ DECLARE ... BEGIN ... END - выполнение PL/SQL выражения
• ✅︎ другие операторы, не упомянутые здесь
• ❌ SET ...; SELECT ...; - множественные операторы не поддерживаются

Примеры с Oracle.execute

```python
    from onetl.connection import Oracle

    oracle = Oracle(...)

    oracle.execute("DROP TABLE schema.table")
    oracle.execute(
        """
        CREATE TABLE schema.table (
            id bigint GENERATED ALWAYS AS IDENTITY,
            key VARCHAR2(4000),
            value NUMBER
        )
        """,
        options=Oracle.ExecuteOptions(queryTimeout=10),
    )
```

Опции

onetl.connection.db_connection.oracle.options.OracleFetchOptions

Bases: JDBCFetchOptions

Source code in onetl/connection/db_connection/oracle/options.py

class OracleFetchOptions(JDBCFetchOptions):
    __doc__ = JDBCFetchOptions.__doc__.replace("SomeDB", "Oracle")  # type: ignore[assignment, union-attr]

fetchsize = None class-attribute instance-attribute

How many rows to fetch per round trip.

Tuning this option can influence performance of reading.

.. warning:: Default value depends on driver. For example, Oracle has default fetchsize=10.

query_timeout = Field(default=None, alias='queryTimeout') class-attribute instance-attribute

The number of seconds the driver will wait for a statement to execute. Zero means there is no limit.

This option depends on driver implementation, some drivers can check the timeout of each query instead of an entire JDBC batch.

parse(options) classmethod

If a parameter inherited from the ReadOptions class was passed, then it will be returned unchanged. If a Dict object was passed it will be converted to ReadOptions.

Otherwise, an exception will be raised

Source code in onetl/impl/generic_options.py

@classmethod
def parse(
    cls: type[T],
    options: GenericOptions | dict | None,
) -> T:
    """
    If a parameter inherited from the ReadOptions class was passed, then it will be returned unchanged.
    If a Dict object was passed it will be converted to ReadOptions.

    Otherwise, an exception will be raised
    """

    if not options:
        return cls()

    if isinstance(options, dict):
        return cls.parse_obj(options)

    if not isinstance(options, cls):
        raise TypeError(
            f"{options.__class__.__name__} is not a {cls.__name__} instance",
        )

    return options

onetl.connection.db_connection.oracle.options.OracleExecuteOptions

Bases: JDBCExecuteOptions

Source code in onetl/connection/db_connection/oracle/options.py

class OracleExecuteOptions(JDBCExecuteOptions):
    __doc__ = JDBCExecuteOptions.__doc__.replace("SomeDB", "Oracle")  # type: ignore[assignment, union-attr]

fetchsize = None class-attribute instance-attribute

How many rows to fetch per round trip.

Tuning this option can influence performance of reading.

.. warning:: Default value depends on driver. For example, Oracle has default fetchsize=10.

query_timeout = Field(default=None, alias='queryTimeout') class-attribute instance-attribute

The number of seconds the driver will wait for a statement to execute. Zero means there is no limit.

This option depends on driver implementation, some drivers can check the timeout of each query instead of an entire JDBC batch.

parse(options) classmethod

If a parameter inherited from the ReadOptions class was passed, then it will be returned unchanged. If a Dict object was passed it will be converted to ReadOptions.

Otherwise, an exception will be raised

Source code in onetl/impl/generic_options.py

@classmethod
def parse(
    cls: type[T],
    options: GenericOptions | dict | None,
) -> T:
    """
    If a parameter inherited from the ReadOptions class was passed, then it will be returned unchanged.
    If a Dict object was passed it will be converted to ReadOptions.

    Otherwise, an exception will be raised
    """

    if not options:
        return cls()

    if isinstance(options, dict):
        return cls.parse_obj(options)

    if not isinstance(options, cls):
        raise TypeError(
            f"{options.__class__.__name__} is not a {cls.__name__} instance",
        )

    return options