외부 데이터 소스의 테이블 정의 파일 만들기

이 페이지에서는 외부 데이터 소스용 테이블 정의 파일을 만드는 방법을 설명합니다. 외부 데이터 소스는 데이터가 BigQuery에 저장되어 있지는 않지만 직접 쿼리할 수 있는 데이터 소스입니다.

테이블 정의 파일에는 외부 테이블의 스키마 정의와 메타데이터(예: 테이블의 데이터 형식 및 관련 속성)가 포함됩니다. 테이블 정의 파일을 만들 때 스키마 자동 감지를 사용하여 외부 데이터 소스의 스키마를 정의할 수 있습니다. 스키마를 인라인으로 제공하거나 스키마 정의가 포함된 JSON 파일을 제공할 수 있습니다.

테이블 정의 파일은 bq 명령줄 도구 내에서 사용됩니다. 테이블 정의 파일의 속성은 REST API 사용 시 ExternalDataConfiguration 생성에도 적용됩니다. Google Cloud 콘솔을 사용하여 외부 테이블을 만들 때는 테이블 정의 파일을 사용하지 않습니다.

다음 외부 데이터 소스의 영구 또는 임시 외부 테이블을 설명하는 테이블 정의 파일을 만들 수 있습니다.

• Cloud Storage

  • 쉼표로 구분된 값(CSV)
  • 줄바꿈으로 구분된 JSON
  • Avro 파일
  • Datastore 내보내기 파일
  • ORC 파일
  • Parquet 파일
  • Firestore 내보내기 파일

• Google Drive

  • 쉼표로 구분된 값(CSV)
  • 줄바꿈으로 구분된 JSON
  • Avro 파일
  • Google Sheets

• Bigtable

시작하기 전에

테이블 정의 파일을 만들려면 데이터 소스의 URI가 필요합니다.

• Drive 데이터 소스의 경우 Drive URI가 필요합니다.
• Cloud Storage 데이터 소스의 경우 Cloud Storage URI가 필요합니다.
• Bigtable 데이터 소스의 경우 Bigtable URI가 필요합니다.

CSV, JSON 또는 Google 스프레드시트 파일의 정의 파일 만들기

다음 방법 중 하나를 사용하여 Cloud Storage 또는 Drive에 CSV, JSON 또는 Google 스프레드시트 파일에 대한 테이블 정의 파일을 만듭니다.

• autodetect 플래그 사용
• 인라인 스키마 사용
• JSON 스키마 파일 사용

autodetect 플래그 사용

인라인 스키마 설명이나 스키마 파일을 포함하지 않고 CSV, JSON 또는 Google 스프레드시트 파일을 지정하는 경우 --autodetect 플래그를 사용하여 테이블 정의 파일에서 "autodetect" 옵션을 true로 설정할 수 있습니다. 스키마 자동 감지가 사용 설정되면 BigQuery는 기존 정보를 최대한 활용하여 스키마를 자동으로 유추합니다. 자세한 내용은 외부 데이터 소스의 스키마 자동 감지를 참조하세요.

Cloud Storage 데이터 소스에서 자동 감지 사용

Cloud Storage 데이터 소스에 테이블 정의 파일을 만듭니다.

1. bq mkdef 명령어를 --autodetect 플래그와 함께 사용하여 테이블 정의 파일을 만듭니다. mkdef 명령어는 JSON 형식의 테이블 정의 파일을 생성합니다. 다음 예시에서는 테이블 정의를 만들고 출력을 /tmp/file_name 파일에 씁니다.

   bq mkdef \
     --autodetect \
     --source_format=SOURCE_FORMAT \
     "URI" > /tmp/FILE_NAME

   다음을 바꿉니다.

   • SOURCE_FORMAT: 파일 형식
   • FILE_NAME: 테이블 정의 파일의 이름

   • URI: Cloud Storage URI

     예를 들면 gs://mybucket/myfile입니다.

2. (선택사항) 테이블 정의 파일을 텍스트 편집기에서 엽니다. 예를 들어 명령어 nano /tmp/file_name은 이 파일을 nano에서 엽니다. CSV 외부 데이터 소스의 경우 파일은 다음과 같이 나타납니다. "autodetect"가 true로 설정되어 있습니다.

   {
   "autodetect": true,
   "csvOptions": {
     "allowJaggedRows": false,
     "allowQuotedNewlines": false,
     "encoding": "UTF-8",
     "fieldDelimiter": ",",
     "quote": "\"",
     "skipLeadingRows": 0
   },
   "sourceFormat": "CSV",
   "sourceUris": [
     "URI"
   ]
   }

3. (선택사항) 테이블 정의 파일을 수동으로 수정하여 maxBadRecords 및 ignoreUnknownValues와 같은 일반 설정을 수정, 추가 또는 삭제합니다. JSON 소스 파일에만 적용되는 구성 설정은 없지만 CSV 및 Google 스프레드시트 파일에 적용되는 설정이 있습니다. 자세한 내용은 API 참조에서 ExternalDataConfiguration을 참조하세요.

Drive 데이터 소스에서 자동 감지 사용

Drive 데이터 소스에 테이블 정의 파일을 만듭니다.

1. bq mkdef 명령어를 --autodetect 플래그와 함께 사용하여 테이블 정의를 만듭니다. mkdef 명령어는 JSON 형식의 테이블 정의 파일을 생성합니다. 다음 예시에서는 테이블 정의를 만들고 출력을 /tmp/file_name 파일에 씁니다.

   bq mkdef \
      --autodetect \
      --source_format=SOURCE_FORMAT \
      "URI" > /tmp/FILE_NAME

   다음을 바꿉니다.

   • SOURCE_FORMAT: 파일 형식
   • FILE_NAME: 테이블 정의 파일의 이름

   • URI: Drive URI

     예를 들면 https://drive.google.com/open?id=123ABCD123AbcD123Abcd입니다.

2. 테이블 정의 파일을 텍스트 편집기에서 엽니다. 예를 들어 명령어 nano /tmp/file_name은 이 파일을 nano에서 엽니다. Google 스프레드시트 외부 데이터 소스의 경우 파일은 다음과 같이 나타납니다. "autodetect"가 true로 설정되어 있습니다.

   {
   "autodetect": true,
   "sourceFormat": "GOOGLE_SHEETS",
   "sourceUris": [
     "URI"
   ]
   }

3. (선택사항) 테이블 정의 파일을 수동으로 수정하여 maxBadRecords 및 ignoreUnknownValues와 같은 일반 설정을 수정, 추가 또는 삭제합니다. JSON 소스 파일에만 적용되는 구성 설정은 없지만 CSV 및 Google 스프레드시트 파일에 적용되는 설정이 있습니다. 자세한 내용은 API 참조에서 ExternalDataConfiguration을 참조하세요.

4. Google 스프레드시트 파일에서 특정 시트 또는 셀 범위를 지정하려면 테이블 정의 파일에 range 속성을 추가합니다. 특정 시트를 쿼리하려면 시트 이름을 지정합니다. 셀 범위를 쿼리하려면 범위를 sheet_name!top_left_cell_id:bottom_right_cell_id 형식(예: "Sheet1!A1:B20")으로 지정합니다. range 매개변수를 지정하지 않으면 파일의 첫 번째 시트가 사용됩니다.

인라인 스키마 사용

스키마 자동 감지를 사용하지 않으려면 인라인 스키마 정의를 제공하여 테이블 정의 파일을 만들 수 있습니다. 인라인 스키마 정의를 제공하려면 명령줄에서 필드 및 데이터 유형을 FIELD:DATA_TYPE,FIELD:DATA_TYPE 형식으로 나열합니다.

Cloud Storage 또는 Drive 데이터 소스에 인라인 스키마 사용

인라인 스키마 정의를 사용하여 Cloud Storage 또는 Drive 데이터 소스에 테이블 정의를 만듭니다.

1. bq mkdef 명령어를 --noautodetect 플래그와 함께 사용하여 테이블 정의를 만듭니다. mkdef 명령어는 JSON 형식의 테이블 정의 파일을 생성합니다. 다음 예시에서는 테이블 정의를 만들고 출력을 /tmp/file_name 파일에 씁니다.

   bq mkdef \
     --noautodetect \
     --source_format=SOURCE_FORMAT \
     "URI" \
     FIELD:DATA_TYPE,FIELD:DATA_TYPE > /tmp/FILE_NAME

   다음을 바꿉니다.

   • SOURCE_FORMAT: 소스 파일 형식

   • URI: Cloud Storage URI 또는 Drive URI

     예를 들면 Cloud Storage의 경우 gs://mybucket/myfile, Drive의 경우 https://drive.google.com/open?id=123ABCD123AbcD123Abcd입니다.

   • FIELD:DATA_TYPE,FIELD:DATA_TYPE: 스키마 정의

     예를 들면 Name:STRING,Address:STRING, ...입니다.

   • FILE_NAME: 테이블 정의 파일의 이름

2. (선택사항) 테이블 정의 파일을 텍스트 편집기에서 엽니다. 예를 들어 명령어 nano /tmp/file_name은 이 파일을 nano에서 엽니다. 파일은 다음과 같이 나타납니다. "autodetect"는 사용 설정되어 있지 않으며 스키마 정보는 테이블 정의 파일에 기록되어 있습니다.

   {
   "schema": {
     "fields": [
       {
         "name": "FIELD",
         "type": "DATA_TYPE"
       },
       {
         "name": "FIELD",
         "type": "DATA_TYPE"
       }
       ...
     ]
   },
   "sourceFormat": "NEWLINE_DELIMITED_JSON",
   "sourceUris": [
     "URI"
   ]
   }

3. (선택사항) 테이블 정의 파일을 수동으로 수정하여 maxBadRecords 및 ignoreUnknownValues와 같은 일반 설정을 수정, 추가 또는 삭제합니다. JSON 소스 파일에만 적용되는 구성 설정은 없지만 CSV 및 Google 스프레드시트 파일에 적용되는 설정이 있습니다. 자세한 내용은 API 참조에서 ExternalDataConfiguration을 참조하세요.

JSON 스키마 파일 사용

자동 감지를 사용하지 않으려면 또는 인라인 스키마 정의를 제공하려면 JSON 스키마 파일을 만들고 테이블 정의 파일을 만들 때 이 파일을 참조합니다. 로컬 머신에서 수동으로 JSON 스키마 파일을 만듭니다. Cloud Storage나 Drive에 저장된 JSON 스키마 파일에 대한 참조는 지원되지 않습니다.

Cloud Storage 데이터 소스에 스키마 파일 사용

JSON 스키마 파일을 사용하여 Cloud Storage 데이터 소스의 테이블 정의를 만듭니다.

1. bq mkdef 명령어를 --noautodetect 플래그와 함께 사용하여 테이블 정의를 만듭니다. mkdef 명령어는 JSON 형식의 테이블 정의 파일을 생성합니다. 다음 예시에서는 테이블 정의를 만들고 출력을 /tmp/file_name 파일에 씁니다.

   bq mkdef \
      --noautodetect \
      --source_format=SOURCE_FORMAT \
      "URI" \
     PATH_TO_SCHEMA_FILE > /tmp/FILE_NAME

   다음을 바꿉니다.

   • SOURCE_FORMAT: 파일 형식
   • FILE_NAME: 테이블 정의 파일의 이름

   • URI: Cloud Storage URI

     예를 들면 gs://mybucket/myfile입니다.

   • PATH_TO_SCHEMA_FILE: 로컬 머신의 JSON 스키마 파일 위치

2. (선택사항) 테이블 정의 파일을 텍스트 편집기에서 엽니다. 예를 들어 명령어 nano /tmp/file_name은 이 파일을
   nano에서 엽니다. 파일은 다음과 같이 나타납니다. "autodetect"는 사용 설정되어 있지 않으며 스키마 정보는 테이블 정의 파일에 기록되어 있습니다.

   {
   "schema": {
     "fields": [
       {
         "name": "FIELD",
         "type": "DATA_TYPE"
       },
       {
         "name": "FIELD",
         "type": "DATA_TYPE"
       }
       ...
     ]
   },
   "sourceFormat": "NEWLINE_DELIMITED_JSON",
   "sourceUris": [
     "URI"
   ]
   }

3. (선택사항) 테이블 정의 파일을 수동으로 수정하여 maxBadRecords 및 ignoreUnknownValues와 같은 일반 설정을 수정, 추가 또는 삭제합니다. JSON 소스 파일에만 적용되는 구성 설정은 없지만 CSV 및 Google 스프레드시트 파일에 적용되는 설정이 있습니다. 자세한 내용은 API 참조에서 ExternalDataConfiguration을 참조하세요.

Drive 데이터 소스에 스키마 파일 사용

JSON 스키마 파일을 사용하여 Drive 데이터 소스의 테이블 정의를 만듭니다.

1. bq mkdef 명령어를 --noautodetect 플래그와 함께 사용하여 테이블 정의를 만듭니다. mkdef 명령어는 JSON 형식의 테이블 정의 파일을 생성합니다. 다음 예시에서는 테이블 정의를 만들고 출력을 /tmp/file_name 파일에 씁니다.

   bq mkdef \
      --noautodetect \
      --source_format=source_format \
      "URI" \
      PATH_TO_SCHEMA_FILE > /tmp/FILE_NAME

   다음을 바꿉니다.

   • SOURCE_FORMAT: 소스 파일 형식

   • URI: Drive URI

     예를 들면 https://drive.google.com/open?id=123ABCD123AbcD123Abcd입니다.

   • PATH_TO_SCHEMA_FILE: 로컬 머신의 JSON 스키마 파일 위치

   • FILE_NAME: 테이블 정의 파일의 이름

2. 테이블 정의 파일을 텍스트 편집기에서 엽니다. 예를 들어 명령어 nano /tmp/file_name은 이 파일을 nano에서 엽니다. 파일은 다음과 같이 나타납니다. "autodetect"는 사용 설정되어 있지 않으며 스키마 정보는 테이블 정의 파일에 기록되어 있습니다.

   {
   "schema": {
     "fields": [
       {
         "name": "FIELD",
         "type": "DATA_TYPE"
       },
       {
         "name": "FIELD",
         "type": "DATA_TYPE"
       }
       ...
     ]
   },
   "sourceFormat": "GOOGLE_SHEETS",
   "sourceUris": [
     "URI"
   ]
   }

3. (선택사항) 테이블 정의 파일을 수동으로 수정하여 maxBadRecords 및 ignoreUnknownValues와 같은 일반 설정을 수정, 추가 또는 삭제합니다. JSON 소스 파일에만 적용되는 구성 설정은 없지만 CSV 및 Google 스프레드시트 파일에 적용되는 설정이 있습니다. 자세한 내용은 API 참조에서 ExternalDataConfiguration을 참조하세요.

4. Google 스프레드시트 파일에서 특정 시트 또는 셀 범위를 지정하려면 테이블 정의 파일에 range 속성을 추가합니다. 특정 시트를 쿼리하려면 시트 이름을 지정합니다. 셀 범위를 쿼리하려면 범위를 sheet_name!top_left_cell_id:bottom_right_cell_id 형식(예: "Sheet1!A1:B20")으로 지정합니다. range 매개변수를 지정하지 않으면 파일의 첫 번째 시트가 사용됩니다.

자체 설명적 형식의 정의 파일 만들기

Avro, Parquet, ORC는 자체 설명적 형식입니다. 이러한 형식의 데이터 파일에는 고유한 스키마 정보가 있습니다. 이러한 형식 중 하나를 외부 데이터 소스로 사용하는 경우 BigQuery는 소스 데이터를 사용하여 스키마를 자동으로 가져옵니다. 테이블 정의를 만들 때 스키마 자동 감지를 사용할 필요가 없으며 인라인 스키마 정의 또는 스키마 파일을 제공할 필요도 없습니다.

Cloud Storage 또는 Drive에 저장된 Avro, Parquet, ORC 데이터의 테이블 정의 파일을 만들 수 있습니다.

1. bq mkdef 명령어를 사용하여 테이블 정의를 만듭니다.

   bq mkdef \
       --source_format=FORMAT \
       "URI" > FILE_NAME

   다음을 바꿉니다.

   • FORMAT: 소스 형식

   • URI: Cloud Storage URI 또는 Drive URI

     예를 들면 Cloud Storage의 경우 gs://mybucket/myfile, Drive의 경우 https://drive.google.com/open?id=123ABCD123AbcD123Abcd입니다.

   • FILE_NAME: 테이블 정의 파일의 이름

2. (선택사항) 테이블 정의 파일을 텍스트 편집기에서 엽니다. 파일은 다음과 유사합니다.

   {
      "sourceFormat": "AVRO",
      "sourceUris": [
      "URI"
       ]
   }

3. (선택사항) 테이블 정의 파일을 수동으로 수정하여 maxBadRecords 및 ignoreUnknownValues와 같은 일반 설정을 수정, 추가, 삭제합니다. 자세한 내용은 API 참조에서 ExternalDataConfiguration을 참조하세요.

하이브 파티션을 나눈 데이터용 정의 파일 만들기

hive_partitioning_mode 및 hive_partitioning_source_uri_prefix 플래그와 함께 bq mkdef 명령어를 사용하여 Cloud Storage, Amazon Simple Storage Service(Amazon S3) 또는 Azure Blob Storage에 저장된 하이브 파티션을 나눈 데이터의 정의 파일을 만듭니다.

Datastore 및 Firestore용 정의 파일 만들기

Datastore 또는 Firestore 내보내기를 외부 데이터 소스로 사용하는 경우 BigQuery는 자체 설명적 소스 데이터를 사용하여 스키마를 자동으로 가져옵니다. 테이블 정의를 만들 때 인라인 스키마 정의 또는 스키마 파일을 제공할 필요가 없습니다.

Cloud Storage에 저장된 Datastore 및 Firestore 내보내기 데이터의 테이블 정의 파일을 만들 수 있습니다.

1. bq mkdef 명령어를 사용하여 테이블 정의를 만듭니다. --noautodetect 플래그를 Datastore 또는 Firestore 백업 파일과 함께 사용할 필요가 없습니다. 이러한 파일 유형에는 스키마 자동 감지가 사용 중지되어 있습니다. mkdef 명령어는 JSON 형식의 테이블 정의 파일을 생성합니다. 다음 예시에서는 테이블 정의를 만들고 출력을 /tmp/file_name 파일에 씁니다.

   bq mkdef \
   --source_format=DATASTORE_BACKUP \
   "URI" > /tmp/FILE_NAME

   다음을 바꿉니다.

   • URI: Cloud Storage URI
   • FILE_NAME: 테이블 정의 파일의 이름

   DATASTORE_BACKUP 소스 형식은 Datastore 및 Firestore 모두에 사용됩니다.

2. (선택사항) 테이블 정의 파일을 텍스트 편집기에서 엽니다. 예를 들어 명령어 nano /tmp/file_name은 이 파일을 nano에서 엽니다. 파일은 다음과 같이 나타납니다. "autodetect" 설정은 필요하지 않습니다.

   {
   "sourceFormat": "DATASTORE_BACKUP",
   "sourceUris": [
     "gs://URI"
   ]
   }

3. (선택사항) 테이블 정의 파일을 수동으로 수정하여 maxBadRecords 및 ignoreUnknownValues와 같은 일반 설정을 수정, 추가 또는 삭제합니다. Datastore 및 Firestore 내보내기 파일에만 적용되는 구성 설정은 없습니다. 자세한 내용은 API 참조에서 ExternalDataConfiguration을 참조하세요.

Bigtable용 정의 파일 만들기

Bigtable에 대한 테이블 정의 파일을 만들 때는 수동으로 JSON 형식의 파일을 생성해야 합니다. mkdef 명령어를 사용하여 테이블 정의를 만드는 방식은 현재 Bigtable 데이터 소스에 지원되지 않습니다. Bigtable에는 스키마 자동 감지도 지원되지 않습니다. Bigtable 테이블 정의 옵션의 목록은 REST API 참조에서 BigtableOptions를 참조하세요.

Bigtable에 대한 JSON 테이블 정의 파일은 다음과 같습니다. BigQuery는 이 테이블 정의 파일을 사용하여 단일 column family에서 데이터를 읽고 그 값을 바이너리로 인코딩된 정수로 해석합니다.

{
    "sourceFormat": "BIGTABLE",
    "sourceUris": [
        "https://googleapis.com/bigtable/projects/PROJECT_ID/instances/INSTANCE_ID/tables/TABLE_NAME"
    ],
    "bigtableOptions": {
        "columnFamilies" : [
            {
                "familyId": "FAMILY_ID",
                "type": "INTEGER",
                "encoding": "BINARY"
            }
        ]
    }
}

다음을 바꿉니다.

• PROJECT_ID: Bigtable 클러스터가 포함된 프로젝트
• INSTANCE_ID: Bigtable 인스턴스 ID
• TABLE_NAME: 쿼리중인 테이블의 이름
• FAMILY_ID: column family 식별자

자세한 내용은 Bigtable URI 검색을 참조하세요.

테이블 정의 파일의 와일드 카드 지원

데이터가 여러 개의 파일로 분리되어 있는 경우 별표(*) 와일드 카드를 사용하여 여러 파일을 선택할 수 있습니다. 별표 와일드 카드를 사용하려면 다음 규칙을 따라야 합니다.

• 와일드 카드는 객체 이름 중간이나 끝에 입력할 수 있습니다.
• 별표 여러 개를 사용하는 것은 지원되지 않습니다. 예를 들어 gs://mybucket/fed-*/temp/*.csv 경로는 유효하지 않습니다.
• 버킷 이름에 별표를 사용하는 것은 지원되지 않습니다.

예를 들면 다음과 같습니다.

• 다음 예시에서는 프리픽스 gs://mybucket/fed-samples/fed-sample로 시작하는 모든 폴더의 모든 파일을 선택하는 방법을 보여줍니다.

  gs://mybucket/fed-samples/fed-sample*
  

• 다음 예시에서는 fed-samples라는 폴더와 fed-samples의 모든 하위 폴더에 있는 .csv 확장자가 있는 파일만 선택하는 방법을 보여줍니다.

  gs://mybucket/fed-samples/*.csv
  

• 다음 예시에서는 fed-samples라는 폴더에 있는 이름 지정 패턴이 fed-sample*.csv인 파일을 선택하는 방법을 보여줍니다. 이 예시에서는 fed-samples 하위 폴더에 있는 파일을 선택하지 않습니다.

  gs://mybucket/fed-samples/fed-sample*.csv
  

bq 명령줄 도구를 사용할 때 일부 플랫폼에서 별표를 이스케이프 처리해야 할 수도 있습니다.

별표 와일드 카드를 사용할 경우 버킷과 파일 이름을 따옴표로 묶습니다. 예를 들어 fed-sample000001.csv와 fed-sample000002.csv라는 파일 두 개가 있고 별표를 사용하여 두 파일을 모두 선택하려면 버킷 URI는 "gs://mybucket/fed-sample*"이 됩니다.

다음 데이터 소스의 테이블 정의 파일을 만들 때는 * 와일드 카드 문자가 허용되지 않습니다.

• Bigtable. Bigtable 데이터의 경우 데이터 소스를 하나만 지정할 수 있습니다. URI 값은 Bigtable 테이블의 유효한 HTTPS URL이어야 합니다.
• Datastore 또는 Firestore. Cloud Storage에 저장된 Datastore 또는 Firestore 내보내기. Datastore 백업의 경우 데이터 소스를 하나만 지정할 수 있습니다. URI 값은 .backup_info 또는 .export_metadata로 끝나야 합니다.
• Drive. Drive에 저장된 데이터

다음 단계

• Cloud Storage 데이터 쿼리 방법 알아보기
• Drive 데이터 쿼리 방법 알아보기
• Bigtable 데이터 쿼리 방법 알아보기