Cloud Storage, Azure Blob Storage 또는 Amazon Simple Storage Service(Amazon S3)에서 데이터 전송을 설정할 때 URI(또는 데이터 경로)와 대상 테이블을 매개변수화할 수 있습니다. 매개변수화는 날짜별로 정리된 버킷에서 데이터를 로드할 수 있게 해줍니다. 쿼리 매개변수와 구분하기 위해 이러한 매개변수를 런타임 매개변수라고 합니다.
전송에서 런타임 매개변수를 사용할 때 다음을 수행할 수 있습니다.
대상 테이블의 파티션을 나누는 방식 지정
특정 날짜와 일치하는 파일 검색
사용 가능한 런타임 매개변수
Cloud Storage, Blob Storage 또는 Amazon S3 전송을 설정할 때 런타임 매개변수를 사용하여 대상 테이블의 파티션을 나누는 방법을 지정할 수 있습니다.
매개변수
템플릿 유형
값
run_time
형식이 지정된 타임스탬프
일정에 따라 UTC 시간으로 표시됩니다. 정기적인 예약된 전송에서 run_time은 의도한 실행 시간을 나타냅니다. 예를 들어 전송이 '24시간마다'로 설정된 경우 실제 실행 시간은 약간 다를 수 있지만 연속된 두 쿼리 간의 run_time 차이는 정확히 24시간입니다.
테이블 스키마를 만들 때 파티션 나누기 열을 TIMESTAMP 또는 DATE 열로 지정합니다.
매개변수 사용에 대한 참고 사항
현지 시간대를 기준으로 데이터의 파티션을 나누는 경우 템플릿 문법의 오프셋 메커니즘을 사용하여 UTC와의 시차를 수동으로 계산해야 합니다.
매개변수에 분을 지정할 수 없습니다.
대상 테이블 이름의 매개변수와 함께 URI 또는 데이터 경로에 와일드 카드를 사용할 수 있습니다.
런타임 매개변수 예시
다음 예시에서는 일반 사용 사례에 와일드 카드 문자와 매개변수를 결합하는 방법을 보여줍니다. 테이블의 이름이 mytable이고 모든 예시에서 run_time이 2018-02-15 00:00:00(UTC)라고 가정합니다.
파티션을 나누지 않은 테이블로 데이터 전송
이 사용 사례에서는 Cloud Storage, Blob Storage, 또는 Amazon S3 버킷의 새 파일을 파티션을 나누지 않은 테이블에 로드합니다. 이 예시에서는 URI 또는 데이터 경로에 와일드 카드를 사용하고 임시 새로고침 전송을 사용하여 새 파일을 선택합니다.
데이터 소스
소스 URI 또는 데이터 경로
대상 테이블 이름
Cloud Storage
gs://bucket/*.csv
mytable
Amazon S3
s3://bucket/*.csv
mytable
Blob 스토리지
*.csv
mytable
모든 데이터 스냅샷을 수집 시간으로 파티션을 나눈 테이블에 로드
이 경우 지정된 URI 또는 데이터 경로의 모든 데이터는 오늘 날짜로 파티션을 나눈 테이블에 전송됩니다. 새로고침 전송에서 이 구성은 마지막 로드 이후에 추가된 파일을 가져와서 특정 파티션에 추가합니다.
데이터 소스
소스 URI 또는 데이터 경로
매개변수화된 대상 테이블 이름
평가된 대상 테이블 이름
Cloud Storage
gs://bucket/*.csv
mytable${run_time|"%Y%m%d"}
mytable$20180215
Amazon S3
s3://bucket/*.csv
mytable${run_time|"%Y%m%d"}
mytable$20180215
Blob 스토리지
*.csv
mytable${run_time|"%Y%m%d"}
mytable$20180215
이 사용 사례에서는 오늘 날짜의 데이터를 오늘 날짜로 파티션을 나눈 테이블에 전송합니다.
이 예시는 특정 날짜와 일치하는 새로 추가된 파일을 검색하여 데이터를 해당 파티션에 로드하는 새로 고침 전송에도 적용됩니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eRuntime parameters allow for the parameterization of URIs/data paths and destination tables in Cloud Storage, Azure Blob Storage, and Amazon S3 transfers, enabling the loading of data from date-organized buckets.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003erun_time\u003c/code\u003e and \u003ccode\u003erun_date\u003c/code\u003e parameters can be used to specify how to partition the destination table and retrieve files that match a particular date, with \u003ccode\u003erun_date\u003c/code\u003e providing a date string in \u003ccode\u003eYYYYMMDD\u003c/code\u003e format.\u003c/p\u003e\n"],["\u003cp\u003eThe templating syntax \u003ccode\u003e{run_date}\u003c/code\u003e and \u003ccode\u003e{run_time[+\\-offset]|"time_format"}\u003c/code\u003e are supported for destination table names, with \u003ccode\u003erun_time\u003c/code\u003e allowing time offsets and custom formatting.\u003c/p\u003e\n"],["\u003cp\u003ePartitioned tables can be ingestion-time partitioned (based on transfer run time) or column-partitioned (based on a \u003ccode\u003eTIMESTAMP\u003c/code\u003e or \u003ccode\u003eDATE\u003c/code\u003e column), but minutes cannot be specified for partitioning.\u003c/p\u003e\n"],["\u003cp\u003eWildcards in the source URI or data path can be used in conjunction with destination table parameters to transfer data, making it flexible for transferring data into non-partitioned or partitioned tables.\u003c/p\u003e\n"]]],[],null,["# Runtime parameters in Cloud Storage transfers\n=============================================\n\nWhen you set up a data transfer in Cloud Storage, Azure Blob Storage, or\nAmazon Simple Storage Service (Amazon S3), you can parameterize the URI (or data path) and the destination\ntable. Parameterizing lets you load data from buckets that are organized by\ndate. These parameters are referred to as *runtime parameters* to distinguish\nthem from query parameters.\n\nWhen you use runtime parameters in a transfer, you can do the following:\n\n- Specify how you want to partition the destination table\n- Retrieve files that match a particular date\n\nAvailable runtime parameters\n----------------------------\n\nWhen you set up the Cloud Storage, Blob Storage, or\nAmazon S3 transfer, you can specify how you want to partition the\ndestination table by using runtime parameters.\n\nTemplating system\n-----------------\n\nCloud Storage, Blob Storage, and Amazon S3 transfers\nsupport runtime parameters in the destination table name by using a templating\nsyntax.\n\n#### Parameter templating syntax\n\nThe templating syntax supports basic string templating and time offsetting. Parameters are\nreferenced in the following formats:\n\n- `{run_date}`\n- `{run_time[+\\-offset]|\"time_format\"}`\n\n**Usage notes:**\n\n- No whitespace is allowed between run_time, offset, and time format.\n- To include literal curly braces in the string, you can escape them as `'\\{' and '\\}'`.\n- To include literal quotes or a vertical bar in the time_format, such as `\"YYYY|MM|DD\"`, you can escape them in the format string as: `'\\\"'` or `'\\|'`.\n\n#### Parameter templating examples\n\nThese examples demonstrate specifying destination table names with different time formats, and offsetting the run time.\n\nPartitioning options\n--------------------\n\nThere are two types of partitioned tables in BigQuery:\n\n- **Tables that are partitioned by ingestion time.** For Cloud Storage, Blob Storage, and Amazon S3 transfers, the ingestion time is the transfer's run time.\n- **Tables that are partitioned based on a column.** The column type must be a [`TIMESTAMP`](/bigquery/docs/reference/standard-sql/data-types#timestamp_type) or [`DATE`](/bigquery/docs/reference/standard-sql/data-types#date_type) column.\n\nIf the destination table is partitioned on a column, you identify the\npartitioning column when you create the destination table and specify its\nschema. Learn more about creating column-based partitioned tables in\n[Creating and using partitioned tables](/bigquery/docs/creating-column-partitions).\n| **Note:** Minutes cannot be specified when partitioning a table.\n\n### Partitioning examples\n\n- Table with no partitioning\n - Destination table: `mytable`\n- [Ingestion-time partitioned table](/bigquery/docs/partitioned-tables#ingestion_time)\n - Destination table: `mytable`\u003cvar translate=\"no\"\u003e$YYYYMMDD\u003c/var\u003e\n - Note that minutes cannot be specified.\n- [Column-partitioned table](/bigquery/docs/partitioned-tables#date_timestamp_partitioned_tables)\n - Destination table: `mytable`\n - Specify the partitioning column as a `TIMESTAMP` or `DATE` column when you create the table's schema.\n\nNotes on parameter usage\n------------------------\n\n- If you partition your data based on your local timezone, you need to manually calculate the hour offset from UTC by using the offsetting mechanism in the [templating syntax](#templating_system).\n- Minutes cannot be specified in parameters.\n- Using wildcards for the URI or data path in combination with parameters on the destination table name is allowed.\n\nRuntime parameter examples\n--------------------------\n\nThe following examples show ways to combine the wildcard character and\nparameters for common use cases. Assume the table's name is `mytable` and\nthe `run_time` is `2018-02-15 00:00:00` (UTC) for all examples.\n\n### Transfer data to a non-partitioned table\n\nThis use case applies to loading new files from a Cloud Storage,\nBlob Storage, or Amazon S3 bucket into a non-partitioned\ntable. This example uses a wildcard in the URI or data path and uses an ad hoc\nrefresh transfer to pick up new files.\n\n### Load a snapshot of all data into an ingestion-time partitioned table\n\nIn this case, all data in the specified URI or data path is transferred to a\ntable partitioned by today's date. In a refresh transfer, this configuration\npicks up files added since the last load and adds them to a particular\npartition.\n\nThis use case transfers today's data into a table partitioned on today's date.\nThis example also applies to a refresh transfer that retrieves newly added files\nthat match a certain date and loads the data into the corresponding partition.\n\nWhat's next\n-----------\n\n- Learn about [setting up a Cloud Storage transfer](/bigquery/docs/cloud-storage-transfer).\n- Learn more about the [BigQuery Data Transfer Service](/bigquery/docs/dts-introduction)."]]
