PutDatabaseRecord
PutDatabaseRecord
지정한 RecordReader를 사용해 들어오는 flow file에서 레코드를 읽고, 이를 SQL 문으로 변환해 단일 트랜잭션으로 실행하는 프로세서예요.
본문
번들 (Bundle)
org.apache.nifi | nifi-standard-nar
설명
PutDatabaseRecord 프로세서는 지정한 RecordReader를 사용해 들어오는 flow file에서 (여러 개일 수 있는) 레코드를 읽어요. 이 레코드들은 SQL 문으로 변환되어 단일 트랜잭션으로 실행돼요. 오류가 발생하면 flow file은 failure 또는 retry로 라우팅되고, 레코드가 성공적으로 전송되면 들어오는 flow file은 success로 라우팅돼요. 프로세서가 실행하는 문의 유형은 Statement Type 속성으로 지정하는데, INSERT, UPDATE, DELETE 같은 하드코딩된 값과 'Use statement.type Attribute'를 받아들이며, 후자는 flow file 속성에서 문 유형을 가져오게 해요. 중요: Statement Type이 UPDATE면 들어오는 레코드는 기본 키(또는 사용자 지정 Update Keys)의 값을 변경해서는 안 돼요. 그런 레코드를 만나면 데이터베이스에 보내는 UPDATE 문이 아무것도 하지 않거나(새 기본 키 값을 가진 기존 레코드가 없으면), 또는 기존 데이터를 의도치 않게 손상시킬 수 있어요(기본 키의 새 값이 존재하는 레코드를 변경함으로써).
태그
database, delete, insert, jdbc, put, record, sql, update
입력 요구 사항 (Input Requirement)
REQUIRED — 입력 FlowFile이 필요해요.
민감한 동적 속성 지원 (Supports Sensitive Dynamic Properties)
false — 지원하지 않아요.
속성 (Properties)
| 속성 | 설명 |
|---|---|
| Column Name Translation Pattern | 이 정규식으로 열 이름을 정규화해요. |
| Column Name Translation Strategy | 테이블 열 이름을 정규화하는 전략이에요. 전략과 무관하게 대소문자 구분 없는 일치를 위해 열 이름은 대문자화돼요. |
| Data Record Path | 지정하면 각 들어오는 Record에 대해 평가될 RecordPath를 나타내며, RecordPath를 평가한 결과 Record가 전체 들어오는 Record 대신 데이터베이스로 전송돼요. 지정하지 않으면 전체 들어오는 Record가 데이터베이스에 게시돼요. |
| Database Dialect Service | 특정 서비스 또는 벤더에 맞는 문을 생성하기 위한 Database Dialect Service예요. |
| Delete Keys | DELETE 문에 대해 데이터베이스에서 행을 고유하게 식별하는 쉼표로 구분된 열 이름 목록이에요. Statement Type이 DELETE이고 이 속성이 설정되지 않으면 테이블의 열이 사용돼요. 이 속성은 Statement Type이 DELETE가 아니면 무시돼요. |
| Rollback On Failure | 오류 처리 방법을 지정해요. 기본값(false)에서는 FlowFile 처리 중 오류가 발생하면 오류 유형에 따라 FlowFile이 'failure' 또는 'retry' 관계로 라우팅되고 프로세서는 다음 FlowFile을 계속 처리할 수 있어요. 대신 현재 처리 중인 FlowFile을 롤백하고 즉시 추가 처리를 중지하고 싶을 수 있어요. 그 경우 이 'Rollback On Failure' 속성을 활성화하면 돼요. 활성화하면 실패한 FlowFile은 입력 관계에 남고 패널티 없이 성공적으로 처리되거나 다른 방법으로 제거될 때까지 반복 처리돼요. 너무 자주 재시도하지 않도록 적절한 'Yield Duration'을 설정하는 것이 중요해요. |
| Statement Type Record Path | Statement Type을 결정하기 위해 각 Record에 대해 평가할 RecordPath를 지정해요. RecordPath는 INSERT, UPDATE, UPSERT 또는 DELETE 중 하나와 같아야 해요. (Debezium 스타일 연산 유형도 지원돼요: INSERT를 위한 "r"과 "c", UPDATE를 위한 "u", DELETE를 위한 "d".) |
| database-session-autocommit | 사용 중인 데이터베이스 연결에 설정할 autocommit 모드예요. false로 설정하면 연산이 명시적으로 커밋되거나 (각각 성공 또는 실패에 따라) 롤백돼요. true로 설정하면 드라이버/데이터베이스가 커밋/롤백을 자동으로 처리해요. |
| db-type | 특정 서비스 또는 벤더에 맞는 문을 생성하기 위한 Database Type이에요. Generic Type은 대부분의 경우를 지원하지만 특정 유형을 선택하면 최적의 처리 또는 추가 기능이 가능해요. |
| put-db-record-allow-multiple-statements | Statement Type이 'SQL'(statement.type 속성에 설정)이면 이 필드는 필드 값을 세미콜론으로 분할해 각 문을 개별 실행할지 여부를 나타내요. 문 하나라도 오류가 발생하면 전체 문 집합이 롤백돼요. Statement Type이 'SQL'이 아니면 이 필드는 무시돼요. |
| put-db-record-binary-format | 문자열 값을 이진으로 디코딩할 때 적용할 형식이에요. |
| put-db-record-catalog-name | 문이 업데이트해야 하는 데이터베이스(또는 대상 시스템에 따라 카탈로그) 이름이에요. 업데이트 중인 데이터베이스에는 적용되지 않을 수 있어요. 그 경우 필드를 비워두세요. 이 속성이 설정되고 데이터베이스가 대소문자 구분이면 카탈로그 이름이 데이터베이스의 카탈로그 이름과 정확히 일치해야 해요. |
| put-db-record-dbcp-service | 레코드를 보내기 위해 데이터베이스에 대한 연결을 얻는 데 사용하는 Controller Service예요. |
| put-db-record-field-containing-sql | Statement Type이 'SQL'(statement.type 속성에 설정)이면 이 필드는 레코드 중 어떤 필드에 실행할 SQL 문이 들어 있는지 나타내요. 필드 값은 단일 SQL 문이어야 해요. Statement Type이 'SQL'이 아니면 이 필드는 무시돼요. |
| put-db-record-max-batch-size | 데이터베이스로 보내는 각 배치에 포함할 최대 SQL 문 수를 지정해요. 0은 배치 크기가 제한되지 않음을 의미하며 모든 문이 단일 배치에 들어가는데, 문이 매우 많으면 높은 메모리 사용량 문제를 일으킬 수 있어요. |
| put-db-record-query-timeout | 실행 중인 SQL 문에 허용되는 최대 시간으로, 0은 제한이 없음을 의미해요. 1초 미만의 최대 시간은 0과 같아요. |
| put-db-record-quoted-identifiers | 이 옵션을 활성화하면 모든 열 이름이 따옴표로 처리되어 테이블에서 예약어를 열 이름으로 사용할 수 있게 해요. |
| put-db-record-quoted-table-identifiers | 이 옵션을 활성화하면 테이블 이름이 따옴표로 처리되어 테이블 이름의 특수 문자 사용을 지원해요. |
| put-db-record-record-reader | 들어오는 데이터를 파싱하고 데이터의 스키마를 결정하는 데 사용할 Controller Service를 지정해요. |
| put-db-record-schema-name | 테이블이 속한 스키마의 이름이에요. 업데이트 중인 데이터베이스에는 적용되지 않을 수 있어요. 그 경우 필드를 비워두세요. 이 속성이 설정되고 데이터베이스가 대소문자 구분이면 스키마 이름이 데이터베이스의 스키마 이름과 정확히 일치해야 해요. |
| put-db-record-statement-type | 생성할 SQL 문의 유형을 지정해요. 각 연산의 동작 설명은 데이터베이스 문서를 참고하세요. 일부 Database Type은 특정 Statement Type을 지원하지 않을 수 있다는 점에 유의하세요. 'Use statement.type Attribute'를 선택하면 FlowFile의 statement.type 속성에서 값을 가져와요. 'Use statement.type Attribute' 옵션만 'SQL' 문 유형을 허용해요. 'SQL'이 지정되면 'Field Containing SQL' 속성이 지정하는 필드의 값은 대상 데이터베이스에서 유효한 SQL 문이어야 하며 그대로 실행돼요. |
| put-db-record-table-name | 문이 영향을 주어야 하는 테이블의 이름이에요. 데이터베이스가 대소문자 구분이면 테이블 이름이 데이터베이스의 테이블 이름과 정확히 일치해야 해요. |
| put-db-record-translate-field-names | true면 프로세서가 필드 이름을 지정된 테이블의 적절한 열 이름으로 변환하려 해요. false면 필드 이름이 열 이름과 정확히 일치해야 하며, 그렇지 않으면 열이 업데이트되지 않아요. |
| put-db-record-unmatched-column-behavior | 들어오는 레코드가 데이터베이스 테이블의 모든 열에 대한 필드 매핑을 갖고 있지 않으면 이 속성이 상황을 처리하는 방법을 지정해요. |
| put-db-record-unmatched-field-behavior | 들어오는 레코드에 데이터베이스 테이블의 열에 매핑되지 않는 필드가 있으면 이 속성이 상황을 처리하는 방법을 지정해요. |
| put-db-record-update-keys | UPDATE 문에 대해 데이터베이스에서 행을 고유하게 식별하는 쉼표로 구분된 열 이름 목록이에요. Statement Type이 UPDATE이고 이 속성이 설정되지 않으면 테이블의 Primary Keys가 사용돼요. 이 경우 Primary Key가 없으면 Unmatched Column Behaviour가 FAIL로 설정되었을 때 SQL 변환이 실패해요. 이 속성은 Statement Type이 INSERT면 무시돼요. |
| table-schema-cache-size | 몇 개의 Table Schemas를 캐시할지 지정해요. |
관계 (Relationships)
| 이름 | 설명 |
|---|---|
failure |
데이터베이스를 업데이트할 수 없고 재시도해도 실패할 경우(잘못된 쿼리 또는 무결성 제약 위반 등) FlowFile이 이 관계로 라우팅돼요. |
retry |
데이터베이스를 업데이트할 수 없지만 재시도하면 성공할 수 있으면 FlowFile이 이 관계로 라우팅돼요. |
success |
SQL 쿼리 결과 집합에서 성공적으로 생성된 FlowFile이 이 관계로 이동해요. |
쓰기 속성 (Writes attributes)
| 이름 | 설명 |
|---|---|
putdatabaserecord.error |
처리 중 오류가 발생하면 flow file이 failure 또는 retry로 라우팅되고 이 속성에 오류 원인이 채워져요. |
사용 사례
- 레코드를 데이터베이스에 삽입해요.