SingleStore configurations

SingleStore configurations

dbt-singlestore 어댑터에서 모델을 구성하는 방법을 다루는 페이지예요. incremental 전략, 스토리지 타입, reference 테이블, 키, 인덱스, 문자셋 등을 설정할 수 있어요.

출처: 문서

본문

Incremental materialization strategies

incremental_strategy config는 dbt가 incremental 모델을 어떻게 빌드할지 제어해요. 현재 SingleStoreDB는 delete+insert, append, microbatch 구성을 지원해요.

delete+insert incremental 전략은 dbt가 두 단계로 incremental 접근을 하도록 안내해요. 먼저 설정된 is_incremental() 블록이 지시한 레코드를 식별해 제거하고, 그다음 이 레코드들을 다시 삽입해요.

Performance Optimizations

아래 설명된 특정 옵션을 dbt 프로젝트에서 쓰고 싶다면 SingleStore Physical Database Schema Design 문서가 도움이 돼요.

Storage type

SingleStore는 In-Memory Rowstore와 Disk-based Columnstore(기본값) 두 가지 스토리지 타입을 지원해요. 자세한 내용은 docs를 참고하세요. dbt-singlestore 어댑터는 storage_type config 파라미터로 테이블 materialization이 사용할 스토리지 타입을 지정할 수 있게 해줘요.

rowstore_model.sql

{{ config(materialized='table', storage_type='rowstore') }}

select ...

Reference tables

SingleStore는 REFERENCE 테이블을 지원해요 (dbt-singlestore 1.10.0부터). 이 테이블은 클러스터 전체에 복제되며, 자주 조인되는 작은/차원 테이블에 유용해요.

dbt 모델에서 REFERENCE 테이블을 만들려면 table materialization에 reference=true를 설정하세요.

{{
    config(
        materialized='table',
        reference=true,
    )
}}

select ...

reference=true(기본 false)일 때 어댑터는 일반 CREATE TABLE ... 대신 CREATE REFERENCE TABLE ...을 생성해요.

Rowstore reference tables

Rowstore reference 테이블을 원하면 storage_type='rowstore'를 설정하세요.

{{
    config(
        materialized='table',
        reference=true,
        storage_type='rowstore',
    )
}}

select ...

이것은 CREATE ROWSTORE REFERENCE TABLE ...에 매핑돼요.

제약 / 검증

SingleStore 의미론과 맞추기 위해 dbt-singlestore는 다음을 강제해요.

• reference=true와 함께 shard_key를 쓰지 않음 — reference 테이블은 샤딩을 사용하지 않아요. 둘 다 설정하면 컴파일이 실패해요.
• SingleStore는 임시 reference 테이블을 지원하지 않아요. reference=true가 결과적으로 임시 테이블을 만들게 되면(예: temporary=true 설정, 또는 materialization 전략이 내부적으로 임시 테이블 사용), dbt-singlestore는 컴파일을 실패시켜요.

Keys

SingleStore 테이블은 샤딩되며 다양한 컬럼 정의로 생성될 수 있어요. dbt-singlestore 어댑터는 다음 옵션을 지원하고, 각각 column_list(컬럼 이름 목록)를 옵션 값으로 받아요. SingleStore의 다양한 키 타입은 Creating a Columnstore Table을 참고하세요.

• primary_key (PRIMARY KEY (column_list)로 변환)
• sort_key (KEY (column_list) USING CLUSTERED COLUMNSTORE로 변환)
• shard_key (SHARD KEY (column_list)로 변환)
• unique_table_key (UNIQUE KEY (column_list)로 변환)

primary_and_shard_model.sql

{{
    config(
        primary_key=['id', 'user_id'],
        shard_key=['id']
    )
}}

select ...

unique_and_sort_model.sql

{{
    config(
        materialized='table',
        unique_table_key=['id'],
        sort_key=['status'],
    )
}}

select ...

Indexes

Postgres 어댑터와 비슷하게, 테이블 모델, incremental 모델, 시드, 스냅샷은 indexes 목록을 가질 수 있어요. 각 인덱스는 다음 구성 요소를 가질 수 있어요.

• columns (목록, 필수): 인덱스가 정의되는 하나 이상의 컬럼
• unique (boolean, 선택): 인덱스를 unique로 선언할지 여부
• type (string, 선택): 지원되는 인덱스 타입, hash 또는 btree

SingleStore 테이블은 샤딩되므로 인덱스 생성에 특정 제한이 있어요. 자세한 내용은 docs를 참고하세요.

indexes_model.sql

{{
    config(
        materialized='table',
        shard_key=['id'],
        indexes=[{'columns': ['order_date', 'id']}, {'columns': ['status'], 'type': 'hash'}]
    )
}}

select ...

Other options

테이블의 문자셋과 콜레이션을 charset 및/또는 collation 옵션으로 지정할 수 있어요. charset의 지원 값은 binary, utf8, utf8mb4예요. collation의 지원 값은 SHOW COLLATION SQL 쿼리의 출력으로 확인할 수 있어요. 해당 문자셋의 기본 콜레이션은 binary, utf8_general_ci, utf8mb4_general_ci예요.

utf8mb4_model.sql

{{
    config(
        charset='utf8mb4',
        collation='utf8mb4_general_ci'
    )
}}

select ...

Model contracts

1.5부터 dbt-singlestore 어댑터는 모델 contract를 지원해요.

dbt-singlestore 어댑터에서 contract를 쓸 때 다음 제약을 고려하세요.

모델 및 컬럼 정의

• unique 제약은 모델 레벨에서만 설정할 수 있어요. 그래서 컬럼 레벨에는 설정하지 마세요.
• 제약을 반복하면 오류가 나요. 예를 들어 primary_key를 컬럼과 모델 설정 양쪽에 두면 오류가 나요.

설정 덮어쓰기

contract 설정은 configuration 설정을 재정의해요. 예를 들어 config에서 primary_key나 unique_table_key를 정의하고 contract에도 설정하면, contract 설정이 configuration 설정을 대체해요.

상수(constants) 다루기

dim_customers.yml

models:
  - name: dim_customers
    config:
      materialized: table
      contract:
        enforced: true
    columns:
      - name: customer_id
        data_type: int
        constraints:
          - type: not_null
      - name: customer_name
        data_type: text

모델이 다음과 같이 정의되어 있다고 해 볼게요.

dim_customers.sql

select
  'abc123' as customer_id,
  'My Best Customer' as customer_name

상수를 쓸 때는 데이터 타입을 직접 지정해야 해요. 그렇지 않으면 SingleStoreDB가 자동으로 가장 적절하다고 생각하는 데이터 타입을 선택해요.

dim_customers.sql

select
  ('abc123' :> int) as customer_id,
  ('My Best Customer' :> text) as customer_name

오해하기 쉬운 데이터 타입

model contracts를 사용하면 컬럼에 실수로 잘못된 타입의 데이터를 넣는 일을 막을 수 있어요. 예를 들어 컬럼에 숫자가 들어오길 기대하는데 실수로 텍스트를 넣었다면 contract가 이를 잡아내고 오류를 반환해요.

singlestoredb-python 커넥터의 동작 방식 때문에 오류 메시지에 기대와 다른 데이터 타입 이름이 표시될 때도 있어요. 예를 들어:

dim_customers.sql

select
  'abc123' as customer_id,
  ('My Best Customer' :> text) as customer_name

다음과 같은 결과가 나와요.

Please ensure the name, data_type, and number of columns in your contract match the columns in your model's definition.
| column_name | definition_type | contract_type | mismatch_reason       |
| customer_id | LONGBLOB        | LONG          | data type mismatch    |

특정 데이터 타입 매핑이 오류 메시지에서 다르게 보일 수 있지만, 동작에는 영향을 주지 않는다는 점을 기억하세요. dbt-singlestore 어댑터를 설정하고 사용할 때 이 점만 기억하면 흔한 함정을 피할 수 있어요!

더 알아보기 (Learn more)

• SingleStore 설정 — 어댑터 연결.
• Incremental strategies — incremental 전략 개요.
• Model contracts — contract 강제.