JavaScript로 Dataform SQL 워크플로 만들기

이 문서에서는 JavaScript를 사용하여 Dataform에서 SQL 워크플로 요소를 만드는 방법을 설명합니다. Dataform Core 대신 JavaScript를 사용하여 워크플로에서 비슷한 요소를 반복적으로 만들 수 있습니다.

JavaScript로 Dataform에서 워크플로 개발 정보

Dataform Core를 사용하면 SQLX 및 JavaScript로 SQL 워크플로 작업을 만들 수 있습니다. JavaScript를 사용하면 워크플로에서 유사한 작업을 반복적으로 만들 수 있습니다. 예를 들어 특정 사용자 ID가 삭제된 워크플로의 각 테이블에 대한 뷰를 만들 수 있습니다.

다음 JavaScript 코드 샘플을 사용하면 user_id 필드 값이 blocked_user_ids 목록의 값 중 하나와 일치하지 않는 각 테이블의 뷰를 만들 수 있습니다.

  const datasetNames = ["user_events", "user_settings", "user_logs"];

  datasetNames.forEach(datasetNames => {
    publish(datasetNames + "_blocked_removed").query(
      ctx => `
        SELECT * FROM ${ctx.ref(tableName)}
        WHERE user_id NOT IN (
          SELECT user_id
          FROM ${ctx.ref("blocked_user_ids")}
        )`
    );
  });

이 코드 샘플에서는 차단된 사용자 ID가 포함되지 않은 user_events_blocked_removed, user_settings_blocked_removed, user_logs_blocked_removed라는 3개의 뷰를 만듭니다.

Dataform 전역 메서드와 임의 JavaScript ES5 코드(예: 루프 및 상수)를 사용하여 하나의 JavaScript 파일 내에서 여러 작업을 만들 수 있습니다.

Dataform에서 JavaScript로 다음 작업을 정의할 수 있습니다.

시작하기 전에

  1. Google Cloud 콘솔에서 Dataform 페이지로 이동합니다.

    Dataform으로 이동

  2. 저장소를 선택하거나 만듭니다.

  3. 개발 작업공간을 선택하거나 만듭니다.

필요한 역할

JavaScript로 SQL 워크플로를 개발하는 데 필요한 권한을 얻으려면 관리자에게 작업공간의 Dataform 편집자(roles/dataform.editor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

Dataform에서 JavaScript 파일 만들기

정의 및 데이터 소스 선언을 위한 JavaScript 파일을 definitions/ 디렉터리에 저장합니다. definitions/ 디렉터리에 새 JavaScript 파일을 만들려면 다음 단계를 따르세요.

  1. 파일 창에서 definitions/ 옆에 있는 더보기 메뉴를 클릭합니다.

  2. 파일 만들기를 클릭합니다.

  3. 새 파일 만들기 창에서 다음을 수행합니다.

    1. 파일 경로 추가 필드에 definitions/ 다음에 파일 이름을 입력하고 .js를 입력합니다. 예를 들면 definitions/definitions.js입니다.

      파일 이름에는 숫자, 문자, 하이픈, 밑줄만 포함할 수 있습니다.

    2. 파일 만들기를 클릭합니다.

JavaScript로 Dataform SQL 워크플로 객체 속성 설정

다음 Dataform 전역 메서드를 사용하여 Dataform으로 SQL 워크플로 객체를 만들 수 있습니다.

  • declare: 데이터 소스를 선언하는 데 사용됩니다.
  • publish: 테이블을 정의하는 데 사용됩니다.
  • assert: 어설션을 만드는 데 사용됩니다.
  • operate: 커스텀 SQL 작업을 정의하는 데 사용됩니다.

각 전역 메서드에는 생성된 객체를 구성하는 데 사용할 수 있는 속성이 포함됩니다. 전역 메서드 및 속성에 대한 자세한 내용은 Dataform Core 참조를 확인하세요.

테이블을 만드는 publish() 메서드에서 두 번째 메서드 인수로 테이블 속성을 전달하여 테이블 속성을 설정할 수 있습니다.

테이블 속성을 publish()의 두 번째 인수로 전달하려면 다음 단계를 수행합니다.

  1. 개발 작업공간의 파일 창에서 definitions/를 펼칩니다.

  2. JavaScript 파일을 선택합니다.

  3. 파일에서 publish() 메서드에 테이블 속성을 다음 형식으로 추가합니다.

     method("first_method_argument", {
       property1: "property1_value",
       property2: "property2_value",
       property3: "property3_value",
     });
    
  4. (선택사항): 형식을 클릭합니다.

다음 코드 샘플은 속성을 메서드의 두 번째 인수로 전달하여 publish() 메서드에 속성을 설정하는 방법을 보여줍니다.

  publish("table1", {
    type: "table",
    dependencies: ["other_table"],
    description: {
      "Value is 1"
    }
  }).query(ctx => "SELECT 1 AS test");

JavaScript 파일에 include 참조

JavaScript 파일 내에 include 함수, 매크로 또는 상수를 참조할 수 있습니다. Dataform의 include에 대한 자세한 내용은 JavaScript include로 변수 및 함수 재사용을 참조하세요.

JavaScript 파일 내의 include 참조 구문은 include 파일의 위치에 따라 다릅니다. Dataform은 include 디렉터리에 이러한 파일을 저장합니다.

최상위 include 참조

  • 최상위 include 파일을 참조하려면 변수를 선언할 때 파일 이름을 참조합니다.

다음 코드 샘플은 includes/service.js 파일의 serviceNameserviceId 변수를 참조합니다.

  const {serviceName, serviceId} = service;

중첩 include 참조

중첩된 include 파일을 참조하려면 JavaScript require 함수에 파일 이름을 입력합니다.

다음 코드 샘플은 includes/allServices/service.js 파일의 serviceNameserviceId 변수를 참조합니다.

  const {serviceName, serviceId} = require("includes/allServices/service.js");

JavaScript 메서드에서 Dataform 쿼리 함수 사용

Dataform은 refself와 같이 쿼리 내에서 사용할 수 있는 여러 가지 기본 제공 함수를 제공합니다. Dataform 기본 제공 함수에 대한 자세한 내용은 Dataform API 참조를 확인하세요.

JavaScript 메서드에서 기본 제공 쿼리 함수를 사용하려면 다음 단계를 따르세요.

  1. 개발 작업공간의 파일 창에서 definitions/를 펼칩니다.

  2. JavaScript 파일을 선택합니다.

  3. 파일에 전역 Dataform JavaScript 메서드를 입력합니다.

  4. 메서드에서 컨텍스트 가능한 ctx 인수를 입력합니다.

  5. 선택사항: JavaScript 템플릿 문자열을 사용하는 경우 컨텍스트 가능한 인수를 백틱 ``으로 래핑합니다.

  6. 컨텍스트 가능한 인수에 쿼리 함수를 매개변수와 함께 컨텍스트 객체로 입력합니다.

  7. (선택사항): 형식을 클릭합니다.

다음 코드 샘플은 게시 메서드의 컨텍스트 가능한 인수에 래핑된 ref 쿼리 함수를 보여줍니다.

  publish("example").query(ctx => `SELECT * FROM ${ctx.ref("other_table")}`);

JavaScript로 SQL 워크플로 데이터 소스 선언

Dataform 선언 JavaScript 메서드를 사용하여 하나의 JavaScript 선언 파일에서 여러 데이터 소스를 선언할 수 있습니다. 선언 메서드에 대한 자세한 내용은 Dataform Core 참조를 확인하세요. Dataform의 데이터 소스에 대한 자세한 내용은 데이터 소스 선언을 참조하세요.

JavaScript 파일에서 데이터 소스를 선언하려면 다음 단계를 따르세요.

  1. 개발 작업공간의 파일 창에서 definitions/를 확장하세요.

  2. JavaScript 파일을 선택합니다.

  3. 파일에 다음 코드 스니펫을 입력합니다.

     declare({
       database: "DATABASE_PROJECT_ID",
       schema: "BIGQUERY_SCHEMA",
       name: "RELATION_NAME",
     });
    

    다음을 바꿉니다.

    • DATABASE_PROJECT_ID: 데이터 소스가 포함된 프로젝트의 프로젝트 ID
    • BIGQUERY_SCHEMA: 외부 관계가 있는 BigQuery 데이터 세트
    • RELATION_NAME: 나중에 Dataform에서 데이터 소스를 참조하는 데 사용할 수 있는 관계의 이름
  4. 동일한 파일에 다른 데이터 소스를 선언하려면 파일에 추가 declare 블록을 추가합니다.

  5. (선택사항): 형식을 클릭합니다.

JavaScript로 테이블 정의

Dataform JavaScript publish 메서드로 테이블을 만들 수 있습니다. 게시 메서드에 대한 자세한 내용은 Dataform Core 참조를 확인하세요.

테이블, 증분 테이블, 뷰 등의 테이블 유형을 정의할 수 있습니다. Dataform에서 테이블을 정의하는 방법에 대한 자세한 내용은 테이블 만들기를 참조하세요.

JavaScript 파일에서 테이블을 정의하려면 다음 단계를 따르세요.

  1. 개발 작업공간의 파일 창에서 definitions/를 펼칩니다.

  2. JavaScript 파일을 선택합니다.

  3. 파일에 다음 코드 스니펫을 입력합니다.

     publish("TABLE_NAME").query(ctx => "SELECT_QUERY");
    
    1. TABLE_NAME을 테이블 이름으로 바꿉니다.

    2. SELECT_QUERY를 테이블을 정의하는 SQL SELECT 문으로 바꿉니다.

  4. 테이블 유형을 설정하고, 테이블 종속 항목을 추가하고, 테이블 설명을 추가하려면 publish 메서드의 객체 속성을 설정합니다.

  5. 동일한 파일에 다른 테이블을 정의하려면 3단계와 4단계를 반복합니다.

  6. (선택사항): 형식을 클릭합니다.

JavaScript로 수동 Dataform 어설션 정의

Dataform 어설션 JavaScript 메서드를 사용하여 JavaScript 파일에서 수동 SQL 어설션을 만들 수 있습니다. 어설션 메서드에 대한 자세한 내용은 Dataform Core 참조를 확인하세요.

수동 어설션 SQL 쿼리는 0개의 행을 반환해야 합니다. 쿼리가 실행될 때 행을 반환하면 어설션이 실패합니다. 하나의 JavaScript 파일에 여러 어설션을 만들 수 있습니다.

Dataform의 어설션에 대한 자세한 내용은 어설션이 있는 테이블 테스트를 참조하세요.

JavaScript 파일에서 수동 어설션을 만들려면 다음 단계를 따르세요.

  1. 개발 작업공간의 파일 창에서 definitions/를 펼칩니다.

  2. JavaScript 파일을 선택합니다.

  3. 파일에 다음 코드 스니펫을 입력합니다.

     assert("<var>ASSERTION_NAME</var>").query(ctx => "<var>CUSTOM_ASSERTION_QUERY</var>");
    
    1. ASSERTION_NAME을 커스텀 어설션 이름으로 바꿉니다.

    2. CUSTOM_ASSERTION_QUERY를 SQL 어설션 쿼리로 바꿉니다.

  4. 같은 파일에 다른 어설션을 만들려면 3단계를 반복합니다.

  5. (선택사항): 형식을 클릭합니다.

다음 코드 샘플은 source_table의 값이 NULL이 아님을 알리는 어설션을 보여줍니다.

  assert("assertion1").query(ctx => "SELECT * FROM source_table WHERE value IS NULL");

JavaScript로 커스텀 SQL 작업 정의

Dataform 작업 JavaScript 메서드를 사용하여 JavaScript 파일에서 커스텀 SQL 작업을 정의할 수 있습니다. Dataform의 커스텀 SQL 작업에 대한 자세한 내용은 커스텀 SQL 작업 추가를 참조하세요.

JavaScript로 커스텀 SQL 작업을 정의하려면 다음 단계를 따르세요.

  1. 개발 작업공간의 파일 창에서 definitions/를 펼칩니다.

  2. JavaScript 파일을 선택합니다.

  3. 파일에 다음 코드 스니펫을 입력합니다.

     operate("OPERATION_NAME").queries(ctx => "CUSTOM_SQL_QUERY");
    
    1. OPERATION_NAME을 커스텀 작업의 이름으로 바꿉니다.

    2. CUSTOM_SQL_QUERY를 커스텀 SQL 쿼리로 바꿉니다.

  4. 같은 파일에 다른 커스텀 SQL 작업을 정의하려면 3단계를 반복합니다.

  5. (선택사항): 형식을 클릭합니다.

다음 코드 샘플은 하나의 새로운 행을 some_table에 삽입하고 새 행의 test_column2로 설정하는 JavaScript 파일의 커스텀 SQL 작업을 보여줍니다.

  operate("operation1").queries("INSERT INTO some_table (test_column) VALUES (2)");

다음 단계

  • Dataform JavaScript 메서드 및 기본 제공 쿼리 함수에 대한 자세한 내용은 Dataform Core 참조를 확인하세요.
  • JavaScript로 Dataform에서 개발하는 방법에 대한 자세한 내용은 Dataform의 JavaScript 소개를 참조하세요.