Перейти к основному содержимому

Настройка Oracle

  • Поддерживается: Oracle
  • Авторы: Oracle
  • Репозиторий GitHub: oracle/dbt-oracle
  • Пакет PyPI: dbt-oracle
  • Канал в Slack: #db-oracle
  • Поддерживаемая версия dbt Core: v1.2.1 и новее
  • Поддержка dbt: Not Supported
  • Минимальная версия платформы данных: Oracle 12c and higher

Установка dbt-oracle

Установите адаптер с помощью pip. До версии 1.8 установка адаптера автоматически устанавливала dbt-core и любые дополнительные зависимости. Начиная с 1.8 установка адаптера не устанавливает dbt-core автоматически. Это потому, что версии адаптеров и dbt Core были развязаны, и мы больше не хотим перезаписывать существующие установки dbt-core. Используйте следующую команду для установки:

python -m pip install dbt-core dbt-oracle

Настройка dbt-oracle

Конфигурацию, специфичную для Oracle, см. на странице настроек Oracle.

Настройка режима драйвера Python​

python-oracledb делает установку библиотек Oracle Client необязательной. Этот драйвер поддерживает 2 режима:

  1. Тонкий режим (предпочтительный): Процесс Python напрямую подключается к базе данных Oracle. В этом режиме не требуются библиотеки Oracle Client.
  2. Толстый режим: Процесс Python связывается с библиотеками Oracle Client. Некоторые расширенные функции базы данных Oracle (например, Advanced Queuing, LDAP-соединения, прокручиваемые курсоры) в настоящее время доступны через библиотеки Oracle Client.

Вы можете настроить режим драйвера, используя переменную окружения ORA_PYTHON_DRIVER_TYPE. Используйте тонкий режим, так как он значительно упрощает установку.

Режим драйвераТребуются ли библиотеки Oracle Client?Конфигурация
ТонкийНетORA_PYTHON_DRIVER_TYPE=thin
ТолстыйДаORA_PYTHON_DRIVER_TYPE=thick
Loading table...

Значение по умолчанию для ORA_PYTHON_DRIVER_TYPE — thin.

export ORA_PYTHON_DRIVER_TYPE=thin # по умолчанию

Настройка кошелька для Oracle Autonomous Database (ADB-S) в облаке​

dbt может подключаться к Oracle Autonomous Database (ADB-S) в Oracle Cloud, используя либо TLS (Transport Layer Security), либо взаимный TLS (mTLS). TLS и mTLS обеспечивают повышенную безопасность для аутентификации и шифрования. Имя пользователя и пароль базы данных по-прежнему требуются для подключений dbt, которые можно настроить, как объясняется в следующем разделе Подключение к базе данных Oracle.

С TLS dbt может подключаться к Oracle ADB без использования кошелька. Оба режима драйвера python-oracledb поддерживают TLS.

к сведению

В толстом режиме dbt может подключаться через TLS только при использовании версий библиотеки Oracle Client 19.14 (или более поздних) или 21.5 (или более поздних).

Обратитесь к документации Oracle, чтобы подключиться к экземпляру ADB с использованием аутентификации TLS и к блогу Легкие подключения без кошелька к Oracle Autonomous Databases в Python, чтобы включить TLS для вашего экземпляра Oracle ADB.

Подключение к базе данных Oracle​

Подключение к базе данных Oracle​

Определите следующие обязательные параметры в виде переменных окружения и используйте их в профиле подключения с помощью Jinja-функции env_var. При необходимости вы также можете задать их напрямую в файле profiles.yml, однако это не рекомендуется.

export DBT_ORACLE_USER=<username>
export DBT_ORACLE_PASSWORD=***
export DBT_ORACLE_SCHEMA=<username>
export DBT_ORACLE_DATABASE=example_db2022adb

Используйте следующий запрос, чтобы получить имя базы данных:

SELECT SYS_CONTEXT('userenv', 'DB_NAME') FROM DUAL

Профиль подключения Oracle для dbt можно настроить, используя любой из следующих методов:

Файл tnsnames.ora — это файл конфигурации, содержащий сетевые имена служб, сопоставленные с дескрипторами подключения. Местоположение директории файла tnsnames.ora можно указать с помощью переменной окружения TNS_ADMIN.

tnsnames.ora
db2022adb_high = (description =
                 (retry_count=20)(retry_delay=3)
                 (address=(protocol=tcps)
                 (port=1522)
                 (host=adb.example.oraclecloud.com))
                 (connect_data=(service_name=example_high.adb.oraclecloud.com))
                 (security=(ssl_server_cert_dn="CN=adb.example.oraclecloud.com,
                 OU=Oracle BMCS US,O=Oracle Corporation,L=Redwood City,ST=California,C=US")))

TNS alias db2022adb_high можно определить как переменную окружения и использовать в profiles.yml.

export DBT_ORACLE_TNS_NAME=db2022adb_high
~/.dbt/profiles.yml
dbt_test:
   target: dev
   outputs:
      dev:
         type: oracle
         user: "{{ env_var('DBT_ORACLE_USER') }}"
         pass: "{{ env_var('DBT_ORACLE_PASSWORD') }}"
         database: "{{ env_var('DBT_ORACLE_DATABASE') }}"
         tns_name: "{{ env_var('DBT_ORACLE_TNS_NAME') }}"
         schema: "{{ env_var('DBT_ORACLE_SCHEMA') }}"
         threads: 4
Примечание

Начиная с dbt-oracle==1.0.2, установка имени database в profile.yml является необязательной.

Начиная с dbt-oracle==1.8.0, ключ database в profile.yml все еще необязателен для всех, кроме одного из рабочих процессов dbt-oracle. Если database отсутствует в profile.yml, сгенерированный каталог, используемый для документации проекта, будет пустым.

С версии dbt-oracle==1.8 мы обнаруживаем, что ключ database отсутствует в profile.yml, и выдаем предупреждение о необходимости его добавления для генерации каталога. Сообщение предупреждения также показывает имя базы данных, которое ожидает dbt-oracle. Таким образом, пользователям не нужно беспокоиться о том, "какое" имя базы данных и "как" его получить.

Конфигурация кавычек​

Конфигурация кавычек по умолчанию, используемая dbt-oracle, показана ниже:

dbt_project.yaml
quoting:
  database: false
  identifier: false
  schema: false

Это рекомендуется и работает в большинстве случаев.

Ошибка приблизительного совпадения отношения​

Часто пользователи жалуются на ошибку приблизительного совпадения отношения, как показано ниже:

Ошибка компиляции в модели <model>
19:09:40    При поиске отношения dbt нашел приблизительное совпадение. Вместо того чтобы угадывать,
19:09:40    какое отношение использовать, dbt продолжит. Пожалуйста, удалите <model> или переименуйте его, чтобы он был менее двусмысленным.
  Искали: <model>

Это сообщается в нескольких каналах:

Во всех случаях решением было включение кавычек только для базы данных.

Чтобы решить эту проблему приблизительного совпадения, используйте следующую конфигурацию кавычек:

dbt_project.yaml
quoting:
  database: true

Модели Python, использующие Oracle Autonomous Database (ADB-S)​

Пользователи Oracle's Autonomous Database Serverless (ADB-S) могут запускать модели dbt-py, используя Oracle Machine Learning (OML4PY), который доступен без дополнительной настройки.

Возможности​

  • Пользовательская функция на Python выполняется в среде выполнения Python 3.12.1, запущенной в ADB-S
  • Доступ к внешним Python-пакетам, доступным в среде выполнения Python. Например, numpy, pandas, scikit_learn и т.д.
  • Интеграция с Conda 24.x для создания окружений с пользовательскими Python-пакетами
  • Доступ к сессии базы данных внутри Python-функции
  • DataFrame read API для чтения TABLES, VIEWS и произвольных SELECT-запросов в виде DataFrame
  • DataFrame write API для записи DataFrame в виде TABLES
  • Поддержка как табличной, так и инкрементальной материализации

Настройка​

Необходимые роли​

  • Пользователь должен быть не-ADMIN для выполнения функции Python
  • Пользователю должна быть предоставлена роль OML_DEVELOPER

URL облачного сервиса OML​

URL облачного сервиса OML имеет следующий формат:

https://tenant1-dbt.adb.us-sanjose-1.oraclecloudapps.com

В этом примере:

  • tenant1 — это идентификатор арендатора
  • dbt — это имя базы данных
  • us-sanjose-1 — это регион центра обработки данных
  • oraclecloudapps.com — это корневой домен

Добавьте oml_cloud_service_url в ваш существующий ~/.dbt/profiles.yml.

~/.dbt/profiles.yml
dbt_test:
   target: dev
   outputs:
      dev:
         type: oracle
         user: "{{ env_var('DBT_ORACLE_USER') }}"
         pass: "{{ env_var('DBT_ORACLE_PASSWORD') }}"
         database: "{{ env_var('DBT_ORACLE_DATABASE') }}"
         tns_name: "{{ env_var('DBT_ORACLE_TNS_NAME') }}"
         schema: "{{ env_var('DBT_ORACLE_SCHEMA') }}"
         oml_cloud_service_url: "https://tenant1-dbt.adb.us-sanjose-1.oraclecloudapps.com"

Конфигурации моделей Python​

КонфигурацияТип данныхПримеры
МатериализацияСтрокаdbt.config(materialized="incremental") или dbt.config(materialized="table")
СервисСтрокаdbt.config(service="HIGH") или dbt.config(service="MEDIUM") или dbt.config(service="LOW")
Асинхронный режимЛогическийdbt.config(async_flag=True)
Тайм-аут в секундах, используется только с асинхронным режимом (min: 1800 и max: 43200)Целое числоdbt.config(timeout=1800)
Среда CondaСтрокаdbt.config(conda_env_name="dbt_py_env")
Loading table...

В асинхронном режиме dbt-oracle запланирует задание Python, будет опрашивать статус задания и ждать его завершения. Без асинхронного режима dbt-oracle немедленно вызовет задание Python в блокирующем режиме.

Примечание

Используйте dbt.config(async_flag=True) для длительных заданий Python.

Примеры моделей Python​

Ссылка на другую модель​

Используйте dbt.ref(model_name), чтобы ссылаться на SQL или Python модель.

def model(dbt, session):
    # Должно быть либо table, либо incremental (view в настоящее время не поддерживается)
    dbt.config(materialized="table")
    # возвращает oml.core.DataFrame, ссылающийся на модель dbt
    s_df = dbt.ref("sales_cost")
    return s_df

Ссылка на источник​

Используйте dbt.source(source_schema, table_name).

def model(dbt, session):
    # Должно быть либо table, либо incremental (view в настоящее время не поддерживается)
    dbt.config(materialized="table")
    # oml.core.DataFrame, представляющий источник данных
    s_df = dbt.source("sh_database", "channels")
    return s_df

Инкрементальная материализация​

def model(dbt, session):
    # Должно быть либо table, либо incremental
    dbt.config(materialized="incremental")
    # oml.DataFrame, представляющий источник данных
    sales_cost_df = dbt.ref("sales_cost")

    if dbt.is_incremental:
        cr = session.cursor()
        result = cr.execute(f"select max(cost_timestamp) from {dbt.this.identifier}")
        max_timestamp = result.fetchone()[0]
        # фильтруем новые строки
        sales_cost_df = sales_cost_df[sales_cost_df["COST_TIMESTAMP"] > max_timestamp]

    return sales_cost_df

Конкатенация нового столбца в DataFrame​


def model(dbt, session):
    dbt.config(materialized="table")
    dbt.config(async_flag=True)
    dbt.config(timeout=1800)

    sql = f"""SELECT customer.cust_first_name,
       customer.cust_last_name,
       customer.cust_gender,
       customer.cust_marital_status,
       customer.cust_street_address,
       customer.cust_email,
       customer.cust_credit_limit,
       customer.cust_income_level
    FROM sh.customers customer, sh.countries country
    WHERE country.country_iso_code = ''US''
    AND customer.country_id = country.country_id"""

    # session.sync(query) выполнит SQL-запрос и вернет oml.core.DataFrame
    us_potential_customers = session.sync(query=sql)

    # Вычисляем произвольный аномальный балл по кредитному лимиту
    median_credit_limit = us_potential_customers["CUST_CREDIT_LIMIT"].median()
    mean_credit_limit = us_potential_customers["CUST_CREDIT_LIMIT"].mean()
    anomaly_score = (us_potential_customers["CUST_CREDIT_LIMIT"] - median_credit_limit)/(median_credit_limit - mean_credit_limit)

    # Добавляем новый столбец "CUST_CREDIT_ANOMALY_SCORE"
    us_potential_customers = us_potential_customers.concat({"CUST_CREDIT_ANOMALY_SCORE": anomaly_score.round(3)})

    # Возвращаем набор данных потенциальных клиентов как oml.core.DataFrame
    return us_potential_customers

Использование пользовательской среды Conda​

  1. В качестве пользователя ADMIN создайте среду conda, используя OML4PY Conda Notebook:
conda create -n dbt_py_env -c conda-forge --override-channels --strict-channel-priority python=3.12.1 nltk gensim
  1. Сохраните эту среду, используя следующую команду из OML4PY Conda Notebook:
conda upload --overwrite dbt_py_env -t application OML4PY
  1. Используйте среду в моделях dbt Python:
# Импортируйте пользовательские пакеты из сред Conda
import nltk
import gensim

def model(dbt, session):
    dbt.config(materialized="table")
    dbt.config(conda_env_name="dbt_py_env")  # Ссылаемся на среду conda
    dbt.config(async_flag=True) # Используем асинхронный режим для длительных заданий Python
    dbt.config(timeout=900)
    # oml.core.DataFrame, ссылающийся на модель dbt-sql
    promotion_cost = dbt.ref("direct_sales_channel_promo_cost")
    return promotion_cost

Поддерживаемые функции​

  • Табличная материализация
  • Материализация представлений
  • Материализованное представление
  • Инкрементальная материализация
  • Seeds
  • Источники данных
  • Единичные тесты
  • Общие тесты; Не null, Уникальные, Допустимые значения и Отношения
  • Операции
  • Анализы
  • Экспозиции
  • Генерация документации
  • Публикация документации проекта в виде веб-сайта
  • Модели Python (с версии dbt-oracle 1.5.1)
  • Интеграция с Conda для использования любых пакетов Python из репозитория Anaconda
  • Поддерживаются все команды dbt

Неподдерживаемые функции​

  • Эфемерная материализация

Нашли ошибку?

0
Loading