어설션 정보
어설션은 쿼리에 지정된 규칙을 하나 이상 위반하는 행을 찾는 데이터 품질 테스트 쿼리입니다. 쿼리가 행을 반환하면 어설션이 실패합니다. Dataform은 SQL 워크플로를 업데이트할 때마다 어설션을 실행하고 어설션이 실패할 경우 알림을 제공합니다.
Dataform은 컴파일된 어설션 쿼리의 결과가 포함된 뷰를 BigQuery에 자동으로 만듭니다. 워크플로 설정 파일에 구성된 대로 Dataform은 어설션 스키마에 어설션 결과를 검사할 수 있는 뷰를 만듭니다.
예를 들어 기본 dataform_assertions
스키마의 경우 Dataform은 BigQuery에서 dataform_assertions.assertion_name
형식으로 뷰를 만듭니다.
테이블, 증분 테이블, 뷰, 구체화된 뷰 등 모든 Dataform 테이블 유형에 대해 어설션을 만들 수 있습니다.
다음과 같은 방법으로 어설션을 만들 수 있습니다.
-
테이블의
config
블록에 기본 제공 어설션을 추가하고 조건을 지정할 수 있습니다. -
고급 사용 사례 또는 Dataform에서 생성되지 않은 데이터 세트에 대한 별도의 SQLX 파일에 커스텀 어설션을 수동으로 작성합니다.
시작하기 전에
필요한 역할
어설션을 만드는 데 필요한 권한을 얻으려면 관리자에게 작업공간의 Dataform 편집자(roles/dataform.editor
) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
기본 제공 어설션 만들기
기본 제공 Dataform 어설션을 테이블의 config
블록에 추가할 수 있습니다. 테이블 생성 후 Dataform에서 이러한 어설션을 실행합니다. Dataform이 테이블을 게시하면 어설션을 검사할 수 있습니다.
테이블의 config
블록에 다음 어설션을 만들 수 있습니다.
nonNull
이 조건은 지정된 열이 모든 테이블 행에서 null이 아니라는 어설션을 만듭니다. 이 조건은 null이 될 수 없는 열에 사용됩니다.
다음 코드 샘플은 테이블의
config
블록에 있는nonNull
어설션을 보여줍니다.
config {
type: "table",
assertions: {
nonNull: ["user_id", "customer_id", "email"]
}
}
SELECT ...
rowConditions
이 조건은 모든 테이블 행이 정의한 커스텀 로직을 따른다는 어설션을 만듭니다. 각 행 조건은 커스텀 SQL 표현식이며 각 테이블 행은 각 행 조건을 기준으로 평가됩니다. 테이블 행이 행 조건을 위반하면 어설션이 실패합니다.
다음 코드 샘플은 증분 테이블의
config
블록에 있는 커스텀rowConditions
어설션을 보여줍니다.
config {
type: "incremental",
assertions: {
rowConditions: [
'signup_date is null or signup_date > "2022-08-01"',
'email like "%@%.%"'
]
}
}
SELECT ...
uniqueKey
이 조건은 지정된 열에서 동일한 값을 가진 테이블 행이 없다는 어설션을 만듭니다.
다음 코드 샘플은 뷰의
config
블록에 있는uniqueKey
어설션을 보여줍니다.
config {
type: "view",
assertions: {
uniqueKey: ["user_id"]
}
}
SELECT ...
uniqueKeys
이 조건은 지정된 열에서 동일한 값을 가진 테이블 행이 없다는 어설션을 만듭니다. 테이블에 지정된 모든 열에 대해 동일한 값을 갖는 행이 둘 이상 있는 경우 어설션이 실패합니다.
다음 코드 샘플은 테이블의
config
블록에 있는uniqueKeys
어설션을 보여줍니다.
config {
type: "table",
assertions: {
uniqueKeys: [["user_id"], ["signup_date", "customer_id"]]
}
}
SELECT ...
config
블록에 어설션 추가
테이블의 구성 블록에 어설션을 추가하려면 다음 단계를 따르세요.
- 개발 작업공간의 파일 창에서 테이블 정의 SQLX 파일을 선택합니다.
- 테이블 파일의
config
블록에assertions: {}
를 입력합니다. assertions: {}
내에서 어설션을 추가합니다.- (선택사항): 형식을 클릭합니다.
다음 코드 샘플은 config
블록에 추가된 조건을 보여줍니다.
config {
type: "table",
assertions: {
uniqueKey: ["user_id"],
nonNull: ["user_id", "customer_id"],
rowConditions: [
'signup_date is null or signup_date > "2019-01-01"',
'email like "%@%.%"'
]
}
}
SELECT ...
SQLX로 수동 어설션 만들기
수동 어설션은 전용 SQLX 파일로 작성하는 SQL 쿼리입니다. 수동 어설션 SQL 쿼리는 0개의 행을 반환해야 합니다. 실행했을 때 쿼리가 행을 반환하면 어설션이 실패합니다.
새 SQLX 파일에 수동 어설션을 추가하려면 다음 단계를 수행합니다.
- 파일 창에서
definitions/
옆에 있는 더보기 메뉴를 클릭합니다. - 파일 만들기를 클릭합니다.
파일 경로 추가 필드에 파일 이름을 입력하고 파일 이름 다음에
.sqlx
를 입력합니다. 예를 들면definitions/custom_assertion.sqlx
입니다.파일 이름에는 숫자, 문자, 하이픈, 밑줄만 포함할 수 있습니다.
파일 만들기를 클릭합니다.
파일 창에서 새 파일을 클릭합니다.
파일에 다음을 입력합니다.
config { type: "assertion" }
config
블록 아래에서 SQL 쿼리 또는 여러 쿼리를 작성합니다.(선택사항): 형식을 클릭합니다.
다음 코드 샘플은 A, B 필드를 어설션하고 c
가 sometable
에서 NULL
이 아닌 SQLX 파일의 수동 어설션을 보여줍니다.
config { type: "assertion" }
SELECT
*
FROM
${ref("sometable")}
WHERE
a IS NULL
OR b IS NULL
OR c IS NULL
어설션을 종속 항목으로 설정
워크플로 작업 B가 어설션이 있는 워크플로 작업 A에 종속되면 작업 A의 어설션 실패로 인해 Dataform의 작업 B 실행이 차단되지 않습니다. 작업 A의 어설션에 통과한 경우에만 작업 B를 실행하려면 작업 A의 어설션을 작업 B의 종속 항목으로 설정해야 합니다.
다음과 같은 방법으로 어설션을 선택한 작업의 종속 항목으로 설정할 수 있습니다.
- 선택한 어설션을 종속 항목으로 설정
수정된 작업의
config
블록에서dependencies: [ "" ]
에 추가하여 선택한 어설션을 종속 항목으로 수동으로 설정할 수 있습니다.예를 들어 작업 B가 작업 A에 종속되는데 작업 B가 작업 A의 선택된 어설션에만 종속되도록 하려면 선택한 어설션을 작업 B의
config
블록에 추가하면 됩니다.데이터 소스 선언을 제외한 모든 작업 유형의 종속 항목으로 선택한 어설션을 수동으로 설정할 수 있습니다.
- 선택한 종속 항목 작업의 어설션을 종속 항목으로 설정
선택한 종속 항목 워크플로 작업의 모든 직접 어설션을 수정된 작업의 종속 항목으로 자동 설정하도록
includeDependentAssertions
매개변수를 설정할 수 있습니다. Dataform은 종속 항목 작업의 어설션이 변경되는 경우 종속 항목이 최신 상태로 유지되도록 작업을 컴파일할 때마다 이러한 어설션을 종속 항목으로 추가합니다.예를 들어 작업 C가 작업 A 및 B에 종속되는데 작업 C가 작업 A의 어설션에만 종속되기를 원한다면 작업 C를 수정하고
includeDependentAssertions
매개변수를 설정하여 작업 A의 모든 어설션을 작업 C의 종속 항목으로 자동 설정하면 됩니다.다음 유형의 작업에
includeDependentAssertions
매개변수를 설정할 수 있습니다.table
view
operations
- 모든 종속 항목 작업의 어설션을 종속 항목으로 설정
수정된 작업의 모든 종속 항목 작업의 모든 직접 어설션을 수정된 작업의 추가 종속 항목으로 자동 설정하도록
dependOnDependencyAssertions
매개변수를 설정할 수 있습니다. Dataform은 종속 항목 작업의 어설션이 변경되는 경우 종속 항목이 최신 상태로 유지되도록 작업을 컴파일할 때마다 이러한 어설션을 종속 항목으로 추가합니다.예를 들어 작업 C가 작업 A 및 B에 종속되는 경우 작업 C를 수정하고
dependOnDependencyAssertions
매개변수를 설정하여 작업 A 및 B의 모든 어설션을 작업 C의 종속 항목으로 자동 설정하면 됩니다.다음 유형의 작업에
dependOnDependencyAssertions
매개변수를 설정할 수 있습니다.table
view
operations
단일 파일에서 dependOnDependencyAssertions
매개변수와 includeDependentAssertions
매개변수를 설정하면 includeDependentAssertions
매개변수가 우선 적용됩니다.
예를 들어 dependOnDependencyAssertions
를 true
로 설정했지만 선택한 종속 항목 작업에 대해 includeDependentAssertions
를 false
로 설정하면 Dataform은 해당 작업의 어설션을 종속 항목에 추가하지 않습니다.
다음 코드 샘플은 동일한 테이블 정의 파일에 설정된 dependOnDependencyAssertions
및 includeDependentAssertions
매개변수를 보여줍니다.
// filename is tableName.sqlx
config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "actionA", {name: "actionB", includeDependentAssertions: false} ]
}
SELECT * FROM ${ref("actionC")}
앞의 코드 샘플에서 Dataform은 컴파일 중 actionA
및 actionC
의 모든 직접 어설션을 tableName
의 종속 항목에 추가합니다.
선택한 어설션을 종속 항목으로 설정
선택한 어설션에 통과한 경우에만 워크플로 작업을 실행하려면 수정된 작업의 config
블록에서 dependencies: [ "" ]
에 선택한 어설션을 추가하면 됩니다.
선택한 어설션을 선택한 워크플로 작업의 종속 항목으로 설정하려면 다음 단계를 따르세요.
- 개발 작업공간의 파일 창에서
definitions/
를 펼칩니다. - 워크플로 작업 SQLX 파일을 선택합니다.
- 작업 파일의
config
블록에dependencies: [ "" ]
를 입력합니다. dependencies: [ "" ]
내에서 작업 어설션의 이름 또는 종속 항목으로 설정하려는 수동 어설션의 파일 이름을 다음 형식 중 하나로 입력합니다.nonNull
config { type: "ACTION_TYPE", dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_nonNull"] }
다음을 바꿉니다.
- ACTION_TYPE: 워크플로 작업의 유형(
table
,view
,operations
) - ACTION_DATASET_NAME: 작업이 정의된 데이터 세트의 이름. 기본 데이터 세트는 워크플로 설정 파일에서 정의됩니다.
- ACTION_NAME: 어설션이 정의된 작업의 이름
rowConditions
config { type: "ACTION_TYPE", dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_rowConditions"] }
다음을 바꿉니다.
- ACTION_TYPE: 워크플로 작업의 유형(
table
,view
,operations
) - DATASET_NAME: 작업이 정의된 데이터 세트의 이름. 기본 데이터 세트는 워크플로 설정 파일에서 정의됩니다.
- ACTION_NAME: 어설션이 정의된 작업의 이름
uniqueKey
config { type: "ACTION_TYPE", dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKey_INDEX"] }
다음을 바꿉니다.
- ACTION_TYPE: 워크플로 작업의 유형(
table
,view
,operations
) - DATASET_NAME: 테이블이 정의된 데이터 세트의 이름. 기본 데이터 세트는 워크플로 설정 파일에서 정의됩니다.
- ACTION_NAME: 어설션이 정의된 테이블의 이름
- INDEX: 종속 항목으로 추가하려는
uniqueKey
어설션에 정의된 키 배열의 색인. 예를 들면0
또는1
입니다. 어설션에 키 배열이 하나만 정의된 경우 색인은0
입니다.
uniqueKeys
config { type: "ACTION_TYPE", dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKeys_INDEX"] }
다음을 바꿉니다.
- ACTION_TYPE: 워크플로 작업의 유형(
table
,view
,operations
) - DATASET_NAME: 테이블이 정의된 데이터 세트의 이름. 기본 데이터 세트는 워크플로 설정 파일에서 정의됩니다.
- ACTION_NAME: 어설션이 정의된 테이블의 이름
- INDEX: 종속 항목으로 추가하려는
uniqueKeys
어설션에 정의된 키 배열의 색인(예:0
또는1
). 어설션에 키 배열이 하나만 정의된 경우 색인은0
입니다.
수동 어설션
config { type: "ACTION_TYPE", dependencies: [ "MANUAL_ASSERTION_NAME"] }
다음을 바꿉니다.
- ACTION_TYPE: 워크플로 작업의 유형(
table
,view
,operations
) - MANUAL_ASSERTION_NAME: 수동 어설션의 이름
- ACTION_TYPE: 워크플로 작업의 유형(
수정된 테이블에 다른 어설션을 종속 항목으로 추가하려면 4단계를 반복합니다.
(선택사항): 형식을 클릭합니다.
다음 코드 샘플은 dataform
데이터 세트에 정의된 테이블 A에 추가된 어설션을 보여줍니다.
config {
type: "table",
assertions: {
uniqueKey: ["user_id"],
nonNull: ["user_id", "customer_id"],
}
}
다음 코드 샘플은 테이블 B에 종속 항목으로 추가된 테이블 A 어설션을 보여줍니다.
config {
type: "table",
dependencies: [ "dataform_A_assertions_uniqueKey_0", "dataform_A_assertions_nonNull"]
}
다음 코드 샘플은 뷰에 종속 항목으로 추가된 manualAssertion.sqlx
파일에 정의된 수동 어설션을 보여줍니다.
config {
type: "view",
dependencies: [ "manualAssertion"]
}
다음 코드 샘플은 manual_assertion
파일과 테이블에 종속 항목으로 추가된 sometable
테이블의 어설션을 보여줍니다.
config {
type: "table",
dependencies: [ "manual_assertion", "dataform_sometable_assertions_nonNull" , "dataform_sometable_assertions_rowConditions"]
}
SELECT * FROM ${ref("referenced_table")} LEFT JOIN ...
선택한 작업의 어설션을 종속 항목으로 설정
선택한 종속 항목 작업의 모든 직접 어설션에 통과한 경우에만 워크플로 작업을 실행하려면 수정된 작업에서 includeDependentAssertions
매개변수를 true
로 설정합니다.
Dataform은 컴파일 중에 선택한 종속 항목 작업의 직접 어설션을 종속 항목에 자동으로 추가합니다. 기본값은 false
입니다.
선택한 종속 항목 작업의 모든 어설션을 종속 항목으로 설정하려면 다음 단계를 따르세요.
- 개발 작업공간의 파일 창에서
definitions/
를 펼칩니다. - 워크플로 작업 SQLX 파일을 선택합니다.
파일에서 다음 방법 중 하나를 사용하여
includeDependentAssertions
매개변수를true
로 설정합니다.config
블록config { type: "ACTION_TYPE", dependencies: [{name: "dEPENDENCY_ACTION_NAME", includeDependentAssertions: true}] }
다음을 바꿉니다.
- ACTION_TYPE: 워크플로 작업의 유형(
table
,view
,operations
) - DEPENDENCY_ACTION_NAME: 어설션을 수정된 작업의 종속 항목으로 설정하려는 종속 항목 작업의 이름
SELECT
문config { type: "ACTION_TYPE" } SELECT * FROM ${ref({name: "DEPENDENCY_ACTION_NAME", includeDependentAssertions: true})}
다음을 바꿉니다.
- ACTION_TYPE: 워크플로 작업의 유형(
table
,view
,operations
) - DEPENDENCY_ACTION_NAME: 어설션을 수정된 작업의 종속 항목으로 설정하려는 종속 항목 작업의 이름
- ACTION_TYPE: 워크플로 작업의 유형(
(선택사항): 형식을 클릭합니다.
다음 코드 샘플은 viewA
, tableB
, tableB
의 모든 어설션에 종속되는 tableC
을 보여줍니다.
// filename is tableC.sqlx
config {
type: "table",
dependencies: ["viewA", {name: "tableB", includeDependentAssertions: true}]
}
SELECT * FROM ...
앞의 코드 샘플에서 Dataform은 컴파일 중에 tableB
의 모든 직접 어설션을 종속 항목으로 tableC
에 추가합니다.
모든 종속 항목 작업의 어설션을 종속 항목으로 설정
모든 종속 항목 작업의 모든 직접 어설션에 통과한 경우에만 워크플로 작업을 실행하려면 수정된 작업에서 dependOnDependencyAssertions
매개변수를 true
로 설정합니다.
Dataform은 컴파일 중에 종속 항목 작업의 직접 어설션을 종속 항목으로 자동으로 추가합니다. 기본값은 false
입니다.
단일 파일에서 dependOnDependencyAssertions
매개변수와 includeDependentAssertions
매개변수를 설정하면 설정된 종속 항목 작업에서 includeDependentAssertions
매개변수가 우선 적용됩니다.
선택한 종속 항목 작업의 모든 어설션을 종속 항목으로 설정하려면 다음 단계를 따르세요.
- 개발 작업공간의 파일 창에서
definitions/
를 펼칩니다. - 워크플로 작업 SQLX 파일을 선택합니다.
파일에서
dependOnDependencyAssertions
매개변수를 다음 형식으로true
로 설정합니다.config { type: "ACTION_TYPE", dependOnDependencyAssertions: true, dependencies: [ "dependency1", "dependency2" ] }
ACTION_TYPE을 워크플로 작업의 유형으로 바꿉니다. 지원되는 값은
table
,view
,operations
입니다.(선택사항): 형식을 클릭합니다.
다음 코드 샘플은 sometableA
, sometabletableB
, sometableC
, sometableD
에 종속되는 sometableE
와 종속 항목 테이블의 모든 직접 어설션을 보여줍니다.
// filename is sometableE.sqlx
config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "sometableA", "sometableB" ]
}
SELECT * FROM ${ref("sometableC")}
SELECT * FROM ${ref("sometableD")}
앞의 코드 샘플에서 Dataform은 컴파일 중 sometableA
, sometableB
, sometableC
, sometableD
의 모든 직접 어설션을 sometableE
에 종속 항목으로 자동 추가합니다.
다음 단계
- 어설션 유형에 대한 자세한 내용은 Dataform API 참조하기
- JavaScript로 어설션을 정의하는 방법을 알아보려면 JavaScript로 SQL 워크플로 만들기 참조하기
- 워크플로를 수동으로 실행하는 방법은 실행 트리거 참조하기