ETL: 중급 Part02: System 변수 또는 사전 정의된 변수에 대하여

Integrate.io ETL의 System 변수와 사전 정의된 변수(Pre-Defined Variables) 전체 목록과 각 변수의 기본값, 용도를 정리하고 재시도 횟수 제어 방법을 설명합니다.

​

System 변수를 변경하는 이점

System 변수를 사용함으로써 재시도 횟수나 동시 실행 수 등 미리 정해져 있는 상한값을 작업(Job)의 특성에 맞게 변경할 수 있습니다.

​

System 변수는 어디에서 설정하나요?

변수 화면 왼쪽에서 “User”에서 “System”으로 전환하면 설정 화면을 전환할 수 있습니다.

​

System 변수 목록

주의 사항

아래 표 및 설명은 2026년 1월 시점의 정보를 바탕으로 작성되었습니다. 업데이트될 가능성이 있으므로, 최신 정보는 이 도움말을 참고해 주십시오.

System Variables	설명	기본값	단위	MB 환산
_MAX_COMBINED_SPLIT_SIZE	1개의 태스크에서 처리하는 데이터양을 바이트 단위로 지정합니다. 작은 파일은 이 크기에 도달할 때까지 결합됩니다. 그보다 큰 파일은 압축되지 않은 경우, 또는 Bzip2를 사용하여 압축된 경우 모두 설정된 크기를 기준으로 분할됩니다.	67,108,864	바이트	64
_BYTES_PER_REDUCER	1개의 레코드에서 읽을 수 있는 문자열 크기(바이트 단위). 그보다 큰 크기의 레코드는 무시됩니다.	209,715,200	바이트	200
_LINE_RECORD_READER_MAX_LENGTH	파일에서 읽어 들일 때 한 줄의 최대 바이트 길이. 이 값보다 긴 줄은 폐기됩니다.	1,048,576	바이트	1
_DEFAULT_TIMEZONE	DateTime 필드에서 Timezone 지정이 없는 경우 자동으로 Timezone을 추가할 때 사용되는 Timezone. 기본값은 UTC입니다.	+00:00’
_DEFAULT_PARALLELISM	패키지에서 사용할 병렬 Reduce 태스크의 기본 수를 설정합니다. 일반적으로 Reducer의 수는 데이터의 크기와 분포(distribution)에 따라 달라집니다. 데이터가 비교적 크지만 편중되어 있는 경우(예: 필드로 집계할 때 대부분의 레코드가 하나의 그룹으로 분류되는 경우), Reducer를 추가해도 성능에 긍정적인 영향을 주지 않습니다. 기본값은 0입니다. 이는 Reducer의 수가 _BYTES_PER_REDUCER에 의해 계산됨을 의미합니다.	0
_SHUFFLE_INPUT_BUFFER_PERCENT	셔플 중(Mapper의 출력을 Reducer로 전달하는 처리)에 최대 힙 크기에서 Map 출력 저장에 할당되는 메모리의 비율.	70%
_COPY_PARALLELISM	복사 전처리 액션에서 사용되는 프로세스의 수를 제어합니다.	0
_COPY_TARGET_PARTITIONS	복사 전처리 액션에 의해 데이터가 분할되는 파티션의 수를 제어합니다. 이 변수의 값을 0으로 설정하면 프로세스는 파일을 병합하지 않습니다.	100
_COPY_TARGET_SIZE	복사 전처리 액션에 의해 결합된 파일에 대해 파티션 내 파일 1개당 최대 크기를 제어합니다.	64
_PARQUET_COMPRESSION	저장 시 Apache Parquet를 사용할 경우의 압축 타입. 사용 가능한 값은 다음과 같습니다: UNCOMPRESSED, GZIP, SNAPPY.
_PARQUET_PAGE_SIZE	Apache Parquet 압축용 페이지 크기	1 * 1024 * 1024		1
_PARQUET_BLOCK_SIZE	Apache Parquet의 메모리에 버퍼링되는 row group의 크기. *Apache Parquet 공식 문서에 따르면 큰 row group(512MB~1GB)을 권장하고 있습니다. https://parquet.apache.org/documentation/latest/	128 * 1024 * 1024	바이트	128
_GA_API_REQUEST_READ_TIMEOUT	Google Analytics 요청의 타임아웃	30 * 1000	밀리초
_GA_API_REQUEST_MAX_RESULTS	Google Analytics 응답에 포함할 수 있는 행의 최대 수. (지정 가능한 최대값은 10000)	10,000
_GA_API_MAX_INPUT_SPLITS	Google Analytics에 대해 동시 실행할 수 있는 요청의 최대 수	10
_GA_API_SKIP_BAD_PROFILES	Google Analytics의 프로필 ID 중 접근할 수 없는 것이 포함된 경우에도 패키지 실행을 정상적으로 완료하려면 true로 설정합니다.	FALSE
_ADWORDS_API_REQUEST_READ_TIMEOUT	Google Adwords에 대한 요청의 타임아웃	180 * 1000	밀리초
_ADWORDS_API_MAX_INPUT_SPLITS	Google Adwords에 대해 동시 실행할 수 있는 요청의 최대 수	-1
_CACHED_BAG_MEMORY_PERCENT	Map 또는 Reduce 태스크의 모든 백(Bag, 데이터를 처리할 때 하나 또는 여러 필드를 그룹화한 것, 즉 처리 대상 데이터를 의미)에 할당되는 힙의 비율. 여기서 설정한 값이 가득 차면 데이터가 디스크로 유출됩니다. 값을 크게 하면 디스크로의 유출은 줄어들지만, 힙 메모리가 부족해질 가능성이 높아집니다.	0.2		20%
_MAP_MAX_ATTEMPTS	Map 태스크에 대해 실패로 완료되기 전에 몇 번 재시도를 수행할지	3
_REDUCER_MAX_ATTEMPTS	Reduce 태스크에 대해 실패로 완료되기 전에 몇 번 재시도를 수행할지	3
_MAP_MAX_FAILURES_PERCENT	작업이 실패로 완료되기 전에 실패할 수 있는 Map 태스크의 최대 비율(%)을 제어합니다. 값의 범위는 0~100입니다.	0
_REDUCER_MAX_FAILURES_PERCENT	작업이 실패로 완료되기 전에 실패할 수 있는 Reduce 태스크의 최대 비율(%)을 제어합니다. 값의 범위는 0~100입니다.	0
_MAP_TASK_TIMEOUT	태스크의 응답이 없을 경우 얼마나 기다린 후 해당 태스크를 종료(Kill)할지를 밀리초 단위로 설정합니다.	600 * 1000	밀리초
_BQ_READER_POLL_RETRIES	Google BigQuery에서의 데이터 내보내기를 폴링할 때의 재시도 횟수를 제어합니다.	60	회
_BQ_READER_POLL_INTERVAL	Google BigQuery에서의 데이터 내보내기를 폴링할 때 재시도 간격 시간을 밀리초 단위로 제어합니다.	10,000	밀리초
_BQ_READER_MAX_SHARDS	Shard된 테이블을 읽어 들일 때의 최대 수	500
_JDBC_SPLIT_QUERY_RETRIES	데이터베이스가 소스인 경우 병렬 쿼리에서 키의 최소값과 최대값을 취득하기 위한 재시도 횟수.	3
_JDBC_SPLIT_QUERY_RETRIES_INTERVAL_IN_SEC	데이터베이스 소스의 병렬 쿼리에서 키의 최소값과 최대값을 취득하기 위한 재시도 간격.	30
_SQL_COMMAND_TIMEOUT_IN_SEC	SQL 실행 시의 타임아웃. 기본값은 타임아웃 없음입니다.	-1
_INTERMEDIATE_COMPRESSION	결과에 대해 압축할지 여부입니다. 기본값은 압축하지 않음입니다.	FALSE
_SPANNER_MAX_WORKERS	Google Cloud Spanner가 쿼리를 분산 처리하는 경우의 최대 Worker 수	2
_SPANNER_BATCH_SIZE	Google Spanner에 로드할 때 트랜잭션 1개당 배치 크기(행 수). 기본값은 100입니다.	100
_FS_SFTP_MAX_RETRIES	SFTP에서 파일이나 디렉터리를 검색할 때의 재시도 횟수입니다. 기본값은 5입니다.	5
_FS_SFTP_RETRY_SLEEP	SFTP에서 파일이나 디렉터리를 검색할 때 재시도 간격(밀리초)입니다. 기본값은 500입니다.	500	밀리초
_FS_SFTP_BLOCK_SIZE	태스크가 SFTP에서 읽어 들이는 블록의 크기를 결정합니다. 큰 파일을 읽을 때 기본값보다 큰 값으로 변경합니다.	64 * 1024 * 1024	바이트	64
_FACEBOOK_ADS_INSIGHTS_SLEEP	Facebook Ads Insights 리포트 취득 시 재시도 간격(밀리초). 기본값은 0입니다.	0
_FB_ASYNC_REPORT_TIMEOUT	Facebook Ads Insights 리포트의 비동기 요청에 대한 요청 타임아웃(시도별). 이 값을 초과하면 시도가 실패합니다(기본값: 타임아웃 없음).	-1
_HTTP_FOLLOW_REDIRECTS	REST API 소스나 Curl 명령을 이용한 Function이 리다이렉트된 상태 코드를 따르지 않도록 하려면 false로 설정합니다.	TRUE
_HTTP_REQUEST_MAX_RETRIES	예외 오류가 되기 전, HTTP 응답 코드 429 또는 5xx를 수신했을 때 시도되는 REST API 소스 또는 Curl 함수의 재시도 횟수.	8
_SYNC_WAIT_TIME	Amazon Redshift를 Destination으로 하는 데이터를 스테이징한 후 Redshift 클러스터에서 COPY를 실행할 때까지 대기하는 시간(초 단위)	1
_XPATH_IGNORE_ERRORS	XML의 Xpath 오류를 무시할지 여부. 기본값은 무시하지 않음입니다.	FALSE
_FS_IGNORE_MISSING_INPUT_EXCEPTIONS	소스 경로(File Storage Source 컴포넌트를 포함)에서 입력 파일을 찾을 수 없는 경우에도 패키지를 정상적으로 완료하려면 true로 설정합니다.	FALSE
_ADWORDS_API_SKIP_BAD_ACCOUNTS	AdWords의 Account ID 중 접근할 수 없는 것이 포함된 경우에도 패키지를 정상적으로 완료하려면 true로 설정합니다(Google Adwords 소스 컴포넌트 사용 시).	FALSE
_BQ_READER_MAX_SHARDS	Google BigQuery가 “Exporting to multiple wildcard URIs…” 오류를 반환하는 경우 1로 설정.	500
_BQ_DATE_DATATYPE	Google BigQuery의 날짜 데이터 타입을 설정합니다.	‘TIMESTAMP’
_BQ_STAGING_TABLE_EXPIRY	Google BigQuery 스테이징 테이블의 유효 기간을 설정합니다.	24 * 60 * 60 * 1000
_GA4_API_REQUEST_MAX_RESULTS	Google Analytics(GA4) 소스 컴포넌트의 페이지당 최대 결과 수.	1000	밀리초
_GA4_API_REQUEST_MAX_ATTEMPTS	GA4 API에 대한 요청 시도 시 최대 시도 횟수.	3	회
_GA4_API_MAX_INPUT_SPLITS	Google Analytics 4의 동시 요청 최대 수.	8
_HUBSPOT_API_REQUEST_MAX_RETRIES	레이트 리밋 관련 오류를 수신했을 때 Hubspot API가 시도하는 재시도 횟수.	5	회
_SALESFORCE_API_REQUEST_MAX_RETRIES	요청 제한 관련 오류를 수신했을 때의 Salesforce API 재시도 횟수.	5	회
_TIMEOUT_IN_SECONDS	작업이 정지될 때까지의 초 수. 작업 실행 시간이 지나치게 길 경우 자동으로 정지할 수 있습니다. 기본적으로는 타임아웃이 설정되어 있지 않습니다(작업은 무기한으로 실행됩니다). 이는 계정 레벨에서도 설정 가능하며, 모든 패키지에 적용됩니다. 계정 레벨에서의 설정을 원하시는 경우 문의해 주십시오.	0	밀리초

​

Mapper와 Reducer의 재시도 횟수 제어에 대하여

​

_MAP_MAX_ATTEMPTS:

데이터 소스에서 데이터를 취득할 때의 재시도 횟수를 정의하는 **_MAP_MAX_ATTEMPTS**의 제어 대상에는 제한이 있습니다. 다음은 대상 범위 밖이므로 주의해 주십시오.

_MAP_MAX_ATTEMPTS의 재실행 대상에서 제외되는 데이터 소스:

• JDBC(데이터베이스) 재시도 횟수는 _JDBC_SPLIT_QUERY_RETRIES로 지정 가능합니다. *기본 재시도 횟수는 3회입니다.
• SFTP 재시도 횟수는 _FS_SFTP_MAX_RETRIES로 지정 가능합니다. *기본 재시도 횟수는 5회입니다.

​

_REDUCE_MAX_ATTEMPTS:

• **_REDUCE_MAX_ATTEMPTS**로 재시도 횟수를 제어할 수 있는 것은 Curl 함수를 사용한 요청 등 HTTP 요청(POST)으로 데이터를 갱신하는 경우입니다.

​

사전 정의된 변수 목록(Pre-Defined variables)

이 변수들은 패키지가 작업(Job)으로 실행될 때 Package Variables에 자동으로 설정되는 변수입니다. Select 컴포넌트 등에서 사용하면 실행 시점의 정보를 수집할 수 있습니다.

Pre-Defined Variables	설명
_CLUSTER_ID_S3_ESCAPED	작업이 실행 중인 클러스터 ID(S3용).
_CLUSTER_ID	작업이 실행 중인 클러스터의 ID.
_CLUSTER_NODES_COUNT	작업을 실행하는 클러스터 내의 노드 수.
_JOB_ID	Integrate.io ETL 작업 식별자. 워크플로 내에서 실행되는 태스크의 경우, JOB_ID의 형식은 NNNNNN_component_abcdef가 됩니다.
_JOB_ID_S3_ESCAPED	Integrate.io ETL 작업 식별자(S3용)
_JOB_SUBMISSION_TIMESTAMP	작업이 UTC로 제출된 시각의 ISO-8601 날짜/시각 값. 예: 2013-04-22T14:18:17Z
_JOB_SUBMISSION_TIMESTAMP_S3_ESCAPED	작업이 UTC로 제출된 시각의 S3 이스케이프 날짜/시각 값(S3용). 예: 2013-01-09T14-52-21Z
_JOB_SUBMITTER_EMAIL	작업을 제출한 사용자의 이메일 주소. 예: [e-mail]
_JOB_SUBMITTER_EMAIL_S3_ESCAPED	작업을 제출한 사용자의 이메일 주소(S3용). 예: helpdesk-integrate.io-com
_PACKAGE_OWNER_EMAIL	패키지를 소유한 사용자의 이메일 주소.
_PACKAGE_OWNER_EMAIL_S3_ESCAPED	패키지 소유자의 이메일 주소(S3용).
_ACCOUNT_ID	패키지와 작업이 생성된 계정의 내부 ID.
_ACCOUNT_ID_S3_ESCAPED	패키지와 작업이 생성된 계정의 내부 ID(S3용).
_ACCOUNT_NAME	패키지와 작업이 생성된 계정 이름.
_ACCOUNT_NAME_S3_ESCAPED	패키지와 작업이 생성된 계정 이름(S3용).
_PACKAGE_LAST_SUCCESSFUL_JOB_SUBMISSION_TIMESTAMP	동일 패키지에 대한 마지막 정상 작업의 타임스탬프(UTC, ISO-8601 날짜/시각 형식). 이 변수는 증분 로드에서 이전에 실행된 작업보다 새로운 데이터를 읽어 들이는 데 사용할 수 있습니다.
_WORKFLOW_PACKAGE_LAST_SUCCESSFUL_JOB_SUBMISSION_TIMESTAMP	UTC 기준 동일 워크플로의 마지막 성공 작업 타임스탬프(ISO-8601 날짜/시각 형식). 이 변수는 증분 로드에서 이전 실행 작업보다 새로운 데이터를 읽어 들이는 데 사용할 수 있습니다.
_PARENT_JOB_ID	부모 작업(현재 태스크를 실행 중인 워크플로 작업)의 Integrate.io ETL 작업 식별자.
_PARENT_JOB_ID_S3_ESCAPED	부모 작업의 Integrate.io ETL 작업 식별자(S3용)