Dataform Core 참조

이 문서에서는 Dataform Core의 메서드, 속성, 구성 옵션을 설명합니다. SQLX 및 자바스크립트 파일에서 Dataform Core를 사용할 수 있습니다.

assert()

assert	(name: string, query?: AContextable)
	컴파일된 그래프에 Dataform 어설션을 추가합니다. /definitions 디렉터리에서만 사용할 수 있습니다.

예:

// 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을 반환합니다. Resolvable 객체를 사용하여 이 함수를 호출할 수 있습니다. 예: ${ref({ name: "name", schema: "schema", database: "database" })} "database", "schema", "name" 값에 개별 인수를 사용하여 이 함수를 호출할 수도 있습니다. 값이 두 개만 제공되면 기본 데이터베이스가 사용되고 값이 "schema" 및 "name"으로 해석됩니다. 값이 하나만 제공되면 기본 데이터베이스와 스키마가 사용되고 제공된 값이 `"name"`으로 해석됩니다. ${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 디렉터리에서만 사용할 수 있습니다.

예:

// definitions/file.js

declare({name: "a-declaration"})

IActionConfig

SQL 워크플로 작업에 적용되는 Dataform 태그 및 종속 항목을 정의합니다.

tags	string[]
	작업에 라벨을 지정해야 하는 사용자 정의 태그 목록입니다.
dependencies	Resolvable| Resolvable[]
	작업의 종속 항목입니다.
disabled	boolean
	true로 설정하면 이 작업이 실행되지 않습니다. 그러나 작업에 여전히 의존할 수 있습니다. 손상된 작업을 일시적으로 사용 중지하는 데 유용합니다.

IAssertionConfig

assertion 작업 유형의 구성 옵션입니다.

database	string
	이 어설션의 해당 뷰를 만들 데이터베이스(Google Cloud 프로젝트 ID)입니다.
description	string
	이 어설션에 대한 설명입니다.
disabled	boolean
	true로 설정하면 이 작업이 실행되지 않습니다. 작업에 여전히 의존할 수 있습니다. 손상된 작업을 일시적으로 사용 중지하는 데 유용합니다.
hermetic	boolean
	이 작업의 밀폐 여부를 선언합니다. 모든 종속 항목이 명시적으로 선언된 작업은 밀폐된 작업입니다. 이 작업이 종속 항목으로 선언되지 않은 소스의 데이터에 의존하는 경우 hermetic을 false로 설정하세요. 그렇지 않으면 true로 설정합니다.
schema	string
	이 어설션의 해당 뷰를 만들 스키마(BigQuery 데이터 세트)입니다.
tags	string[]
	이 작업에 적용된 사용자 정의 태그 목록입니다.

IBigQueryOptions

BigQuery 전용 웨어하우스 옵션입니다.

additionalOptions
	테이블, 뷰, 구체화된 뷰 옵션의 키-값 쌍입니다. partitionExpirationDays와 같은 일부 옵션에는 전용 유형/유효성 검사 필드가 있습니다. 이러한 옵션에는 전용 필드를 사용합니다. 문자열 값은 큰따옴표로 묶어야 합니다. 예: additionalOptions: {numeric_option: "5", string_option: '"string-value"'} 옵션 이름에 특수문자가 포함되어 있으면 이름을 따옴표로 묶습니다. 예: additionalOptions: { "option-name": "value" }.
clusterBy	string[]
	파티션 클러스터링 기준을 지정하는 키입니다.
labels
	BigQuery 라벨의 키-값 쌍입니다. 라벨 이름에 하이픈 같은 특수 문자가 포함되어 있으면 이름을 따옴표로 묶습니다. 예: labels: { "label-name": "value" }.
partitionBy	string
	테이블 파티션 나누기에 사용할 키입니다. 일반적으로 타임스탬프 또는 날짜 열의 이름입니다.
partitionExpirationDays	number
	BigQuery가 각 파티션에 데이터를 저장하는 기간(일)입니다. 이 설정은 테이블의 모든 파티션에 적용되지만 파티션 시간을 기준으로 각 파티션과 별도로 계산됩니다.
requirePartitionFilter	boolean
	파티션을 나눈 테이블에 파티션 나누기 열을 필터링하는 WHERE 절 조건자 필터가 필요한지 여부를 선언합니다.
updatePartitionFilter	string
	증분 업데이트 적용 시점에 대한 SQL 기반 필터입니다.

IColumnsDescriptor

테이블의 열을 설명합니다.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

declaration 작업 유형의 구성 옵션입니다.

columns	IColumnsDescriptor
	테이블 내의 열에 대한 설명입니다.
database	string
	소스 테이블이 있는 데이터베이스(Google Cloud 프로젝트 ID)입니다.
description	string
	테이블 설명입니다.
schema	string
	소스 테이블이 있는 스키마(BigQuery 데이터 세트)입니다.

IDependenciesConfig

SQL 워크플로 작업의 종속 항목을 정의합니다.

dependencies	Resolvable| Resolvable[]
	이 작업에 대한 하나 이상의 명시적 종속 항목입니다. 종속 항목 작업은 종속 작업 전에 실행됩니다. 대부분의 종속 항목은 ref 함수를 사용한 부산물로 선언되므로 일반적으로 설정되지 않은 상태로 유지됩니다.
hermetic	boolean
	이 작업의 기본 제공 여부를 선언합니다. 모든 종속 항목이 명시적으로 선언된 작업은 밀폐된 작업입니다. 이 작업이 종속 항목으로 선언되지 않은 소스의 데이터에 의존하는 경우 hermetic을 명시적으로 false로 설정해야 합니다. 그렇지 않고 이 작업이 명시적으로 선언된 종속 항목의 데이터에만 의존하는 경우 true로 설정해야 합니다.

IDocumentableConfig

데이터 세트와 해당 열에 대한 설명을 정의합니다.

columns	IColumnsDescriptor
	데이터 세트의 열에 대한 설명입니다.
description	string
	데이터 세트에 대한 설명

INamedConfig

SQL 워크플로 작업의 유형과 이름을 정의합니다.

type	string
	작업의 유형입니다.
name	string
	작업의 이름입니다.

IOperationConfig

operations 작업 유형의 구성 옵션입니다.

columns	IColumnsDescriptor
	테이블 내의 열에 대한 설명입니다.
database	string
	이 작업의 출력을 만들 데이터베이스(Google Cloud 프로젝트 ID)입니다.
description	string
	테이블 설명입니다.
disabled	boolean
	true로 설정하면 이 작업이 실행되지 않습니다. 작업에 여전히 의존할 수 있습니다. 손상된 작업을 일시적으로 사용 중지하는 데 유용합니다.
hasOutput	boolean
	이 operations 작업이 ref 함수를 사용하여 참조할 수 있는 테이블을 만들도록 선언합니다. true로 설정하면 이 작업은 self() 컨텍스트 함수를 사용하여 구성된 이름으로 테이블을 만듭니다. 예: create or replace table ${self()} as select ...
hermetic	boolean
	이 작업의 밀폐 여부를 선언합니다. 모든 종속 항목이 명시적으로 선언된 작업은 밀폐된 작업입니다. 이 작업이 종속 항목으로 선언되지 않은 소스의 데이터에 의존하는 경우 hermetic을 false로 설정하세요. 그렇지 않으면 true로 설정합니다.
schema	string
	이 작업의 출력을 만들 스키마(BigQuery 데이터 세트)입니다.
tags	string[]
	이 작업에 적용된 사용자 정의 태그 목록입니다.

IProjectConfig

Dataform 저장소의 컴파일 설정을 포함합니다.

defaultDatabase	string
	필수 항목입니다. 기본 데이터베이스(Google Cloud 프로젝트 ID)입니다.
defaultSchema	string
	필수 항목입니다. 기본 스키마(BigQuery 데이터 세트 ID)입니다.
defaultLocation	string
	필수 항목입니다. 사용할 기본 BigQuery 위치입니다. BigQuery 위치에 대한 자세한 내용은 https://cloud.google.com/bigquery/docs/locations를 참조하세요.
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
	선택사항입니다. 모든 테이블 이름 앞에 추가되어야 하는 프리픽스입니다.
warehouse	string
	필수 항목입니다. bigquery로 설정해야 합니다.

저장소 수준에서 dataform.json에 IProjectConfig 속성을 설정할 수 있습니다.

개별 테이블의 defaultSchema 및 defaultDatabase 속성을 재정의할 수 있습니다.

SQLX 또는 자바스크립트 파일의 SQL SELECT 문에서 모든 IProjectConfig 속성에 액세스할 수 있습니다.

다음 코드 샘플은 dataform.json에 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의 projects.locations.repositories.compilationResults#CodeCompilationConfig REST 리소스를 참조하세요.

IRecordDescriptor

중첩 열이 있는 테이블의 구조체, 객체 또는 레코드를 설명합니다.

bigqueryPolicyTags	string | string[]
	이 열에 적용된 BigQuery 정책 태그의 전체 식별자입니다. BigQuery 정책 태그의 전체 식별자에는 프로젝트 이름, 위치, 분류가 포함됩니다. 예: "projects/1/locations/eu/taxonomies/2/policyTags/3" 현재 BigQuery는 한 열에 태그 하나를 지원합니다.
columns	IColumnsDescriptor
	구조체, 객체 또는 레코드 내의 열에 대한 설명입니다.
description	string
	구조체, 객체 또는 레코드에 대한 설명입니다.

ITableAssertions

테이블 정의의 일부로 어설션을 만드는 옵션입니다.

nonNull	string | string[]
	NULL이 될 수 없는 열입니다. 설정되면 이러한 열에 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
	이 작업의 밀폐 여부를 선언합니다. 모든 종속 항목이 명시적으로 선언된 작업은 밀폐된 작업입니다. 이 작업이 종속 항목으로 선언되지 않은 소스의 데이터에 의존하는 경우 hermetic을 false로 설정하세요. 그렇지 않으면 true로 설정합니다.
materialized	boolean
	테이블 유형이 view인 경우에만 유효합니다. true로 설정하면 구체화된 뷰가 생성됩니다.
protected	boolean
	incremental 테이블 유형에만 허용됩니다. true로 설정하면 이 작업을 실행할 때 full-refresh 옵션을 무시합니다. 이 방법은 임시 데이터로 빌드한 테이블에서 과거 데이터가 손실되지 않도록 하는 데 유용합니다.
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을 반환합니다. Resolvable 객체를 사용하여 이 함수를 호출할 수 있습니다. 예: ${ref({ name: "name", schema: "schema", database: "database" })} "database", "schema", "name" 값에 개별 인수를 사용하여 이 함수를 호출할 수도 있습니다. 값이 두 개만 제공되면 기본 데이터베이스가 사용되고 값이 "schema" 및 "name"으로 해석됩니다. 값이 하나만 제공되면 기본 데이터베이스 스키마가 사용되고 제공된 값이 `"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와 같습니다. falseCase는 선택사항이며 기본값은 빈 문자열입니다.

ITarget

BigQuery 내의 테이블에 대한 참조입니다.

database	string
name	string
schema	string

ITargetableConfig

SQL 워크플로 작업의 대상 데이터베이스 및 스키마를 정의합니다.

database	string
	이 작업의 출력을 만들어야 하는 데이터베이스입니다. BigQuery로 설정해야 합니다.
schema	string
	이 작업의 출력을 만들어야 하는 스키마입니다.

operate()

operate	(name: string, queries?: Contextable)
	SQL 작업을 정의합니다. /definitions 디렉터리에서만 사용할 수 있습니다.

예:

// definitions/file.js

operate("an-operation", ["SELECT 1", "SELECT 2"])

publish()

publish	(name: string, queryOrConfig?: Contextable | ITableConfig)
	테이블 또는 뷰를 만듭니다. /definitions 디렉터리에서만 사용할 수 있습니다.

예:

// 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 절을 포함해야 합니다. 자세한 내용은 증분 테이블 구성을 참조하세요.