Starburst/Trino configurations

Starburst/Trino configurations

dbt-trino 어댑터에서 Starburst/Trino를 구성하는 방법을 다루는 페이지예요. 세션 속성, 파일 형식, materialization(table/view/incremental/materialized view), 스냅샷, grants 등을 설정할 수 있어요.

출처: 문서

본문

클러스터 요구 사항

지정된 클러스터에는 테이블·뷰 같은 객체를 만들고·이름 바꾸고·변경하고·삭제할 수 있는 카탈로그가 연결되어 있어야 해요. dbt로 클러스터에 연결하는 모든 사용자도 대상 카탈로그에 같은 권한이 있어야 해요.

세션 속성 (Session properties)

Starburst Enterprise, Starburst Galaxy, 또는 Trino 클러스터에서는 세션 속성을 설정해 사용자 세션의 현재 구성을 수정할 수 있어요.

세션 속성을 정의하는 표준 방법은 profiles.yml의 session_properties 필드예요. 이렇게 하면 모든 dbt 연결이 기본적으로 이 설정을 사용해요.

하지만 특정 dbt 모델이나 모델 그룹의 세션 속성을 일시적으로 조정하려면 dbt 훅으로 특정 dbt 모델의 세션 속성을 설정할 수 있어요. 예:

{{
  config(
    pre_hook="set session query_max_run_time='10m'"
  )
}}

커넥터 속성 (Connector properties)

Starburst/Trino 테이블 속성으로 데이터가 어떻게 표현될지 구성할 수 있어요.

각 지원 데이터 소스가 지원하는 내용은 Trino Connectors 또는 Starburst Catalog를 참고하세요.

Hive 카탈로그

Starburst와 dbt로 작업할 때는 Hive 커넥터와 metastore 서비스(HMS)를 사용하는 대상 카탈로그가 일반적이에요. dbt 작업에 권장되는 설정은 다음과 같아요. dbt가 자주 실행하는 DROP과 RENAME 문을 수행할 수 있도록 하기 위한 설정이에요.

hive.metastore-cache-ttl=0s
hive.metastore-refresh-interval=5s

파일 형식 구성

Hive 같은 파일 기반 커넥터를 쓸 때 사용자는 사용되는 형식과 materialization 유형 같은 커넥터 측면을 커스터마이즈할 수 있어요.

아래는 테이블을 파티셔닝된 Parquet 파일 집합으로 materialize하도록 구성해요.

{{
  config(
    materialized='table',
    properties= {
      "format": "'PARQUET'",
      "partitioning": "ARRAY['bucket(id, 2)']",
    }
  )
}}

시드와 prepared statements

dbt seed 명령은 Starburst/Trino에서 prepared statements를 사용해요.

Prepared statements는 효율적으로 반복 실행할 수 있는 템플릿 SQL 문이에요. 값은 SQL 문자열에 하드코딩되는 대신 별도의 필드로 전송돼요. 애플리케이션 프론트엔드가 OLTP 데이터베이스 백엔드에서 레코드 INSERT 문을 구성하는 방식과 비슷해요. 그래서 prepared statements는 대상 테이블의 컬럼 수만큼 플레이스홀더 변수(파라미터)를 갖는 게 흔해요.

대부분의 시드 파일은 여러 행, 많게는 수천 행을 가져요. 그래서 클라이언트 요청 크기가 파라미터 수만큼 커져요.

Python HTTP 클라이언트의 헤더 줄 길이 제한

prepared statements에 파라미터가 너무 많으면 헤더 줄 제한에 대한 오류 메시지를 만날 수 있어요. Python HTTP 클라이언트의 헤더 줄 제한이 65536 바이트이기 때문이에요.

이 상한을 피하려면 큰 prepared statement를 더 작은 문으로 나누면 돼요. dbt는 이미 전체 시드 파일을 행 그룹으로 일괄 처리해서 이걸 해요 — CSV의 일부 행이 한 그룹이죠.

예를 들어 20개 컬럼, 600개 행, 12,000개 파라미터가 있는 시드 파일이 있다고 해 볼게요. 이걸 위한 단일 prepared statement를 만드는 대신, dbt가 150개 행과 3,000개 파라미터를 가진 prepared INSERT 문 네 개를 만들게 할 수 있어요.

테이블 행을 그룹으로 묶으면 단점이 있어요. 시드 파일에 컬럼(파라미터)이 많으면 배치 크기가 매우 작아야 해요.

dbt-trino 어댑터의 배치 크기 매크로는 trino__get_batch_size()이고 기본값은 1000이에요. 기본 동작을 바꾸려면 dbt 프로젝트에 이 매크로를 추가하세요.

macros/YOUR_MACRO_NAME.sql

{% macro trino__get_batch_size() %}
  {{ return(10000) }} -- Adjust this number as you see fit
{% endmacro %}

헤더 줄 길이 제한을 피하는 또 다른 방법은 dbt 프로필에서 prepared_statements_enabled를 true로 설정하는 거예요. 다만 이것은 레거시 동작으로 간주되며 향후 릴리스에서 제거될 수 있어요.

Materializations

Table

dbt-trino 어댑터는 on_table_exists로 구성할 수 있는 table materialization(그리고 incremental materialization의 full-refresh 실행)에서 다음 모드를 지원해요.

• rename — 중간 테이블을 만들고, 대상 테이블을 백업 테이블로 이름 바꾸고, 중간 테이블을 대상 테이블로 이름 바꿔요.
• drop — 테이블을 드롭하고 재생성해요. AWS Glue의 테이블 rename 제한을 극복해요.
• replace — CREATE OR REPLACE 절로 테이블을 교체해요. 테이블 교체 지원은 커넥터마다 달라요. 자세한 내용은 커넥터 문서를 참고하세요.
• skip — CREATE TABLE IF NOT EXISTS 절로 테이블 materialization을 완전히 건너뛰어요.

기본 커넥터가 CREATE OR REPLACE를 지원하면 replace가 권장 옵션이에요. 그렇지 않으면 권장 table materialization은 on_table_exists = 'rename'을 사용하는데, 이것이 기본값이기도 해요. 이 기본 구성을 바꾸려면 다음 중 하나의 파일을 수정하세요.

• 모델의 SQL 파일
• dbt_project.yml 구성 파일

다음 예시들은 table materialization을 drop으로 구성해요.

models/YOUR_MODEL_NAME.sql

{{
  config(
    materialized = 'table',
    on_table_exists = 'drop`
  )
}}

dbt_project.yml

models:
  path:
    materialized: table
    +on_table_exists: drop

table materialization과 on_table_exists = 'rename'을 AWS Glue와 함께 쓰면 다음 오류를 만날 수 있어요. drop으로 테이블 rename 제한을 극복할 수 있어요.

TrinoUserError(type=USER_ERROR, name=NOT_SUPPORTED, message="Table rename is not yet supported by Glue service")

View

dbt-trino 어댑터는 view_security로 구성할 수 있는 view materialization에서 다음 보안 모드를 지원해요.

• definer
• invoker

뷰의 보안 모드에 대한 자세한 내용은 Trino docs의 Security를 참고하세요.

기본적으로 view materialization은 view_security = 'definer'를 사용해요. 이 기본 구성을 바꾸려면 다음 중 하나의 파일을 수정하세요.

• 모델의 SQL 파일
• dbt_project.yml 구성 파일

예를 들어 보안 모드를 invoker로 구성하면:

models/YOUR_MODEL_NAME.sql

{{
  config(
    materialized = 'view',
    view_security = 'invoker'
  )
}}

dbt_project.yml

models:
  path:
    materialized: view
    +view_security: invoker

Incremental

Incremental 모델을 쓰면 변환해야 하는 데이터 양이 제한되어 변환 실행 시간이 크게 줄어들어요. 이는 성능을 향상시키고 컴퓨팅 비용을 낮춰요.

{{
    config(
      materialized = 'incremental',
      unique_key='<optional>',
      incremental_strategy='<optional>',)
}}
select * from {{ ref('events') }}
{% if is_incremental() %}
  where event_ts > (select max(event_ts) from {{ this }})
{% endif %}

+on_schema_change 속성으로 dbt-trino가 컬럼 변경을 처리하는 방법을 정의하세요. 이 속성에 대한 자세한 내용은 column changes를 참고하세요.

커넥터가 뷰를 지원하지 않으면 +views_enabled 속성을 false로 설정하세요.

full-refresh 실행에서 모델을 어떻게 다시 빌드할지 on_table_exists config로 결정할 수 있어요. 옵션은 table materialization 섹션에서 설명한 것과 같아요.

append 전략

기본 incremental 전략은 append예요. append는 is_incremental() 조건 블록에 지정된 조건을 기반으로 새 레코드만 추가해요.

{{
    config(
      materialized = 'incremental')
}}
select * from {{ ref('events') }}
{% if is_incremental() %}
  where event_ts > (select max(event_ts) from {{ this }})
{% endif %}

delete+insert 전략

delete+insert incremental 전략으로 dbt에 두 단계 incremental 접근을 사용하라고 지시할 수 있어요. 먼저 설정된 is_incremental() 블록을 통해 감지된 레코드를 삭제하고, 다시 삽입해요.

{{
    config(
      materialized = 'incremental',
      unique_key='user_id',
      incremental_strategy='delete+insert',
      )
}}
select * from {{ ref('users') }}
{% if is_incremental() %}
  where updated_ts > (select max(updated_ts) from {{ this }})
{% endif %}

merge 전략

merge incremental 전략으로 dbt-trino는 unique_key 속성을 기반으로 새 레코드를 insert하고 기존 레코드를 update하는 Trino MERGE 문을 구성해요.

unique_key가 고유하지 않으면 대신 delete+insert 전략을 쓸 수 있어요.

{{
    config(
      materialized = 'incremental',
      unique_key='user_id',
      incremental_strategy='merge',
      )
}}
select * from {{ ref('users') }}
{% if is_incremental() %}
  where updated_ts > (select max(updated_ts) from {{ this }})
{% endif %}

일부 Trino 커넥터는 MERGE를 지원하지 않거나 제한적으로 지원한다는 점에 유의하세요.

Hive 모델의 Incremental overwrite

대상 incremental 모델에 접근하는 Hive 커넥터가 있다면, Trino의 Hive 커넥터 구성에서 insert-existing-partitions-behavior 설정으로 INSERT OVERWRITE 문을 시뮬레이션할 수 있어요.

<hive-catalog-name>.insert-existing-partitions-behavior=OVERWRITE

아래는 minio라는 Hive 커넥터에 OVERWRITE 기능을 설정하는 Hive 구성 예시예요.

trino-incremental-hive:
  target: dev
  outputs:
    dev:
      type: trino
      method: none
      user: admin
      password:
      catalog: minio
      schema: tiny
      host: localhost
      port: 8080
      http_scheme: http
      session_properties:
        minio.insert_existing_partitions_behavior: OVERWRITE
      threads: 1

dbt-trino는 스테이징 데이터와 일치하는 대상 모델의 기존 파티션을 덮어써요. 나머지 파티션은 대상 모델에 추가해요. 이 기능은 파티셔닝을 사용하는 incremental 모델에서 동작해요. 예:

{{
    config(
        materialized = 'incremental',
        properties={
          "format": "'PARQUET'",
          "partitioned_by": "ARRAY['day']",
        }
    )
}}

Materialized view

dbt-trino 어댑터는 materialized view를 지원하고, 이후 실행하는 모든 dbt run마다 이를 새로고침해요. 자세한 내용은 Trino docs의 REFRESH MATERIALIZED VIEW를 참고하세요.

properties config를 통해 materialized view의 커스텀 속성도 정의할 수 있어요.

이 materialization은 full_refresh config와 플래그를 지원해요. materialized view를 다시 빌드하고 싶을 때마다(예: 기본 SQL 쿼리를 바꿀 때) dbt run --full-refresh를 실행하세요.

다음 중 하나의 파일을 수정해 materialized view를 만들 수 있어요.

• 모델의 SQL 파일
• dbt_project.yml 구성 파일

다음 예시들은 Parquet 형식의 materialized view를 만들어요.

models/YOUR_MODEL_NAME.sql

{{
  config(
    materialized = 'materialized_view',
    properties = {
      'format': "'PARQUET'"
    },
  )
}}

dbt_project.yml

models:
  path:
    materialized: materialized_view
    properties:
      format: "'PARQUET'"

Snapshots

dbt의 스냅샷은 기본적으로 밀리초 정밀도(3자리) 타임스탬프를 반환하는 current_timestamp 매크로에 의존해요. Iceberg처럼 이 타임스탬프 정밀도(TIMESTAMP(3) WITH TIME ZONE)를 지원하지 않는 Trino 커넥터도 있어요.

타임스탬프 정밀도를 바꾸려면 나만의 매크로를 정의할 수 있어요. 다음은 마이크로초 정밀도(6자리)를 가진 새 trino__current_timestamp() 매크로를 정의해요.

macros/YOUR_MACRO_NAME.sql

{% macro trino__current_timestamp() %}
    current_timestamp(6)
{% endmacro %}

Grants

grants로 dbt로 만드는 데이터셋에 대한 접근을 관리할 수 있어요. Starburst Enterprise, Starburst Galaxy, Hive(sql-standard)에서 grants를 쓸 수 있어요.

접근 권한을 구현하려면 각 모델, 시드, 스냅샷에 리소스 config로 grants를 정의해요. dbt_project.yml에서 프로젝트 전체에 적용되는 기본 grants를 정의하고, 각 모델의 SQL 또는 YAML 파일에서 모델별 grants를 정의해요.

dbt_project.yml

models:
  - name: NAME_OF_YOUR_MODEL
    config:
      grants:
        select: ['reporter', 'bi']

persist_docs

dbt-trino v1.10.3 이상에서 사용 가능

기본적으로 persist_docs는 COMMENT ON SQL 문을 사용해 모델과 컬럼 설명을 기본 카탈로그에 써요.

연결 프로필에서 starburst_url과 함께 starburst_client_id, starburst_secret_key를 설정하면 persist_docs를 활성화했을 때 모델과 컬럼 설명을 REST API를 통해 Starburst의 Data Discovery 카탈로그에도 동기화해요. 이는 opt-in이고 추가적이라, starburst_url을 설정하지 않은 프로젝트에는 영향이 없어요. 이 프로필 필드 구성에 대한 자세한 내용은 Starburst/Trino 설정 가이드의 Additional parameters를 참고하세요.

컬럼 설명은 배치로 Data Discovery에 동기화돼요. starburst_max_column_batch_size 파라미터가 배치 크기를 제어하며 기본값은 100이에요.

starburst_metadata_failure_strategy는 Data Discovery API의 오류를 dbt가 어떻게 처리할지 제어해요.

• continue_on_error (기본값) — 경고를 기록하고 실행을 계속해요.
• fail_fast — 실행을 중단해요.

Model contracts

dbt-trino 어댑터는 모델 contract를 지원해요. 현재 type이 not_null인 constraints만 지원돼요. 모델에서 not_null constraints를 쓰기 전에, 기본 커넥터가 not null을 지원하는지 확인해 오류를 피하세요.

더 알아보기 (Learn more)

• Starburst/Trino 설정 — 어댑터 연결.
• Incremental strategies — incremental 전략 개요.
• Grants — grants 설정.