StarRocks with OpenMetadata(Beta)

OpenMetadata는 오픈소스 데이터 카탈로그·메타데이터 관리 플랫폼으로, v1.12부터 StarRocks 전용 커넥터(BETA) 를 제공합니다. 이 문서는 온프레미스 Kubernetes 환경에서 OpenMetadata v1.12.10과 StarRocks v4.0.8(Shared-Data 모드)을 연동하여 데이터 카탈로그, 메타데이터 수집, 데이터 계보(Lineage), 쿼리 사용량(Query Usage), 프로파일링(Data Profiler)을 구성한 실제 테스트 결과를 정리한 가이드입니다.

1. 환경 정보

2. StarRocks 커넥터 개요

OpenMetadata는 MySQL 커넥터와 별도로 StarRocks에 최적화된 StarRocks 전용 커넥터(BETA) 를 제공합니다. 공식 문서의 Feature List 기준 지원 범위는 다음과 같습니다.

참고: StarRocks Connector 공식 문서

지원 기능 (공식 Feature List)

위 지원/미지원 항목은 OpenMetadata v1.12.x 공식 문서의 Feature List와 일치합니다. (Stage: BETA)

MySQL 커넥터와의 차이

결론: StarRocks 환경에서는 반드시 StarRocks 전용 커넥터를 사용해야 합니다.

3. StarRocks 커넥터 설정

3.1 사전 요구사항

OpenMetadata 연동용 사용자에게 필요한 권한입니다. 메타데이터 전체를 읽을 수 있어야 하며, Lineage를 위해 View DDL 조회 권한이 필요합니다.

-- 메타데이터 읽기 권한
GRANT SELECT ON *.* TO 'openmetadata_user'@'%';

-- View DDL 조회 권한 (Lineage용)
GRANT SHOW VIEW ON *.* TO 'openmetadata_user'@'%';

테스트 환경에서는 기존 root 계정을 사용해도 됩니다.

3.2 OpenMetadata UI에서 서비스 등록

Settings → Services → Database Services → Add New Service 순으로 진입합니다.

1. Select Connector: StarRocks 선택
2. Service Name: 예) StarRocks-OSS (등록 후 변경 불가하므로 유의)
3. Connection Details 입력

⚠️ 공식 문서 확인 사항: Database Name은 OpenMetadata 내부에서 사용할 표시 이름이며(미입력 시 default), 실제 수집 범위는 Database / Schema / Table Filter Pattern으로 제어합니다. 필터를 비워두면 시스템 스키마(information_schema, _statistics_, sys)를 제외한 전체를 스캔합니다.

입력을 완료한 뒤 Test Connection을 클릭하여 아래 5개 항목이 모두 ✅ 인지 확인하고 Save합니다.

• CheckAccess ✅
• GetSchemas ✅
• GetTables ✅
• GetViews ✅
• GetQueries ✅

4. Metadata Ingestion

서비스 등록 후 Ingestion 탭에서 메타데이터 수집을 구성합니다.

1. Add Ingestion → Metadata Ingestion
2. 주요 옵션
• Database Filter Pattern: 필요 시 include/exclude 설정
• Include Views: ✅ 활성화
• Include Tags: ✅ 활성화
• Mark Deleted Tables: ✅ 활성화
3. Schedule: Run once(테스트) 또는 Every 6 hours
4. Deploy

수집 결과, 모든 Database / Table / View / Materialized View가 카탈로그에 등록됩니다. MV는 테이블 타입으로 표시되지만 메타데이터(컬럼, 타입)는 정상 수집됩니다.

5. Lineage (데이터 계보) 상세

OpenMetadata의 Lineage 동작은 일반 VIEW와 Materialized View(MV) 에서 결과가 다릅니다. 결론부터 말하면 일반 VIEW는 자동 계보가 정상 생성되지만, StarRocks MV는 현재 자동 추출되지 않습니다.

5.1 동작하는 Lineage: 일반 VIEW

Metadata Ingestion 시 OpenMetadata는 각 View의 DDL을 SHOW CREATE VIEW로 조회하고, sqlglot 파서로 AS SELECT ... FROM 절을 분석하여 자동으로 lineage를 생성합니다.

-- StarRocks에서 View 생성
CREATE VIEW lineage_demo.v_order_summary AS
SELECT
  o.order_id, o.order_date,
  c.name AS customer_name, c.region,
  p.product_name, p.category
FROM lineage_demo.raw_orders o
JOIN lineage_demo.raw_customers c ON o.customer_id = c.customer_id
JOIN lineage_demo.raw_products p ON o.product_id = p.product_id;

Metadata Ingestion 실행 후 OpenMetadata UI에서 다음이 확인됩니다.

• raw_orders → v_order_summary
• raw_customers → v_order_summary
• raw_products → v_order_summary
• Column-level lineage도 정상 표시

5.2 동작하지 않는 Lineage: Materialized View

현상: Lineage Ingestion 실행 시 MV DDL을 감지하지만 파싱에 실패합니다.

WARNING {sqlglot:parser:1957} - 'CREATE MATERIALIZED VIEW `mv_session_summary`
(`session_id`, `customer_id`, ...) contains unsupported syntax.
Falling back to parsing as a 'Command'.

WARNING {sqlglot:parser:1957} - 'CREATE MATERIALIZED VIEW mv_executive_kpi
DISTRIBUTED BY HASH(report_date) BUCKETS 4 REFRESH ASYNC P...'
contains unsupported syntax. Falling back to parsing as a 'Command'.

근본 원인: sqlglot 파서가 StarRocks MV DDL의 비표준 구문을 지원하지 않습니다.

• DISTRIBUTED BY HASH(...) BUCKETS N
• REFRESH ASYNC
• PROPERTIES(...)
• 컬럼 정의 목록 (mv_name (col1, col2, ...))

sqlglot이 이 구문을 파싱하지 못하면 Command로 fallback하고, AS SELECT ... 절까지 도달하지 못해 lineage가 추출되지 않습니다. 이 문제는 View Lineage 단계(SHOW CREATE MATERIALIZED VIEW)와 Query Log Lineage 단계(audit log의 CREATE MATERIALIZED VIEW 문) 양쪽에서 동일하게 발생합니다.

5.3 Lineage Ingestion 워크플로우 동작 분석

Lineage Ingestion은 3단계로 동작합니다.

워크플로우 자체는 에러 없이 100% 성공으로 완료되지만, MV에 대한 lineage 엣지만 생성되지 않습니다.

5.4 워크어라운드

방법 1 — 수동 등록(UI): 테이블 상세 → Lineage 탭 → Edit Lineage → 소스 테이블을 드래그하여 연결. 즉시 가능하지만 MV가 많으면 비효율적입니다.

방법 2 — OpenMetadata Lineage API: REST API(PUT /api/v1/lineage)로 프로그래밍 방식 등록. 자동화 스크립트와 조합할 수 있습니다.

방법 3 — Query Log CSV 워크플로우: audit log에서 CREATE MV 문을 추출해 CSV로 만들고 query-log-lineage source type으로 실행. 단, 동일한 sqlglot 파싱 문제로 현재는 동작하지 않습니다.

6. StarRocks Audit Log 활성화 (AuditLoader)

OpenMetadata의 Query Usage 기능과 향후 Lineage 지원을 위해 StarRocks 쿼리 로그를 DB 테이블로 적재해야 합니다.

참고: StarRocks 공식 문서 - Manage audit logs via AuditLoader

6.1 개념

StarRocks는 기본적으로 FE 로컬 파일(fe/log/fe.audit.log)에 쿼리 로그를 저장합니다. AuditLoader 플러그인은 이 파일을 읽어 HTTP PUT(Stream Load)으로 StarRocks 내부 테이블에 적재합니다.

[쿼리 실행] → [fe.audit.log 파일] → [AuditLoader 플러그인] → [Stream Load] → [starrocks_audit_tbl__]

각 FE 노드에서 독립적으로 동작하며, 자체 로컬 HTTP 포트(8030)를 사용합니다.

6.2 Audit Log 테이블 생성

스키마 설계 규칙(공식 문서 권장):

• 새 필드는 반드시 NULL 허용으로 추가
• 필드명은 변경 금지 (StarRocks 내부 AuditEvent 클래스와 이름으로 매핑)
• 필드 타입 변경은 backward compatible만 허용 (예: VARCHAR(32) → VARCHAR(64))
• 컬럼 순서는 자유롭게 변경 가능
• 테이블에 없는 AuditEvent 필드는 자동 무시됨

⚠️ 버전 차이 안내: 위 스키마는 v4.0 환경 기준입니다. 최신 공식 문서(v4.1)에는 QueriedRelations ARRAY<VARCHAR(65533)> NULL(직접 참조된 테이블·뷰 목록) 컬럼이 추가되었습니다. AuditEvent 필드는 이름으로 매핑되고 테이블에 없는 필드는 자동 무시되므로, 사용 중인 버전에 맞춰 포함/생략하면 됩니다.

partition_live_number = 30은 최근 30일 파티션만 유지(자동 만료)합니다. 동적 파티션 첫 생성까지 약 10분 소요됩니다.

6.3 AuditLoader 플러그인 다운로드 및 구성

# 다운로드 (모든 StarRocks 버전과 호환)
curl -sO https://releases.starrocks.io/resources/auditloader.zip

# 압축 해제
unzip auditloader.zip

6.4 plugin.conf 설정

6.5 설치

-- 방법 1: 로컬 파일 경로 (모든 FE 노드에 동일 경로로 배포)
INSTALL PLUGIN FROM "/path/to/auditloader.zip";

-- 방법 2: HTTP URL (모든 FE가 접근 가능한 HTTP 서버에 zip 배치)
INSTALL PLUGIN FROM "http://your-server/auditloader.zip"
PROPERTIES("md5sum" = "24488939bb076521f39870efc4025237");

⚠️ 주의: 두 경우 모두 설치 후에도 원본 zip 파일을 유지해야 합니다. 삭제하면 FE 재시작 시 플러그인 로드에 실패합니다.

6.6 설치 확인

mysql> SHOW PLUGINS\G
*************************** 1. row ***************************
       Name: __builtin_AuditLogBuilder
       Type: AUDIT
     Status: INSTALLED
*************************** 2. row ***************************
       Name: AuditLoader
       Type: AUDIT
Description: Available for versions 3.3.11+. Load audit log to starrocks ...
    Version: 5.0.0
     Status: INSTALLED

6.7 동작 확인

60초(기본 batch interval) 후 적재를 확인합니다.

6.8 Kubernetes 환경에서의 설치

K8s FE pod에는 일반적으로 unzip이 없으므로 JDK에 포함된 jar 명령을 사용합니다.

6.9 플러그인 제거 및 재설치

-- 제거
UNINSTALL PLUGIN AuditLoader;

-- 설정 수정 후 재설치
INSTALL PLUGIN FROM "/path/to/auditloader.zip";

6.10 트러블슈팅

7. Query Usage Ingestion

StarRocks 커넥터는 audit log 테이블에서 쿼리 사용량(Usage)을 수집합니다.

1. StarRocks 서비스 → Ingestion 탭 → Add Ingestion → Usage Ingestion
2. Query Log Duration: 2 (최근 2일)
3. Schedule: Every day
4. Deploy

수집 결과로 테이블별 쿼리 빈도수, 사용자별 접근 패턴, 인기 테이블 랭킹을 확인할 수 있습니다.

8. Data Profiler

1. StarRocks 서비스 → Ingestion 탭 → Add Ingestion → Profiler Ingestion
2. 옵션
• Profile Sample: 50% (큰 테이블은 샘플링)
• Thread Count: 4
3. Schedule: Every week
4. Deploy

9. 테스트용 Lineage Demo 스키마

복잡한 Lineage 시각화를 위해 4레이어 구조의 데모 DB를 생성했습니다.

일반 VIEW를 추가하여 Lineage 자동 생성을 확인했습니다.

CREATE VIEW lineage_demo.v_order_summary AS
SELECT
  o.order_id, o.order_date, o.quantity, o.unit_price,
  o.quantity * o.unit_price AS total_amount,
  c.name AS customer_name, c.region,
  p.product_name, p.category
FROM lineage_demo.raw_orders o
JOIN lineage_demo.raw_customers c ON o.customer_id = c.customer_id
JOIN lineage_demo.raw_products p ON o.product_id = p.product_id;

→ Metadata Ingestion 실행 후 View lineage 자동 생성 확인 ✅

10. 알려진 제한사항

11. 참고 링크