ExecuteSQL 2025.5.31.15¶

번들¶

org.apache.nifi | nifi-standard-nar

설명¶

제공된 SQL select 쿼리를 실행합니다. 쿼리 결과가 Avro 형식으로 변환됩니다. 스트림이 사용되므로 임의로 큰 결과 세트가 지원됩니다. 이 프로세서는 표준 스케줄링 방법을 사용하여 타이머 또는 cron 식에 따라 실행되도록 예약하거나 수신 FlowFile 에 의해 트리거될 수 있습니다. 수신 FlowFile 에 의해 트리거되는 경우 선택 쿼리를 평가할 때 해당 FlowFile 의 특성을 사용할 수 있으며 쿼리는 매개 변수를 이스케이프하기 위해 ?를 사용할 수 있습니다. 이 경우 사용할 매개 변수는 명명 규칙이 sql.args.N.type 및 sql.args.N.value인 FlowFile 특성으로 존재해야 하며, 여기서 N은 양의 정수입니다. Sql.args.N.type은 JDBC 유형을 나타내는 숫자로 예상됩니다. FlowFile 의 내용은 UTF-8 형식이 될 것으로 예상됩니다. FlowFile 특성 ‘executesql.row.count’는 선택된 행 수를 나타냅니다.

태그¶

database, jdbc, query, select, sql

입력 요구 사항¶

ALLOWED

민감한 동적 속성 지원¶

true

속성¶

속성	설명
Content Output Strategy	입력 FlowFiles 을 처리할 때 FlowFile 내용을 작성하는 전략을 지정합니다. 이 전략은 결과물을 생성하지 않는 쿼리를 처리할 때 적용됩니다.
Database Connection Pooling Service	데이터베이스에 대한 연결을 얻는 데 사용되는 컨트롤러 서비스
최대 대기 시간	실행 중인 SQL select 쿼리에 허용되는 최대 시간이며, 0은 제한이 없음을 의미합니다. 최대 시간이 1초 미만이면 0이 됩니다.
SQL 쿼리	실행할 SQL 쿼리. 쿼리는 비어 있거나 상수 값일 수도 있고 표현식 언어를 사용하여 특성으로 작성할 수도 있습니다. 이 속성을 지정하면 수신 flowfile의 내용에 관계없이 사용됩니다. 이 속성이 비어 있으면 수신 플로우 파일의 내용에는 프로세서가 데이터베이스에 발행할 유효한 SQL select 쿼리가 포함될 것으로 예상됩니다. 표현식 언어는 플로우 파일 내용에 대해 평가되지 않습니다.
compression-format	Avro 파일을 작성할 때 사용할 압축 유형입니다. 기본값은 None입니다.
dbf-default-precision	DECIMAL/NUMBER 값이 ‘소수점’ Avro 논리 유형으로 작성된 경우 사용할 수 있는 자릿수를 나타내는 특정 ‘전체 자릿수’가 필요합니다. 일반적으로 전체 자릿수는 열 데이터 타입 정의 또는 데이터베이스 엔진 기본값에 의해 정의됩니다. 그러나 일부 데이터베이스 엔진에서는 정의되지 않은 전체 자릿수(0)가 반환될 수 있습니다. ‘Default Decimal Precision’은 정의되지 않은 전체 자릿수 숫자를 쓸 때 사용됩니다.
dbf-default-scale	DECIMAL/NUMBER 값을 ‘소수점’ Avro 논리 유형으로 작성하는 경우 가용성 있는 소수점 자릿수를 나타내는 특정 ‘스케일’이 필요합니다. 일반적으로 스케일은 열 데이터 타입 정의 또는 데이터베이스 엔진 기본값에 의해 정의됩니다. 그러나 정의되지 않은 전체 자릿수(0)가 반환되면 일부 데이터베이스 엔진에서는 스케일이 불확실할 수도 있습니다. 정의되지 않은 숫자를 쓸 때는 ‘Default Decimal Scale’이 사용됩니다. 값이 지정된 스케일보다 소수점이 많은 경우 값이 반올림됩니다(예: 1.53은 스케일 0으로 2가 되고 1.5는 스케일 1로 1.5가 됩니다).
dbf-normalize	열 이름에서 Avro와 호환되지 않는 문자를 Avro와 호환되는 문자로 변경할지 여부입니다. 예를 들어, 콜론과 기간은 유효한 Avro 레코드를 작성하기 위해 밑줄로 변경됩니다.
dbf-user-logical-types	DECIMAL/NUMBER, DATE, TIME 및 TIMESTAMP 열에 Avro 논리 유형을 사용할지 여부. 비활성화하면 문자열로 작성됩니다. 활성화하면 논리 유형이 기본 유형으로 사용되며, 구체적으로 DECIMAL/NUMBER 는 논리 ‘decimal’: 추가 전체 자릿수 및 스케일 메타 데이터와 함께 바이트로 작성, DATE 는 논리 ‘date-millis’: Unix epoch(1970-01-01) 이후 날짜를 나타내는 int로 작성, TIME 은 논리 ‘time-millis’: Unix epoch 이후 밀리초를 나타내는 int로 작성, TIMESTAMP 는 논리 ‘timestamp-millis’: Unix epoch 이후 밀리초를 나타내는 long형으로 작성됩니다. 작성된 Avro 레코드의 리더가 이러한 논리 유형을 알고 있다면, 리더 구현에 따라 이러한 값을 더 많은 컨텍스트로 역직렬화할 수 있습니다.
esql-auto-commit	DB 연결의 자동 커밋 기능을 사용하거나 사용하지 않도록 설정합니다. 기본값은 ‘true’입니다. 기본값은 대부분의 JDBC 드라이버에서 사용할 수 있으며, 이 프로세서는 데이터를 읽는 데 사용되므로 대부분의 경우 이 기능은 영향을 미치지 않습니다. 그러나 PostgreSQL 드라이버 같은 일부 JDBC 드라이버의 경우 한 번에 가져오는 결과 행 수를 제한하기 위해 자동 커밋 기능을 비활성화해야 합니다. 자동 커밋이 활성화되면 postgreSQL 드라이버가 전체 결과 세트를 한 번에 메모리에 로딩합니다. 이로 인해 대규모 데이터 세트를 가져오는 쿼리를 실행할 때 많은 양의 메모리를 사용할 수 있습니다. PostgreSQL 드라이버에서 이 동작에 대한 자세한 내용은 https://jdbc.postgresql.org//documentation/head/query.html에서 확인할 수 있습니다.
esql-fetch-size	결과 세트에서 한 번에 가져올 결과 행의 수입니다. 이는 데이터베이스 드라이버에 대한 힌트이며 정확하지 않을 수도 있습니다. 지정한 값이 0이면 힌트가 무시됩니다.
esql-max-rows	단일 FlowFile 에 포함될 결과 행의 최대 개수입니다. 이렇게 하면 매우 큰 결과 세트를 여러 개의 FlowFiles 로 분할할 수 있습니다. 지정된 값이 0이면 모든 행이 1개의 FlowFile 로 반환됩니다.
esql-output-batch-size	프로세스 세션을 커밋하기 전에 큐에 넣을 출력 FlowFiles 의 개수입니다. 0으로 설정하면 모든 결과 세트 행이 처리되고 FlowFiles 출력이 다운스트림 관계로 전송할 준비가 되면 세션이 커밋됩니다. 결과 세트가 큰 경우 프로세서 실행이 끝날 때 FlowFiles 이 대량으로 전송될 수 있습니다. 이 속성을 설정하면 지정된 수의 FlowFiles 전송이 준비되면 세션이 커밋되어 FlowFiles 을 다운스트림 관계에 릴리스합니다. 참고: 이 속성이 설정되어 있으면 FlowFiles 에 fragment.count 특성이 설정되지 않습니다.
sql-post-query	기본 SQL 쿼리가 실행된 후 실행된 쿼리의 세미콜론으로 구분된 목록입니다. 메인 쿼리 후 세션 속성을 설정하는 것과 같은 예입니다. 백슬래시(’;’)로 이스케이프 처리하여 문 자체에 세미콜론을 포함할 수 있습니다. 이러한 쿼리 결과/출력은 오류가 없는 경우 표시되지 않습니다.
sql-pre-query	기본 SQL 쿼리가 실행되기 전에 실행된 쿼리의 세미콜론으로 구분된 목록입니다. 예를 들어, 메인 쿼리 전에 세션 속성을 설정합니다. 백슬래시(’;’)로 이스케이프 처리하여 문 자체에 세미콜론을 포함할 수 있습니다. 이러한 쿼리 결과/출력은 오류가 없는 경우 표시되지 않습니다.

관계¶

이름	설명
실패	SQL 쿼리 실행에 실패했습니다. 수신 FlowFile 은 불이익을 받고 이 관계로 라우팅됩니다
성공	SQL 쿼리 결과 세트에서 FlowFile 을 성공적으로 생성했습니다.

Writes 특성¶

이름	설명
executesql.row.count	쿼리에서 반환된 행 수를 포함합니다. ‘Max Rows Per Flow File’이 설정된 경우 이 숫자는 전체 결과 세트가 아닌 Flow File의 행 수를 반영합니다.
executesql.query.duration	쿼리 실행 시간과 가져오기 시간의 합산 기간(밀리초)입니다. ‘Max Rows Per Flow File’을 설정하면 이 숫자는 전체 결과 세트 대신 Flow File에 있는 행의 가져오기 시간만 반영합니다.
executesql.query.executiontime	쿼리 실행 시간(밀리초)입니다. 이 숫자는 ‘Max Rows Per Flow File’ 설정과 관계없이 쿼리 실행 시간을 반영합니다.
executesql.query.fetchtime	결과 세트 가져오기 시간(밀리초)입니다. ‘Max Rows Per Flow File’을 설정하면 이 숫자는 전체 결과 세트 대신 Flow File에 있는 행의 가져오기 시간만 반영합니다.
executesql.resultset.index	여러 결과 세트가 반환된다고 가정하면 이 결과 세트의 0 기반 인덱스입니다.
executesql.error.message	수신 Flow File을 처리할 때 예외가 발생하면 Flow File이 실패로 라우팅되고 이 특성이 예외 메시지로 설정됩니다.
fragment.identifier	‘Max Rows Per Flow File’이 설정된 경우 동일한 쿼리 결과 세트의 모든 FlowFiles 은 fragment.identifier 특성에 대해 동일한 값을 갖습니다. 그런 다음 결과를 상호 연관시키는 데 사용할 수 있습니다.
fragment.count	‘Max Rows Per Flow File’이 설정된 경우 이는 단일 ResultSet 에서 생성되는 FlowFiles 의 총 개수입니다. 이는 동일한 수신 ResultSet 에 속하는 FlowFiles 의 수를 파악하기 위해 fragment.identifier 특성과 함께 사용할 수 있습니다. 출력 배치 크기가 설정되어 있으면 이 특성이 채워지지 않습니다.
fragment.index	‘Max Rows Per Flow File’이 설정된 경우, 동일한 결과 세트 FlowFile 에서 모두 파생된 발신 FlowFiles 목록에서 이 FlowFile 의 위치가 변경됩니다. 이것은 fragment.identifier 특성과 함께 사용하여 동일한 쿼리 결과 세트에서 어떤 FlowFiles 이 생성되었는지, 어떤 순서로 FlowFiles 이 생성되었는지 알 수 있습니다
input.flowfile.uuid	프로세서에 수신 연결이 있는 경우, 송신 FlowFiles 은 이 특성을 입력 FlowFile 의 UUID 값으로 설정합니다. 수신 연결이 없으면 특성이 추가되지 않습니다.