ExecuteSQL 프로세서

Snowflake Openflow의 ExecuteSQL 프로세서에 대한 문서예요. 제공된 SQL select 쿼리를 실행하고, 그 결과를 Avro 형식으로 변환하는 프로세서예요. 스트리밍을 사용하기 때문에 임의로 큰 결과 집합을 지원해요.

출처: Snowflake 문서

본문

기능 — 일반 제공(Generally Available)

Openflow Snowflake 배포는 AWS, Azure, GCP 상용(Commercial) 리전의 모든 계정에서 사용할 수 있어요. Openflow BYOC 배포는 AWS 상용(Commercial) 리전의 모든 계정에서 사용할 수 있어요.

번들(Bundle)

org.apache.nifi | nifi-standard-nar

설명(Description)

제공된 SQL select 쿼리를 실행해요. 쿼리 결과는 Avro 형식으로 변환돼요. 스트리밍을 사용하므로 임의로 큰 결과 집합을 지원해요. 이 프로세서는 표준 스케줄링 방법을 따라 타이머나 cron 표현식으로 실행하도록 예약할 수 있고, 들어오는 FlowFile로 트리거할 수도 있어요. 들어오는 FlowFile로 트리거되면 select 쿼리를 평가할 때 그 FlowFile의 속성을 사용할 수 있으며, 쿼리는 ? 를 사용해 매개변수를 이스케이프할 수 있어요. 이 경우 사용할 매개변수는 sql.args.N.type과 sql.args.N.value라는 명명 규칙의 FlowFile 속성으로 존재해야 해요(N은 양의 정수). sql.args.N.type은 JDBC Type을 나타내는 숫자여야 해요. FlowFile의 콘텐츠는 UTF-8 형식일 것으로 예상돼요. FlowFile 속성 'executesql.row.count'는 선택된 행 수를 나타내요.

태그(Tags)

database, jdbc, query, select, sql

입력 요구사항(Input Requirement)

ALLOWED

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

true

속성(Properties)

속성(Property)	설명(Description)
Content Output Strategy	입력 FlowFile을 처리할 때 FlowFile 콘텐츠를 기록하는 전략을 지정해요. 이 전략은 결과를 생성하지 않는 쿼리를 처리할 때 적용돼요.
Database Connection Pooling Service	데이터베이스에 연결을 얻는 데 사용하는 Controller Service예요.
Default Decimal Precision	DECIMAL/NUMBER 값을 'decimal' Avro 논리 유형으로 기록할 때 사용 가능한 자릿수를 나타내는 특정 'precision'이 필요해요. 일반적으로 precision은 열 데이터 유형 정의나 데이터베이스 엔진 기본값으로 정의돼요. 하지만 일부 데이터베이스 엔진은 정의되지 않은 precision(0)을 반환할 수 있어요. 'Default Decimal Precision'은 그런 정의되지 않은 precision 숫자를 기록할 때 사용돼요.
Default Decimal Scale	DECIMAL/NUMBER 값을 'decimal' Avro 논리 유형으로 기록할 때 사용 가능한 소수 자릿수를 나타내는 특정 'scale'이 필요해요. 일반적으로 scale은 열 데이터 유형 정의나 데이터베이스 엔진 기본값으로 정의돼요. 하지만 정의되지 않은 precision(0)이 반환되면 일부 데이터베이스 엔진에서는 scale도 불확실할 수 있어요. 'Default Decimal Scale'은 그런 정의되지 않은 숫자를 기록할 때 사용돼요. 값이 지정된 scale보다 많은 소수 자릿수를 가지면 반올림되는데, 예를 들어 1.53은 scale 0에서 2가 되고 1.5는 scale 1에서 그대로예요.
Max Wait Time	실행 중인 SQL select 쿼리에 허용되는 최대 시간이에요. 0이면 제한이 없어요. 1초 미만의 최대 시간은 0과 같아요.
Normalize Table and Column Names	열 이름의 Avro 호환 불가 문자를 Avro 호환 문자로 바꿀지 여부예요. 예를 들어 유효한 Avro 레코드를 만들기 위해 콜론과 마침표를 밑줄로 바꿔요.
SQL Query	실행할 SQL 쿼리예요. 쿼리는 비어 있거나, 상수 값이거나, Expression Language를 사용해 속성에서 만들 수 있어요. 이 속성이 지정되면 들어오는 FlowFile의 콘텐츠와 무관하게 사용돼요. 이 속성이 비어 있으면 들어오는 FlowFile의 콘텐츠가 프로세서가 데이터베이스에 보낼 유효한 SQL select 쿼리를 포함할 것으로 예상돼요. Expression Language는 FlowFile 콘텐츠에 대해 평가되지 않아요.
Use Avro Logical Types	DECIMAL/NUMBER, DATE, TIME, TIMESTAMP 열에 Avro 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 레코드를 읽는 사람도 이 논리 유형을 안다면 판독기 구현에 따라 더 많은 맥락으로 이 값을 역직렬화할 수 있어요.
compression-format	Avro 파일을 기록할 때 사용할 압축 유형이에요. 기본값은 None이에요.
esql-auto-commit	DB 연결의 auto commit 기능을 활성화 또는 비활성화해요. 기본값은 'true'예요. 이 프로세서는 데이터를 읽는 데 사용되므로 대부분의 JDBC 드라이버에서 기본값을 사용할 수 있고 이 기능은 대부분의 경우 영향이 없어요. 하지만 PostgreSQL 드라이버 같은 일부 JDBC 드라이버에서는 한 번에 가져오는 결과 행 수를 제한하기 위해 auto commit을 비활성화해야 해요. auto commit이 활성화되면 postgreSQL 드라이버는 전체 결과 집합을 한 번에 메모리로 로드해요. 이는 큰 데이터 집합을 가져오는 쿼리를 실행할 때 많은 메모리를 사용할 수 있어요. PostgreSQL 드라이버의 이 동작에 대한 자세한 내용은 https://jdbc.postgresql.org/documentation/head/query.html 에서 확인할 수 있어요.
esql-fetch-size	한 번에 결과 집합에서 가져올 결과 행 수예요. 데이터베이스 드라이버에 대한 힌트이며 정확히 지켜지지 않을 수 있어요. 지정된 값이 0이면 힌트는 무시돼요.
esql-max-rows	단일 FlowFile에 포함될 최대 결과 행 수예요. 이것은 아주 큰 결과 집합을 여러 FlowFile로 나눌 수 있게 해요. 지정된 값이 0이면 모든 행이 단일 FlowFile로 반환돼요.
esql-output-batch-size	프로세스 세션을 커밋하기 전에 큐에 넣을 출력 FlowFile 수예요. 0으로 설정하면 모든 결과 집합 행이 처리되고 출력 FlowFile이 다운스트림 관계로 전송될 준비가 되면 세션이 커밋돼요. 큰 결과 집합의 경우 프로세서 실행 끝에 많은 FlowFile이 한꺼번에 전송될 수 있어요. 이 속성이 설정되면 지정된 수의 FlowFile이 전송 준비가 될 때 세션이 커밋되어 FlowFile이 다운스트림 관계로 해제돼요. 참고: 이 속성이 설정되면 FlowFile에 fragment.count 속성이 설정되지 않아요.
sql-post-query	기본 SQL 쿼리 실행 후 실행되는 세미콜론으로 구분된 쿼리 목록이에요. 기본 쿼리 후 세션 속성을 설정하는 것 같은 예가 있어요. 문 안에서 세미콜론은 백슬래시(';')로 이스케이프해 포함할 수 있어요. 이 쿼리의 결과/출력은 오류가 없으면 억제돼요.
sql-pre-query	기본 SQL 쿼리 실행 전에 실행되는 세미콜론으로 구분된 쿼리 목록이에요. 예를 들어 기본 쿼리 전에 세션 속성을 설정할 수 있어요. 문 안에서 세미콜론은 백슬래시(';')로 이스케이프해 포함할 수 있어요. 이 쿼리의 결과/출력은 오류가 없으면 억제돼요.

관계(Relationships)

이름(Name)	설명(Description)
failure	SQL 쿼리 실행이 실패했어요. 들어오는 FlowFile에 패널티가 주어지고 이 관계로 라우팅돼요.
success	SQL 쿼리 결과 집합에서 FlowFile을 성공적으로 만들었어요.

속성 기록(Writes attributes)

이름(Name)	설명(Description)
executesql.row.count	쿼리가 반환한 행 수를 담아요. 'Max Rows Per Flow File'이 설정되면 이 숫자는 전체 결과 집합이 아닌 Flow File의 행 수를 반영해요.
executesql.query.duration	쿼리 실행 시간과 가져오기(fetch) 시간을 합친 밀리초 단위 기간이에요. '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	들어오는 FlowFile 처리가 예외를 일으키면 Flow File이 failure로 라우팅되고 이 속성에 예외 메시지가 설정돼요.
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 속성과 함께 사용할 수 있어요.
input.flowfile.uuid	프로세서에 입력 연결이 있으면 출력 FlowFile에 이 속성이 입력 FlowFile의 UUID 값으로 설정돼요. 입력 연결이 없으면 속성이 추가되지 않아요.

ExecuteSQL 프로세서