GenerateTableFetch 프로세서

Openflow의 GenerateTableFetch 프로세서는 테이블에서 행 "페이지"를 가져오는 SQL SELECT 쿼리를 생성해주는 프로세서예요. 파티션 크기와 테이블의 행 수에 따라 페이지의 크기와 개수, 생성되는 FlowFile 수가 결정돼요.

출처: Snowflake 문서

본문

번들 (Bundle)

org.apache.nifi | nifi-standard-nar

설명 (Description)

테이블에서 행 "페이지"를 가져오는 SQL select 쿼리를 생성해요. partition size 속성과 테이블의 행 수가 페이지의 크기와 개수, 그리고 생성되는 FlowFile 수를 결정해요. 또한 Maximum-Value Columns를 설정하면 증분 가져오기(incremental fetching)를 할 수 있는데, 프로세서가 컬럼의 최댓값을 추적해 관측된 최댓값을 초과하는 행만 가져와요. 이 프로세서는 Primary Node에서만 실행되도록 설계되었어요. 이 프로세서는 들어오는 연결을 받을 수 있으며, 들어오는 연결이 있는지에 따라 동작이 달라져요:

들어오는 연결이 지정되지 않은 경우, 프로세서는 지정된 프로세서 스케줄에 따라 SQL 쿼리를 생성해요. 많은 필드에 Expression Language가 지원되지만 FlowFile 속성은 사용할 수 없어요. 대신 속성은 Environment/System 속성을 사용해 평가돼요.
들어오는 연결이 지정되었지만 프로세서 태스크에 사용 가능한 FlowFile이 없으면 아무 작업도 수행하지 않아요.
들어오는 연결이 지정되고 프로세서 태스크에 FlowFile이 사용 가능하면, FlowFile의 속성을 Table Name 같은 필드의 Expression Language에 사용할 수 있어요. 단, Max-Value Columns와 Columns to Return 필드는 비어 있거나 각 지정된 테이블에서 사용 가능한 컬럼을 가리켜야 해요.

태그 (Tags)

database, fetch, generate, jdbc, query, select, sql

입력 요구 사항 (Input Requirement)

허용 (ALLOWED)

민감 동적 속성 지원 (Supports Sensitive Dynamic Properties)

아니요 (false)

속성 (Properties)

속성	설명
Columns to Return	쿼리에 사용할 컬럼 이름의 쉼표로 구분된 목록이에요. 데이터베이스가 이름에 특별한 처리를 요구하면(예: 따옴표) 각 이름에 그 처리를 포함해야 해요. 컬럼 이름을 제공하지 않으면 지정된 테이블의 모든 컬럼이 반환돼요. 참고: 증분 가져오기가 제대로 동작하려면 주어진 테이블에 일관된 컬럼 이름을 사용하는 것이 중요해요.
Database Connection Pooling Service	데이터베이스 연결을 얻는 데 사용하는 컨트롤러 서비스예요.
Database Dialect Service	특정 서비스나 벤더에 맞는 문을 생성하는 Database Dialect 서비스예요.
Max Wait Time	실행 중인 SQL select 쿼리에 허용되는 최대 시간으로, 0이면 제한이 없음을 의미해요. 1초 미만의 최대 시간은 0과 같아요.
Maximum-value Columns	컬럼 이름들의 쉼표로 구분된 목록이에요. 프로세서는 실행을 시작한 이후 반환된 각 컬럼의 최댓값을 추적해요. 여러 컬럼을 사용하면 컬럼 목록에 순서가 생기며, 각 컬럼의 값은 이전 컬럼 값보다 더 느리게 증가할 것으로 예상돼요. 따라서 여러 컬럼을 사용하면 보통 테이블 파티셔닝에 쓰이는 컬럼의 계층 구조를 의미해요. 이 프로세서는 마지막 검색 이후 추가/갱신된 행만 가져오는 데 사용할 수 있어요. bit/boolean 같은 일부 JDBC 타입은 최댓값 유지에 적합하지 않으므로 이런 타입의 컬럼은 이 속성에 나열하면 안 되며, 처리 중 오류가 발생할 수 있어요. 컬럼을 제공하지 않으면 테이블의 모든 행이 고려되어 성능에 영향을 줄 수 있어요. 참고: 증분 가져오기가 제대로 동작하려면 주어진 테이블에 일관된 max-value 컬럼 이름을 사용하는 것이 중요해요.
Table Name	쿼리할 데이터베이스 테이블의 이름이에요.
db-fetch-db-type	특정 서비스나 벤더에 맞는 문을 생성하는 Database Type이에요. Generic Type이 대부분의 경우를 지원하지만 특정 타입을 선택하면 최적 처리가 가능하거나 추가 기능을 제공받을 수 있어요.
db-fetch-where-clause	SQL 쿼리를 만들 때 WHERE 조건에 추가할 사용자 정의 절이에요.
gen-table-column-for-val-partitioning	파티셔닝에 사용할 값이 담긴 컬럼의 이름이에요. 기본 동작은 offset/limit 전략으로 결과 집합의 행 번호를 사용해 데이터베이스에서 가져올 '페이지'로 파티셔닝하는 것이에요. 하지만 특정 데이터베이스에서는 상황에 따라 컬럼 값 자체로 '페이지'를 정의하는 것이 더 효율적일 수 있어요. 이 속성은 기본 쿼리가 잘 수행되지 않거나, max-value 컬럼이 없거나 long 정수로 강제 변환할 수 있는 max-value 컬럼이 하나뿐이며(date나 timestamp가 아닌), 컬럼 값이 고르게 분포되어 드물지 않은 경우에만 사용해야 최상의 성능을 얻을 수 있어요.
gen-table-custom-orderby-column	Max-Value Columns가 제공되지 않고 파티셔닝이 활성화된 경우 결과를 정렬하는 데 사용할 컬럼의 이름이에요. 이 속성은 Max-Value Columns가 설정되었거나 Partition Size = 0이면 무시돼요. 참고: Max-Value Columns와 Custom ORDER BY Column이 모두 설정되지 않으면 데이터베이스/드라이버에 따라 프로세서가 오류를 보고하거나 생성된 SQL이 누락·중복 행을 만들 수 있어요. 명시적 정렬이 없으면 각 파티션을 임의의 순서로 가져오기 때문이에요.
gen-table-fetch-partition-size	각 생성된 SQL 문으로 가져올 결과 행 수예요. 테이블의 총 행 수를 파티션 크기로 나누면 생성되는 SQL 문(즉 FlowFile) 수가 돼요. 값이 0이면 SQL 문이 테이블의 모든 행을 가져올 단일 FlowFile을 생성한다는 뜻이에요.
gen-table-output-flowfile-on-zero-results	지정된 속성에 따라 이 프로세서 실행 시 SQL 문이 생성되지 않을 수 있어요. 이 속성이 true면 빈 FlowFile(들어오는 FlowFile의 부모가 있으면 그 부모를 가짐)이 생성되어 'success' 관계로 전달돼요. 이 속성이 false면 출력 FlowFile이 생성되지 않아요.

상태 관리 (State management)

범위	설명
CLUSTER	지정된 테이블에 대해 쿼리를 수행한 뒤, 지정된 컬럼의 최댓값이 이후 쿼리 실행에 사용되도록 보존돼요. 이렇게 하면 프로세서가 보존된 값보다 큰 최댓값을 가진 레코드만 가져올 수 있어요. 증분 가져오기, 새로 추가된 행 가져오기 등에 사용할 수 있어요. 최댓값을 지우려면 State Management 문서에 따라 프로세서 상태를 지우면 돼요.

범위

설명

CLUSTER

지정된 테이블에 대해 쿼리를 수행한 뒤, 지정된 컬럼의 최댓값이 이후 쿼리 실행에 사용되도록 보존돼요. 이렇게 하면 프로세서가 보존된 값보다 큰 최댓값을 가진 레코드만 가져올 수 있어요. 증분 가져오기, 새로 추가된 행 가져오기 등에 사용할 수 있어요. 최댓값을 지우려면 State Management 문서에 따라 프로세서 상태를 지우면 돼요.

관계 (Relationships)

이름	설명
failure	이 관계는 들어오는 FlowFile을 사용한 SQL 쿼리 실행이 실패한 경우에만 사용돼요. 들어오는 FlowFile은 패널티를 받고 이 관계로 보내져요. 들어오는 연결이 지정되지 않으면 이 관계는 사용되지 않아요.
success	SQL 쿼리 결과 집합에서 성공적으로 생성된 FlowFile이 보내져요.

쓰기 속성 (Writes attributes)

이름	설명
generatetablefetch.sql.error	들어오는 연결이 있고 들어오는 FlowFile을 처리할 때 SQL 예외가 발생하면 FlowFile이 failure로 보내지고 이 속성이 예외 메시지로 설정돼요.
generatetablefetch.tableName	쿼리할 데이터베이스 테이블의 이름이에요.
generatetablefetch.columnNames	쿼리에 사용된 컬럼 이름들의 쉼표로 구분된 목록이에요.
generatetablefetch.whereClause	원하는 행을 얻기 위해 쿼리에 사용된 where 절이에요.
generatetablefetch.maxColumnNames	프로세서 실행 시작 이후 반환된 데이터를 추적하는 데 사용되는 컬럼 이름들의 쉼표로 구분된 목록이에요.
generatetablefetch.limit	SQL 문으로 가져올 결과 행 수예요.
generatetablefetch.offset	해당 파티션을 검색하는 데 사용할 offset이에요.
fragment.identifier	같은 쿼리 결과 집합에서 생성된 모든 FlowFile은 fragment.identifier 속성 값이 같아요. 이를 사용해 결과를 연관시킬 수 있어요.
fragment.count	단일 ResultSet에서 생성된 FlowFile의 총 개수예요. fragment.identifier 속성과 함께 사용해 같은 들어오는 ResultSet에 속한 FlowFile 수를 알 수 있어요.
fragment.index	같은 실행에서 생성된 나가는 FlowFile 목록에서 이 FlowFile의 위치예요. fragment.identifier 속성과 함께 사용해 어떤 FlowFile이 같은 실행에서 나왔는지, FlowFile이 어떤 순서로 생성되었는지 알 수 있어요.

GenerateTableFetch 프로세서