Dataform에 패키지 설치

이 문서에서는 Dataform 저장소에 JavaScript 패키지를 설치하고, JavaScript 파일 및 SQLX 파일로 가져와 패키지를 사용하여 Dataform에서 SQL 워크플로를 개발하는 방법을 보여줍니다.

Dataform에서 패키지를 사용하려면 저장소에 패키지를 설치해야 합니다.

Dataform에서 다음 유형의 패키지를 설치할 수 있습니다.

그런 다음 JavaScript 또는 SQLX 파일에서 패키지를 사용하려면 패키지의 선택한 콘텐츠를 파일로 가져와야 합니다. 또한 전체 패키지를 선택된 콘텐츠 대신 JavaScript 또는 SQLX 파일로 가져올 수 있습니다.

프로덕션 환경에서 패키지 설치 문제를 방지하려면 다음을 따르는 것이 좋습니다.

  • package.json에서 패키지 버전을 명시적으로 지정하세요(예: 3.0.0). package.json의 다른 dependencies 옵션(예: >version)을 사용하지 마세요.

  • 비프로덕션 환경에서 새 패키지 버전을 테스트합니다. 다양한 코드 수명 주기 환경 구성에 대한 자세한 내용은 코드 수명 주기 관리를 참조하세요.

시작하기 전에

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

    Dataform 페이지로 이동

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

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

  4. 선택사항: 비공개 패키지를 설치하려면 비공개 패키지를 인증합니다.

필요한 역할

패키지를 가져오는 데 필요한 권한을 얻으려면 관리자에게 작업공간에 대한 Dataform 편집자(roles/dataform.editor) IAM 권한을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

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

Dataform 저장소에 패키지 설치

Dataform 저장소 내에 패키지를 설치하려면 package.json 파일에 패키지를 종속 항목으로 추가해야 합니다. package.json 파일의 종속 항목 정의 형식은 패키지 유형에 따라 다릅니다. workflow_settings.yaml 파일이 dataformCoreVersion을 지정하므로 package.json 파일이 없으면 workflow_settings.yaml에서 dataformCoreVersion을 삭제한 후 package.json 파일을 만들고 @dataform/core를 종속 항목으로 추가합니다.

Dataform 저장소에 패키지를 설치하려면 다음 단계를 수행합니다.

  1. 작업공간의 파일 창에서 package.json을 선택합니다.

  2. dependencies 블록에 패키지를 추가합니다.

    1. 게시된 공개 NPM 패키지를 다음 형식으로 추가합니다.

      "PACKAGE-NAME": "PACKAGE-VERSION"

      다음을 바꿉니다.

      • PACKAGE-NAME: 패키지 이름
      • PACKAGE-VERSION: 최신 버전의 게시된 공개 NPM 패키지 패키지 설치 관련 문제를 방지하려면 버전을 명시적으로 지정합니다(예: 3.0.0).

    2. 게시되지 않은 공개 NPM 패키지를 다음 형식으로 추가합니다.

      "PACKAGE-NAME": "PACKAGE-URL"

      다음을 바꿉니다.

      • PACKAGE-NAME: 패키지 이름
      • PACKAGE-URL을 제3자 패키지 저장소의 tar.gz URL(예: https://github.com/user/sample-package-repository/archive/master.tar.gz)로 바꿉니다.

    3. 인증된 비공개 NPM 패키지를 다음 형식으로 추가합니다.

      "REGISTRY-SCOPE/PACKAGE-NAME": "PACKAGE-URL"

      다음을 바꿉니다.

      • REGISTRY-SCOPE: 패키지 이름. REGISTRY-SCOPE는 저장소의 .nmprc 파일에 정의된 레지스트리 범위와 일치해야 합니다.
      • PACKAGE-NAME: 패키지 이름
      • PACKAGE-URL: 패키지 저장소의 tar.gz URL(예: https://github.com/user/sample-package-repository/archive/master.tar.gz)

  3. 패키지 설치를 클릭합니다.

  4. 변경사항을 커밋하고 푸시합니다.

다음 코드 샘플은 .package.json 파일에 추가된 공개 오픈소스 지연 변경 측정기준 패키지를 보여줍니다.

 ```json
 {
   "name": "repository-name",
   "dependencies": {
     "@dataform/core": "2.0.3",
     "dataform-scd": "https://github.com/dataform-co/dataform-scd/archive/0.3.tar.gz"
   }
 }
 ```

Dataform에서 자바스크립트 파일로 패키지 함수 또는 상수 가져오기

Dataform에서 JavaScript 파일 내 패키지의 함수 또는 상수를 사용하려면 먼저 이를 파일로 가져와야 합니다.

패키지에서 JavaScript 파일로 함수 또는 상수를 가져오려면 다음 단계를 따르세요.

  1. 작업공간의 파일 창에서 패키지를 사용하려는 .js 파일을 선택합니다.

  2. 파일에서 함수 또는 상수를 다음 형식으로 가져옵니다.

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    1. EXPORT-NAME을 패키지 index.js 파일의 module.exports에서 선언된 사용하려는 함수 또는 상수의 이름으로 바꿉니다.
    2. PACKAGE-NAME을 사용하려는 패키지 이름으로 바꿉니다.

  3. 변경사항을 커밋하고 푸시합니다.

다음 코드 샘플은 JavaScript 파일에서 가져와서 사용되는 postoffice 패키지의 getDomain 함수를 보여줍니다.

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const { getDomain } = require("postoffice");
getDomain();

Dataform에서 전체 패키지를 JavaScript 파일로 가져오기

선택한 함수 또는 상수를 JavaScript 파일로 가져오는 대신 전체 패키지를 JavaScript 파일로 가져오려면 다음 단계를 따르세요.

  1. 작업공간의 파일 창에서 패키지를 사용하려는 .js 파일을 선택합니다.

  2. 파일에서 다음 형식으로 패키지를 가져옵니다.

    const CONSTANT-NAME = require("PACKAGE-NAME");
    1. CONSTANT-NAME을 상수 이름으로 바꿉니다.
    2. PACKAGE-NAME을 사용하려는 패키지 이름으로 바꿉니다.

  3. 변경사항을 커밋하고 푸시합니다.

다음 코드 샘플은 JavaScript 파일에 사용되는 가져온 postoffice 패키지의 getDomain 함수를 보여줍니다.

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const postoffice = require("postoffice");
postoffice.getDomain();

Dataform에서 SQLX 파일로 패키지 함수 또는 상수 가져오기

SQLX 파일 내 패키지의 함수 또는 상수를 사용하려면 먼저 이를 파일로 가져와야 합니다.

패키지의 함수 또는 상수를 SQLX 파일로 가져오려면 다음 단계를 따르세요.

  1. 작업공간의 파일 창에서 패키지를 사용하려는 .sqlx 파일을 선택합니다.

  2. 파일에 다음 js 블록을 입력합니다.

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. EXPORT-NAME을 패키지 index.js 파일의 module.exports에서 선언된 사용하려는 함수 또는 상수의 이름으로 바꿉니다.
    2. PACKAGE-NAME을 사용하려는 패키지 이름으로 바꿉니다.

  3. 변경사항을 커밋하고 푸시합니다.

다음 코드 샘플은 js 블록으로 가져오고 SQLX 파일의 SELECT 문에서 사용된 postoffice 패키지의 getDomain 함수를 보여줍니다.

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const { getDomain } = require("postoffice");
}

SELECT ${getDomain("email")} as test

Dataform에서 SQLX 파일로 전체 패키지 가져오기

선택한 함수 또는 상수를 JavaScript 파일로 가져오는 대신 전체 패키지를 SQLX 파일로 가져오려면 다음 단계를 수행합니다.

  1. 작업공간의 파일 창에서 패키지를 사용하려는 .sqlx 파일을 선택합니다.

  2. 파일에서 다음 형식으로 패키지를 가져옵니다.

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. CONSTANT-NAME을 상수 이름으로 바꿉니다.
    2. PACKAGE-NAME을 사용하려는 패키지 이름으로 바꿉니다.

  3. 변경사항을 커밋하고 푸시합니다.

다음 코드 샘플은 js 블록으로 가져온 postoffice 패키지와 SQLX 파일의 SELECT 문에서 사용된 getDomain 함수를 보여줍니다.

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const postoffice = require("postoffice");
}

SELECT ${postoffice.getDomain("email")} as test

다음 단계