QueryDatabaseTable

QueryDatabaseTable

지정한 Maximum Value 열(들)의 값이 이전에 본 최댓값보다 큰 모든 행을 가져오도록 SQL SELECT 쿼리를 생성(또는 제공된 문 사용)해 실행하는 프로세서예요. 증분 적재에 자주 사용되고, 결과는 Avro 형식으로 변환돼요.

출처: Snowflake 문서

본문

번들 (Bundle)

org.apache.nifi | nifi-standard-nar

설명 (Description)

SQL select 쿼리를 생성하거나 제공된 문을 사용해서, 지정한 Maximum Value 열의 값이 이전에 본 최댓값보다 큰 모든 행을 가져오도록 실행합니다. 쿼리 결과는 Avro 형식으로 변환됩니다. 여러 속성에서 Expression Language 를 지원하지만, 들어오는 연결은 허용되지 않습니다. Expression Language 를 포함하는 속성의 값을 제공하려면 Environment/System 속성을 사용할 수 있습니다. 이러한 쿼리를 수행하기 위해 FlowFile 속성을 활용하고자 한다면 GenerateTableFetch 또는 ExecuteSQL 프로세서를 사용할 수 있습니다. 임의로 큰 결과 집합을 지원하도록 스트리밍 방식으로 동작합니다. 이 프로세서는 표준 스케줄링 방식으로 타이머 또는 cron 표현식에 따라 실행되도록 예약할 수 있습니다. 이 프로세서는 Primary Node에서만 실행하도록 설계되었습니다. FlowFile 속성 'querydbtable.row.count'는 선택된 행 개수를 나타냅니다.

태그 (Tags)

database, jdbc, query, select, sql

입력 요구사항 (Input Requirement)

FORBIDDEN

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

false

속성 (Properties)

속성 (Property) 설명 (Description)
Columns to Return 쿼리에 사용할 열 이름의 쉼표로 구분된 목록입니다. 데이터베이스가 이름에 특별한 처리를 요구한다면(예: 따옴표) 각 이름에 그 처리를 포함해야 합니다. 열 이름을 제공하지 않으면 지정한 테이블의 모든 열이 반환됩니다. 참고: 증분 가져오기가 제대로 동작하려면 특정 테이블에 대해 일관된 열 이름을 사용하는 것이 중요합니다.
Database Connection Pooling Service 데이터베이스에 대한 연결을 얻는 데 사용되는 Controller Service입니다.
Database Dialect Service 특정 서비스 또는 벤더에 맞는 문을 생성하기 위한 Database Dialect Service입니다.
Default Decimal Precision DECIMAL/NUMBER 값을 'decimal' Avro 논리 타입으로 쓸 때 사용 가능한 자릿수를 나타내는 특정 'precision'이 필요합니다. 일반적으로 precision은 열 데이터 타입 정의나 데이터베이스 엔진의 기본값으로 결정됩니다. 그러나 일부 데이터베이스 엔진에서는 정의되지 않은 precision(0)이 반환될 수 있습니다. 이러한 정의되지 않은 precision 숫자를 쓸 때 'Default Decimal Precision'이 사용됩니다.
Default Decimal Scale DECIMAL/NUMBER 값을 'decimal' Avro 논리 타입으로 쓸 때 사용 가능한 소수 자릿수를 나타내는 특정 'scale'이 필요합니다. 일반적으로 scale은 열 데이터 타입 정의나 데이터베이스 엔진의 기본값으로 결정됩니다. 그러나 정의되지 않은 precision(0)이 반환되면 일부 데이터베이스 엔진에서는 scale도 불확실할 수 있습니다. 이러한 정의되지 않은 숫자를 쓸 때 'Default Decimal Scale'이 사용됩니다. 값이 지정한 scale보다 소수 자릿수가 더 많으면 반올림됩니다(예: 1.53은 scale 0에서는 2가 되고, scale 1에서는 1.5가 됩니다).
Fetch Size 결과 집합에서 한 번에 가져올 결과 행 수입니다. 이는 데이터베이스 드라이버에 대한 힌트이며 항상 정확히 지켜지지 않을 수 있습니다. 지정 값이 0이면 힌트는 무시됩니다. PostgreSQL을 사용하는 경우 'Fetch Size'가 적용되도록 'Set Auto Commit'이 'false'여야 합니다.
Max Wait Time 실행 중인 SQL select 쿼리에 허용되는 최대 시간이며, 0이면 제한이 없습니다. 1초 미만의 최대 시간은 0과 동일하게 처리됩니다.
Maximum-value Columns 열 이름의 쉼표로 구분된 목록입니다. 프로세서는 실행 시작 이후 반환된 각 열의 최댓값을 추적합니다. 여러 열을 사용하면 열 목록에 순서가 의미하게 되고, 각 열의 값은 이전 열의 값보다 더 천천히 증가할 것으로 예상됩니다. 따라서 여러 열을 사용하면 계층적 구조의 열을 의미하며, 보통 테이블 파티셔닝에 사용됩니다. 이 프로세서는 마지막 조회 이후 추가/갱신된 행만 가져오는 데 사용할 수 있습니다. bit/boolean 같은 일부 JDBC 타입은 최댓값 유지에 적합하지 않으므로 처리 중 오류가 발생할 수 있습니다. 열을 제공하지 않으면 테이블의 모든 행이 고려되며 성능에 영향을 줄 수 있습니다. 참고: 증분 가져오기가 제대로 동작하려면 특정 테이블에 대해 일관된 max-value 열 이름을 사용하는 것이 중요합니다.
Normalize Table and Column Names 열 이름에서 Avro 호환 문자가 아닌 문자를 Avro 호환 문자로 변경할지 여부입니다. 예를 들어, 유효한 Avro 레코드를 만들기 위해 콜론과 마침표가 밑줄로 변경됩니다.
Set Auto Commit DB 연결의 자동 커밋 기능을 활성화하거나 비활성화합니다. 기본값은 'No value set'입니다. 'No value set'이면 DB 연결의 자동 커밋 모드를 변경하지 않고 그대로 둡니다. PostgreSQL 드라이버 같은 일부 JDBC 드라이버에서는 'Fetch Size' 설정이 적용되도록 자동 커밋 기능을 비활성화해야 합니다. 자동 커밋이 활성화되면 PostgreSQL 드라이버는 'Fetch Size' 설정을 무시하고 결과 집합의 모든 행을 한 번에 메모리로 로드합니다. 이는 큰 데이터 집합을 가져오는 쿼리를 실행할 때 많은 메모리를 사용할 수 있습니다. PostgreSQL 드라이버의 이 동작에 대한 자세한 내용은 https://jdbc.postgresql.org//documentation/head/query.html 에서 확인할 수 있습니다.
Table Name 쿼리할 데이터베이스 테이블의 이름입니다. 사용자 지정 쿼리를 사용하면 이 속성이 쿼리에 별칭을 붙이는 데 사용되며 FlowFile 속성으로 나타납니다.
Use Avro Logical Types DECIMAL/NUMBER, DATE, TIME, TIMESTAMP 열에 Avro Logical Types를 사용할지 여부입니다. 비활성화하면 문자열로 씁니다. 활성화하면 Logical types가 사용되어 기본 타입으로 기록됩니다. 구체적으로 DECIMAL/NUMBER는 논리 'decimal'(precision과 scale 메타데이터가 추가된 bytes), DATE는 논리 'date-millis'(Unix epoch 1970-01-01 이후 일수인 int), TIME은 논리 'time-millis'(Unix epoch 이후 밀리초인 int), TIMESTAMP는 논리 'timestamp-millis'(Unix epoch 이후 밀리초인 long)로 기록됩니다. 기록된 Avro 레코드를 읽는 쪽에서도 이 논리 타입을 안다면, 리더 구현에 따라 더 많은 맥락으로 값을 역직렬화할 수 있습니다.
db-fetch-db-type 특정 서비스 또는 벤더에 맞는 문을 생성하기 위한 데이터베이스 타입입니다. Generic Type은 대부분의 경우를 지원하지만 특정 타입을 선택하면 최적의 처리 또는 추가 기능이 가능합니다.
db-fetch-sql-query 데이터를 가져오는 데 사용하는 사용자 지정 SQL 쿼리입니다. 다른 속성에서 SQL 쿼리를 만드는 대신, 이 쿼리는 서브쿼리로 감싸집니다. 쿼리에는 ORDER BY 문이 없어야 합니다.
db-fetch-where-clause SQL 쿼리를 만들 때 WHERE 조건에 추가할 사용자 지정 절입니다.
initial-load-strategy 프로세서가 처음 시작될 때(또는 상태가 지워졌을 때) 데이터베이스 테이블의 기존 행을 처리하는 방법입니다. 'initial.maxvalue.*' 동적 속성이 구성되어 있으면 이 속성은 무시됩니다.
qdbt-max-frags 최대 단편(fragment) 수입니다. 지정 값이 0이면 모든 단편이 반환됩니다. 이는 이 프로세서가 거대한 테이블을 처리할 때 OutOfMemoryError를 방지합니다. 참고: 들어오는 결과가 정렬되지 않아 행이 결과 집합에 포함되지 않는 임의 경계에서 단편이 끝날 수 있으므로, 이 속성을 설정하면 데이터 손실이 발생할 수 있습니다.
qdbt-max-rows 단일 FlowFile에 포함될 최대 결과 행 수입니다. 이를 통해 매우 큰 결과 집합을 여러 FlowFile로 나눌 수 있습니다. 지정 값이 0이면 모든 행이 단일 FlowFile로 반환됩니다.
qdbt-output-batch-size 프로세스 세션을 커밋하기 전에 큐에 넣을 출력 FlowFile의 수입니다. 0으로 설정하면 모든 결과 집합 행이 처리되고 출력 FlowFile이 다운스트림 관계로 전송될 준비가 되었을 때 세션이 커밋됩니다. 큰 결과 집합의 경우 프로세서 실행이 끝날 때 많은 FlowFile이 한 번에 전송될 수 있습니다. 이 속성이 설정되면 지정한 수의 FlowFile이 전송 준비가 되었을 때 세션이 커밋되어 FlowFile이 다운스트림 관계로 전송됩니다. 참고: 이 속성이 설정되면 maxvalue.* 및 fragment.count 속성은 FlowFile에 설정되지 않습니다.
transaction-isolation-level 이 설정은 이를 지원하는 드라이버의 데이터베이스 연결에 대한 트랜잭션 격리 수준을 설정합니다.

상태 관리 (State management)

범위 (Scopes) 설명 (Description)
CLUSTER 지정한 테이블에 대한 쿼리를 수행한 후, 지정한 열(들)의 최댓값이 이후 쿼리 실행에 사용하도록 보존됩니다. 이렇게 하면 프로세서가 보존된 값보다 큰 max 값을 가진 레코드만 가져올 수 있습니다. 증분 가져오기, 새로 추가된 행 가져오기 등에 사용할 수 있습니다. 최댓값을 지우려면 State Management 문서에 따라 프로세서의 상태를 지우면 됩니다.

관계 (Relationships)

이름 (Name) 설명 (Description)
success SQL 쿼리 결과 집합에서 FlowFile이 성공적으로 생성되었습니다.

쓰는 속성 (Writes attributes)

이름 (Name) 설명 (Description)
tablename 쿼리 중인 테이블의 이름입니다.
querydbtable.row.count 쿼리가 선택한 행의 수입니다.
fragment.identifier 'Max Rows Per Flow File'이 설정되면 같은 쿼리 결과 집합의 모든 FlowFile은 fragment.identifier 속성에 대해 같은 값을 가집니다. 이를 결과를 연관시키는 데 사용할 수 있습니다.
fragment.count 'Max Rows Per Flow File'이 설정되면 단일 ResultSet이 만든 FlowFile의 총 수입니다. 같은 들어오는 ResultSet에 속한 FlowFile이 몇 개인지 알기 위해 fragment.identifier 속성과 함께 사용할 수 있습니다. Output Batch Size가 설정되면 이 속성은 채워지지 않습니다.
fragment.index 'Max Rows Per Flow File'이 설정되면 같은 결과 집합 FlowFile에서 파생된 출력 FlowFile 목록에서 이 FlowFile의 위치입니다. 어떤 FlowFile이 같은 쿼리 결과 집합에서 왔고 어떤 순서로 만들어졌는지 알기 위해 fragment.identifier 속성과 함께 사용할 수 있습니다.
maxvalue.* 각 속성은 지정한 'Maximum-value Column'의 관찰된 최댓값을 포함합니다. 속성의 접미사는 열 이름입니다. Output Batch Size가 설정되면 이 속성은 채워지지 않습니다.

함께 보기 (See also)

  • org.apache.nifi.processors.standard.ExecuteSQL
  • org.apache.nifi.processors.standard.GenerateTableFetch

더 알아보기 (Learn more)