이 문서에서는 Dataform Core의 메서드, 속성, 구성 옵션을 설명합니다. SQLX 및 자바스크립트 파일에서 Dataform Core를 사용할 수 있습니다.
assert()
assert
|
(name: string, query?: AContextable
|
|
컴파일된 그래프에 Dataform 어설션을 추가합니다.
|
예를 들면 다음과 같습니다.
// definitions/file.js
assert("name").query(ctx => "select 1");
CommonContext
컨텍스트 메서드는 SQLX 파일 내에서와 같이 컨텍스트가 있는 SQL 코드를 평가할 때나 Dataform Core와 함께 Contextable 인수를 사용할 때 제공됩니다.
database
|
() => string
|
| 해당하는 경우 이 데이터 세트의 데이터베이스를 반환합니다. | |
name
|
() => string
|
| 이 테이블의 이름을 반환합니다. | |
ref
|
(ref: Resolvable | string[], rest: string[]) => string
|
다른 작업을 참조하여 이 작업에 종속 항목으로 추가하고 from 표현식에 사용할 유효한 SQL을 반환합니다.
${ref("database", "schema", "name")}
${ref("schema", "name")}
${ref("name")}
|
|
resolve
|
(ref: Resolvable | string[], rest: string[]) => string
|
ref와 비슷하지만 참조된 작업을 이 작업에 종속 항목으로 추가하지 않습니다.
|
|
self
|
() => string
|
resolve(name())와 같습니다.
이 작업으로 생성된 테이블을 참조하는 데 사용할 수 있는 유효한 SQL 문자열을 반환합니다. |
|
schema
|
() => string
|
| 이 데이터 세트의 스키마를 반환합니다. |
Contextable
컨텍스트가 있는 인수는 일반 유형 T의 일반 값을 전달할 수도 있고, 이 작업 유형의 컨텍스트 객체와 함께 호출되는 함수를 전달할 수도 있습니다.
T | (ctx: Context) => T
Dataform
IProjectConfig 객체가 포함된 전역 변수입니다.
IProjectConfig 속성을 가져오는 데 필요합니다. 예를 들면 다음과 같습니다.
dataform.projectConfig.vars.myVariableName === "myVariableValue"
declare()
declare
|
(dataset: dataform.ITarget)
|
|
데이터 세트를 Dataform 데이터 소스로 선언합니다.
|
예:
// definitions/file.js
declare({name: "a-declaration"})
defaultLocation
defaultLocation 속성은 기본 BigQuery 데이터 세트 위치를 지정합니다. Dataform은 이 위치를 사용하여 코드를 처리하고 결과를 저장합니다. 이 처리 위치는 BigQuery 데이터 세트의 위치와 일치해야 합니다. 하지만 Dataform 저장소 위치와 일치하지 않아도 됩니다.
defaultLocation 속성을 설정하지 않으면 Dataform에서 SQL 쿼리가 참조하는 데이터 세트를 기반으로 위치를 결정합니다. 작동 방식은 다음과 같습니다.
- 쿼리가 동일한 위치의 데이터 세트를 참조하는 경우 Dataform은 해당 위치를 사용합니다.
- 쿼리가 서로 다른 두 개 이상의 위치에서 데이터 세트를 참조하면 오류가 발생합니다. 이 제한사항에 대한 자세한 내용은 리전 간 데이터 세트 복제를 참조하세요.
- 쿼리가 데이터 세트를 참조하지 않는 경우 Dataform의 기본 위치는
US멀티 리전입니다. 다른 위치를 선택하려면defaultLocation속성을 설정합니다. 또는 쿼리에서@@location시스템 변수를 사용합니다.
자세한 내용은 위치 지정을 참고하세요.
IActionConfig
워크플로 작업에 적용되는 Dataform 태그와 종속 항목을 정의합니다.
tags
|
string[]
|
|
작업에 라벨을 지정해야 하는 사용자 정의 태그 목록입니다. |
|
dependencies
|
Resolvable| Resolvable[]
|
|
작업의 종속 항목입니다. |
|
disabled
|
boolean
|
|
true로 설정하면 이 작업이 실행되지 않습니다. 그러나 작업에 여전히 의존할 수 있습니다. 손상된 작업을 일시적으로 사용 중지하는 데 유용합니다. |
IAssertionConfig
assertion 작업 유형의 구성 옵션입니다.
database
|
string
|
| 이 어설션의 해당 뷰를 만들 데이터베이스 (Google Cloud 프로젝트 ID)입니다. | |
description
|
string
|
| 이 어설션에 대한 설명입니다. | |
disabled
|
boolean
|
true로 설정하면 이 작업이 실행되지 않습니다.
작업에 여전히 의존할 수 있습니다. 손상된 작업을 일시적으로 사용 중지하는 데 유용합니다.
|
|
hermetic
|
boolean
|
| 이 작업의 밀폐 여부를 선언합니다. 모든 종속 항목이 명시적으로 선언된 작업은 밀폐된 작업입니다.
이 작업이 종속 항목으로 선언되지 않은 소스의 데이터에 의존하는 경우 |
|
schema
|
string
|
| 이 어설션의 해당 뷰를 만들 스키마(BigQuery 데이터 세트)입니다. | |
tags
|
string[]
|
| 이 작업에 적용된 사용자 정의 태그 목록입니다. |
IBigQueryOptions
BigQuery 전용 웨어하우스 옵션입니다.
additionalOptions
|
|
| 테이블, 뷰, 구체화된 뷰 옵션의 키-값 쌍입니다.
문자열 값은 큰따옴표로 묶어야 합니다. 예:
옵션 이름에 특수문자가 포함되어 있으면 이름을 따옴표로 묶습니다.
예: |
|
clusterBy
|
string[]
|
| 파티션 클러스터링 기준을 지정하는 키입니다. | |
labels
|
|
| BigQuery 라벨의 키-값 쌍입니다.
라벨 이름에 하이픈 같은 특수 문자가 포함되어 있으면 이름을 따옴표로 묶습니다(예: |
|
partitionBy
|
string
|
| 테이블 파티션 나누기에 사용할 키입니다. 일반적으로 타임스탬프 또는 날짜 열의 이름입니다. | |
partitionExpirationDays
|
number
|
| BigQuery가 각 파티션에 데이터를 저장하는 기간(일)입니다. 이 설정은 테이블의 모든 파티션에 적용되지만 파티션 시간을 기준으로 각 파티션과 별도로 계산됩니다. | |
requirePartitionFilter
|
boolean
|
파티션을 나눈 테이블에 파티션 나누기 열을 필터링하는 WHERE 절 조건자 필터가 필요한지 선언합니다.
|
|
updatePartitionFilter
|
string
|
| 증분 업데이트 적용 시점에 대한 SQL 기반 필터입니다. | |
iceberg
|
IIcebergOptions
|
| Iceberg 관리형 테이블의 Apache Iceberg 관련 옵션입니다. |
IIcebergOptions
Iceberg 관리형 테이블의 Apache Iceberg 관련 옵션입니다.
connection |
string |
|
(선택사항) 외부 스토리지를 읽고 쓰는 사용자 인증 정보를 제공하는 Cloud Storage 연결의 리소스 이름입니다. 다음과 같은 방법으로 형식을 지정할 수 있습니다.
기본값은 |
|
file_format
|
string
|
|
(선택사항) 테이블 데이터의 파일 형식입니다.
|
|
bucket_name
|
string
|
|
테이블 또는 워크플로 수준에서 필요합니다. 테이블 데이터가 저장되는 Cloud Storage 버킷의 이름입니다.
테이블 정의 파일의 |
|
table_folder_root
|
string
|
|
(선택사항) 테이블 데이터가 저장되는 Cloud Storage 버킷 내의 첫 번째 수준 폴더 이름입니다.
이 속성을 설정하지 않으면 Dataform은 설정된 경우 |
|
table_folder_subpath
|
string
|
|
(선택사항)
이 속성을 설정하지 않으면 Dataform은 |
이러한 값은 gs://BUCKET_NAME/TABLE_FOLDER_ROOT/TABLE_FOLDER_SUBPATH 형식으로 Cloud Storage URI를 구성합니다.
IColumnsDescriptor
테이블의 열을 설명합니다.
{ [name]: string | IRecordDescriptor }
IDeclarationConfig
declaration 작업 유형의 구성 옵션입니다.
columns
|
IColumnsDescriptor
|
| 테이블 내의 열에 대한 설명입니다. | |
database
|
string
|
| 소스 테이블이 있는 데이터베이스 (Google Cloud 프로젝트 ID)입니다. | |
description
|
string
|
| 테이블 설명입니다. | |
schema
|
string
|
| 소스 테이블이 있는 스키마(BigQuery 데이터 세트)입니다. |
IDependenciesConfig
워크플로 작업의 종속 항목을 정의합니다.
dependencies
|
Resolvable| Resolvable[]
|
|
이 작업의 명시적 종속 항목이 하나 이상 있습니다. 종속 항목 작업은 종속 작업 전에 실행됩니다.
대부분의 종속 항목은 |
|
hermetic
|
boolean
|
|
이 작업의 밀폐 여부를 선언합니다. 모든 종속 항목이 명시적으로 선언된 작업은 밀폐된 작업입니다. 이 작업이 종속 항목으로 선언되지 않은 소스의 데이터에 의존하는 경우 |
IDocumentableConfig
데이터 세트와 해당 열에 대한 설명을 정의합니다.
columns
|
IColumnsDescriptor
|
|
데이터 세트의 열에 대한 설명입니다. |
|
description
|
string
|
|
데이터 세트에 대한 설명 |
INamedConfig
워크플로 작업의 유형과 이름을 정의합니다.
type
|
string
|
|
작업의 유형입니다. |
|
name
|
string
|
|
작업의 이름입니다. |
IOperationConfig
operations 작업 유형의 구성 옵션입니다.
columns
|
IColumnsDescriptor
|
| 테이블 내의 열에 대한 설명입니다. | |
database
|
string
|
| 이 작업의 출력을 만들 데이터베이스 (Google Cloud 프로젝트 ID)입니다. | |
description
|
string
|
| 테이블 설명입니다. | |
disabled
|
boolean
|
true로 설정하면 이 작업이 실행되지 않습니다.
작업에 여전히 의존할 수 있습니다.
손상된 작업을 일시적으로 사용 중지하는 데 유용합니다.
|
|
hasOutput
|
boolean
|
이 operations 작업이 ref 함수를 사용하여 참조할 수 있는 테이블을 만들도록 선언합니다.
create or replace table ${self()} as select ...
|
|
hermetic
|
boolean
|
| 이 작업의 밀폐 여부를 선언합니다. 모든 종속 항목이 명시적으로 선언된 작업은 밀폐된 작업입니다.
이 작업이 종속 항목으로 선언되지 않은 소스의 데이터에 의존하는 경우 |
|
schema
|
string
|
| 이 작업의 출력을 만들 스키마(BigQuery 데이터 세트)입니다. | |
tags
|
string[]
|
| 이 작업에 적용된 사용자 정의 태그 목록입니다. |
IProjectConfig
Dataform 저장소의 컴파일 설정을 포함합니다.
defaultDatabase
|
string
|
| 필수 항목입니다. 기본 데이터베이스 (Google Cloud 프로젝트 ID)입니다. | |
defaultSchema
|
string
|
| 필수 항목입니다. 기본 스키마(BigQuery 데이터 세트 ID)입니다. | |
defaultLocation
|
string
|
| (선택사항) Dataform이 테이블을 만드는 기본 BigQuery 위치입니다. | |
assertionSchema
|
string
|
| 필수 항목입니다. 어설션의 기본 스키마(BigQuery 데이터 세트 ID)입니다. | |
vars
|
map (key: string, value: string)
|
(선택사항) 컴파일 중에 프로젝트 코드에서 사용할 수 있는 사용자 정의 변수입니다.
"key": value 쌍 목록을 포함하는 객체입니다.
예: { "name": "wrench", "mass": "1.3kg", "count": "3" }
|
|
databaseSuffix
|
string
|
| (선택사항) 모든 데이터베이스(Google Cloud 프로젝트 ID) 이름에 추가해야 하는 서픽스입니다. | |
schemaSuffix
|
string
|
| (선택사항) 모든 스키마(BigQuery 데이터 세트 ID) 이름에 추가해야 하는 서픽스입니다. | |
tablePrefix
|
string
|
| (선택사항) 모든 테이블 이름 앞에 추가되어야 하는 프리픽스입니다. | |
defaultIcebergConfig
|
object
|
(선택사항) Apache Iceberg 관리형 테이블의 워크플로 수준 기본값입니다.
다음 필드가 포함됩니다.
|
|
preserveGovernanceControls
|
boolean
|
(선택사항) true로 설정하면 Dataform은 저장소의 모든 테이블에 대해 워크플로 실행 전반에서 기존 BigQuery 데이터 정책 및 데이터 거버넌스 태그 (미리보기)를 자동으로 보존합니다.
|
|
warehouse
|
string
|
필수 항목입니다. bigquery로 설정해야 합니다.
|
저장소 수준에서 워크플로 설정에 IProjectConfig 속성을 설정할 수 있습니다.
개별 테이블의 defaultSchema 및 defaultDatabase 속성을 재정의할 수 있습니다.
SQLX 또는 자바스크립트 파일의 SQL SELECT 문에서 모든 IProjectConfig 속성에 액세스할 수 있습니다.
다음 코드 샘플은 워크플로 설정에 projectConfig.vars 속성으로 설정된 myVariableName 커스텀 컴파일 변수를 SQLX 파일의 SELECT 문에서 액세스하는 것을 보여줍니다.
config { type: "view" }
SELECT ${when(
dataform.projectConfig.vars.myVariableName === "myVariableValue",
"myVariableName is set to myVariableValue!",
"myVariableName is not set to myVariableValue!"
)}
개별 컴파일 결과의 프로젝트 구성 설정을 재정의하는 방법은 Dataform API의 CodeCompilationConfig REST 리소스를 참조하세요.
IRecordDescriptor
중첩 열이 있는 테이블의 구조체, 객체 또는 레코드를 설명합니다.
bigqueryPolicyTags
|
string | string[]
|
| 이 열에 적용된 BigQuery 정책 태그의 전체 식별자입니다. BigQuery 정책 태그의 전체 식별자에는 프로젝트 이름, 위치, 분류가 포함됩니다.
예: |
|
columns
|
IColumnsDescriptor
|
| 구조체, 객체 또는 레코드 내의 열에 대한 설명입니다. | |
description
|
string
|
| 구조체, 객체 또는 레코드에 대한 설명입니다. |
ITableAssertions
테이블 정의의 일부로 어설션을 만드는 옵션입니다.
nonNull
|
string | string[]
|
NULL이 될 수 없는 열입니다.
설정되면 이러한 열에 |
|
rowConditions
|
string[]
|
| 테이블의 모든 행에서 true여야 하는 일반 조건입니다.
설정되면 이러한 조건을 위반하는 행이 하나라도 있는 경우 해당 어설션이 실패합니다. |
|
uniqueKey
|
string | string[]
|
| 테이블의 고유 키 색인을 구성하는 열입니다.
설정되면 테이블에서 이러한 모든 열에 대해 동일한 값을 갖는 행이 둘 이상 있는 경우 결과 어설션이 실패합니다. |
|
uniqueKeys
|
[]
|
| 테이블의 고유 키 색인을 구성하는 열 조합입니다.
설정되면 테이블에서 고유 키의 모든 열에 대해 동일한 값을 갖는 행이 둘 이상 있는 경우 결과 어설션이 실패합니다. |
ITableConfig
table, view, incremental 테이블 유형을 비롯한 table 작업의 구성 옵션입니다.
IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig 및 ITargetableConfig를 확장합니다.
assertions
|
ITableAssertions
|
| 테이블에서 실행할 어설션입니다.
구성된 경우 관련 어설션이 자동으로 생성되고 이 테이블의 종속 항목으로 실행됩니다. |
|
bigquery
|
IBigQueryOptions
|
| BigQuery 전용 웨어하우스 옵션입니다. | |
columns
|
IColumnsDescriptor
|
| 테이블 내의 열에 대한 설명입니다. | |
database
|
string
|
| 이 작업의 출력을 만들 데이터베이스 (Google Cloud 프로젝트 ID)입니다. | |
description
|
string
|
| 테이블 설명입니다. | |
disabled
|
boolean
|
true로 설정하면 이 작업이 실행되지 않습니다.
작업에 여전히 의존할 수 있습니다.
손상된 작업을 일시적으로 사용 중지하는 데 유용합니다.
|
|
hermetic
|
boolean
|
| 이 작업의 밀폐 여부를 선언합니다. 모든 종속 항목이 명시적으로 선언된 작업은 밀폐된 작업입니다.
이 작업이 종속 항목으로 선언되지 않은 소스의 데이터에 의존하는 경우 |
|
materialized
|
boolean
|
테이블 유형이 view인 경우에만 유효합니다.
true로 설정하면 구체화된 뷰가 생성됩니다. |
|
onSchemaChange
|
onSchemaChange
|
테이블 유형이 incremental인 경우에만 유효합니다.
Dataform이 이 기능은 미리보기 상태입니다. |
|
preserveGovernanceControls
|
boolean
|
(선택사항) true로 설정하면 Dataform은 전체 새로고침 중에 테이블, 뷰 또는 증분 테이블을 다시 만들 때 기존 BigQuery 데이터 정책 및 데이터 거버넌스 태그 (미리보기)를 백업하고 다시 적용합니다. workflow_settings.yaml에 설정된 워크플로 수준 기본값보다 우선합니다.
|
|
protected
|
boolean
|
incremental 테이블 유형에만 허용됩니다.
true로 설정하면 이 작업을 실행할 때 |
|
schema
|
string
|
| 이 작업의 출력을 만들 스키마(BigQuery 데이터 세트)입니다. | |
tags
|
string[]
|
| 이 작업에 적용된 사용자 정의 태그 목록입니다. | |
type
|
TableType
|
| 테이블의 유형입니다. | |
uniqueKey
|
string[]
|
| 증분 테이블에 대한 병합 기준의 고유 키입니다.
구성된 경우 고유 키가 일치하는 레코드에 대해 새 행을 삽입하지 않고 업데이트를 수행합니다. |
ITableContext
컨텍스트 메서드는 SQLX 파일 내에서와 같이 컨텍스트가 있는 SQL 코드를 평가할 때나 Dataform Core와 함께 Contextable 인수를 사용할 때 제공됩니다.
incremental
|
() => boolean
|
| 현재 컨텍스트가 테이블이 증분적으로 빌드됨을 나타내면 true를 반환합니다. | |
name
|
() => string
|
| 이 테이블의 정규화된 이름을 반환합니다. | |
ref
|
(ref: Resolvable | string[], rest: string[]) => string
|
| 다른 작업을 참조하여 이 작업에 종속 항목으로 추가하고 from 표현식에 사용할 유효한 SQL을 반환합니다.
${ref({ name: "name", schema: "schema", database: "database" })}
값이 두 개만 제공되면 기본 데이터베이스가 사용되고 값이 값이 하나만 제공되면 기본 데이터베이스 스키마가 사용되고 제공된 값이 `"name"`으로 해석됩니다. ${ref("database", "schema", "name")}
${ref("schema", "name")}
${ref("name")}
|
|
resolve
|
(ref: Resolvable | string[], rest: string[]) => string
|
ref와 비슷하지만 종속 항목을 추가하는 대신 `from` 표현식과 같이 SQL에서 사용할 수 있도록 제공된 참조를 해석합니다.
|
|
self
|
() => string
|
resolve(name())와 같습니다.
이 작업으로 생성된 테이블을 참조하는 데 사용할 수 있는 유효한 SQL 문자열을 반환합니다. |
|
when
|
(cond: boolean, trueCase: string, falseCase: string) => string
|
if 조건의 약식 표기입니다.
cond ? trueCase : falseCase와 같습니다.
|
ITarget
BigQuery 내의 테이블에 대한 참조입니다.
database
|
string
|
name
|
string
|
schema
|
string
|
ITargetableConfig
워크플로 작업의 대상 데이터베이스 및 스키마를 정의합니다.
database
|
string
|
|
이 작업의 출력을 만들어야 하는 데이터베이스입니다. BigQuery로 설정해야 합니다. |
|
schema
|
string
|
|
이 작업의 출력을 만들어야 하는 스키마입니다. |
onSchemaChange
onSchemaChange 속성을 설정하면 Dataform에서 SELECT 쿼리를 확인하여 열이 추가되었는지 또는 삭제되었는지 확인합니다.
그런 다음 Dataform은 onSchemaChange 속성 값으로 지정된 작업을 수행합니다. 작업을 다음 중 하나로 설정할 수 있습니다.
IGNORE(기본값): 추가된 열을 무시하고 누락된 열에 대한 오류를 표시합니다.onSchemaChange이 설정되지 않은 경우 스키마가 변경될 때 기본 동작입니다.FAIL: Dataform이 스키마 변경사항을 감지하면 작업을 중지하여 스키마를 일관되게 유지합니다.EXTEND: 쿼리의 새 열을 증분 테이블에 추가하고 이전 레코드에NULL값을 추가합니다. 열이 쿼리의 원래 스키마에서 삭제되거나 누락된 경우 오류를 표시합니다. 이 설정을 사용하여 런타임 중에 증분 테이블에 새 열을 추가할 수 있습니다.SYNCHRONIZE: 쿼리의 새 열을 증분 테이블에 추가하고 이전 레코드에NULL값을 추가합니다. 원래 스키마에 있었지만 현재 쿼리에서 누락된 열을 삭제합니다.
operate()
operate
|
(name: string, queries?: Contextable
|
|
SQL 작업을 정의합니다.
|
예를 들면 다음과 같습니다.
// definitions/file.js
operate("an-operation", ["SELECT 1", "SELECT 2"])
publish()
publish
|
(name: string, queryOrConfig?: Contextable
|
|
테이블 또는 뷰를 만듭니다.
|
예를 들면 다음과 같습니다.
// definitions/file.js
publish("published-table", {
type: "table",
dependencies: ["a-declaration"],
}).query(ctx => "SELECT 1 AS test");
Resolvable
해석 가능 항목은 string 유형의 테이블 이름 또는 관계의 전체 경로를 설명하는 객체일 수 있습니다.
string | ITarget
TableType
지원되는 테이블 작업 유형입니다.
view 유형의 테이블은 뷰로 생성됩니다.
table 유형의 테이블은 테이블로 생성됩니다.
incremental 유형의 테이블은 where 절을 포함해야 합니다.
자세한 내용은 증분 테이블 구성을 참고하세요.