이 페이지는 Cloud Translation API를 통해 번역되었습니다.

BigQuery로 내보내기

개요

Earth Engine의 계산 아키텍처는 이미지(픽셀 기반) 계산을 빠르고 확장 가능하게 만드는 데 최적화되어 있습니다. BigQuery는 마찬가지로 테이블 형식 데이터 (벡터)의 확장 가능한 처리에 최적화되어 있으며 Earth Engine을 보완하는 여러 기능을 갖추고 있습니다.

워크플로의 예는 다음과 같습니다.

Earth Engine에서 생성된 데이터에 대규모 BigQuery 조인 실행
BigQuery에서 추가 처리를 위해 이미지에서 파생된 통계로 벡터 데이터에 주석 추가
Earth Engine에서 추가 가능한 BigQuery 테이블로 주기적으로 데이터 내보내기

다른 멋진 사용 사례가 있으면 공유해 주세요.

BigQuery 기본사항

Earth Engine은 BigQuery 테이블에 작성하며 모든 테이블은 데이터 세트에 포함됩니다. 지정된 데이터 세트가 BigQuery에 없으면 내보내기 작업이 실패합니다. BigQuery 데이터 세트 소개에서 자세히 알아보세요.

데이터 세트 만들기

데이터 세트에는 이름, 스토리지 리전, 만료 동작을 비롯한 여러 생성 시간 옵션과 몇 가지 고급 옵션이 있습니다.

데이터 세트를 만드는 메커니즘은 다양하지만 Cloud 콘솔을 통해 시작하는 것이 가장 간단합니다.

Cloud 콘솔의 BigQuery 페이지로 이동합니다.
메시지가 표시되면 '사용 설정'을 클릭하여 API를 사용 설정합니다.
'SQL Workspace' 탭에서 프로젝트 옆에 있는 점 3개 메뉴()를 클릭합니다.
'데이터 세트 만들기' 옵션을 선택합니다.
구성 가이드를 따릅니다.

데이터 세트를 만들고 구성하는 모든 옵션은 BigQuery 문서를 참고하세요.

권한

호출자는 Earth Engine을 사용하는 데 필요한 표준 역할 및 권한 외에도 Cloud 프로젝트 또는 데이터 세트에 대한 올바른 BigQuery 권한도 필요합니다.

bigquery.tables.get
bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.delete
bigquery.jobs.create

다음과 같은 사전 정의된 Identity and Access Management(IAM) 역할 조합에는 필요한 권한이 포함되어 있습니다.

bigquery.dataEditor + bigquery.jobUser
bigquery.dataOwner + bigquery.jobUser
bigquery.user
bigquery.admin

가격 책정

BigQuery는 유료 Google Cloud 서비스이므로 BigQuery로 내보내는 Earth Engine 데이터의 저장소 및 분석을 비롯하여 BigQuery 사용에 대한 요금이 청구됩니다.

Earth Engine의 BigQuery 내보내기 기능 가격 책정에 관한 자세한 내용은 아래의 가격 책정 섹션을 참고하세요.

구성 내보내기

구문

코드 편집기 (JavaScript)

Export.table.toBigQuery({
  collection: features,
  table: 'myproject.mydataset.mytable',
  description: 'put_my_data_in_bigquery',
  append: true,
  overwrite: false
});

Python 설정

Python API 및 대화형 개발을 위한 geemap 사용에 관한 자세한 내용은 Python 환경 페이지를 참고하세요.

import ee
import geemap.core as geemap

Colab (Python)

task = ee.batch.Export.table.toBigQuery(
    collection=features,
    table='myproject.mydataset.mytable',
    description='put_my_data_in_bigquery',
    append=True,
    overwrite=False,
)
task.start()

자동 또는 수동 스키마 사양

BigQuery에 테이블이 없으면 Earth Engine은 컬렉션의 첫 번째 ee.Feature의 속성을 사용하여 스키마를 결정하려고 시도합니다. 이는 최선의 추측이며 첫 번째 지형지물의 스키마가 다른 지형지물의 스키마와 다른 컬렉션을 구성할 수 있습니다.

BigQuery 테이블에 특정 스키마가 필요한 경우 대상 스키마로 빈 테이블을 만들어 구성합니다.

속성 이름

Earth Engine 지형지물의 속성은 BigQuery의 열에 해당합니다. Earth Engine은 ee.Feature 도형('.geo' 선택기)을 BigQuery에 쓸 때 'geo'라는 이름을 사용합니다.

이름을 바꾸지 않으려면 ee.Feature 객체에 유효한 열 이름 속성이 있고 'geo'라는 이름이 없는지 확인합니다. 이 이름은 Earth Engine에 이름이 없는 지형지물의 도형에 사용되기 때문입니다.

속성 이름에 유효하지 않은 문자가 있으면 BigQuery 열 이름에 대한 제한사항으로 인해 내보내기에 실패합니다.

유형 변환

Earth Engine (ee.Feature 속성의 값) 데이터는 가능한 경우 상응하는 BigQuery 유형으로 변환됩니다. null 허용 여부는 유형이 아닌 테이블 스키마에서 제어합니다.

Earth Engine 유형	BigQuery 유형	참고
`ee.String`	`STRING`
`ee.Number`	`FLOAT` 또는 `INTEGER`
`ee.Geometry`	`GEOGRAPHY`
`ee.Date`	`TIMESTAMP`
`ee.ByteString`	`BYTES`
`ee.Array`	`STRUCT<ARRAY<INT64>,` `ARRAY<INT64\|FLOAT64>>`	배열 섹션을 참고하세요.
기타 `ee.*` 유형	지원되지 않음	JSON 값 섹션을 참고하세요.

배열

Earth Engine은 BigQuery의 ML.DECODE_IMAGE 함수에서 사용하는 형식과 마찬가지로 모든 다차원 ee.Array를 STRUCT<ARRAY<INT64> dimensions, ARRAY<INT64|FLOAT64> values>로 내보냅니다.

구조체의 첫 번째 배열인 dimensions에는 Earth Engine 배열의 크기인 $d_1$ ~ $d_n$이 포함됩니다.

구조체의 두 번째 배열인 values에는 다차원 배열의 모든 값이 포함되며 단일 BigQuery 배열로 평면화됩니다. 평면 배열의 총 값 수는 $\sum_{i=1}^n d_i$이고 원래 Earth Engine 배열의 색인 $(i_i, \ldots, i_n)$ 의 값은 평면 배열의 다음 색인에 있는 값에 해당합니다.

\[ \sum_{j=1}^n \left( i_j \cdot \prod_{k=j+1}^n d_k \right) \]

일반적인 경우 values 배열의 색인 표현식은 다음과 같습니다.

배열 크기	크기	색인 생성 표현식
1차원	`d1`	`[i1]`
2차원	`d1, d2`	`[(i1 * d2) + i2]`
3차원	`d1, d2, d3`	`[(i1 * d2 * d3) + (i2 * d3) + i3]`

예를 들어 2x3x4 Earth Engine 배열을 생각해 보겠습니다.

    ee.Array([
      [
        [1, 2, 3, 4],
        [5, 6, 7, 8],
        [9, 10, 11, 12]
      ],
      [
        [13, 14, 15, 16],
        [17, 18, 19, 20],
        [21, 22, 23, 24]
      ]
    ]);

이 배열은 dimensions 요소가 배열 [2, 3, 4]이고 values 요소가 평면화된 배열 [1, 2, 3, 4, 5, 6, 7, 8, ..., 21, 22, 23, 24]인 BigQuery STRUCT로 변환됩니다. 평면화된 배열의 색인은 [(i1 * 12) + (i2 * 4) + i3]로 계산할 수 있습니다.

JSON 값

셀 내에서 더 풍부한 구조의 데이터를 지원하려면 Earth Engine 값을 JSON 객체로 인코딩하면 됩니다. BigQuery는 JSON 인코딩 데이터에 대한 SQL 작업을 지원하므로 Earth Engine에서 생성한 인코딩된 JSON 값을 '내부에서 살펴보는' 쿼리를 실행할 수 있습니다.

코드 편집기 (JavaScript)

var states = ee.FeatureCollection('TIGER/2018/States');
var mod11a1 = ee.ImageCollection('MODIS/061/MOD11A1');

// Find the max day and night temperatures per pixel for a given time.
var maxTemp = mod11a1
    .select(['LST_Day_1km', 'LST_Night_1km'])
    .filterDate('2023-05-15', '2023-05-25')
    .max();

// Annotate each state with its max day/night temperatures.
var annotatedStates = states.map(function (e) {
  var dict = maxTemp.reduceRegion({
    reducer: ee.Reducer.max(),
    geometry: e.geometry(),
    scale: 10 * 1000,  // 10 km
  });
  // Convert the dictionary to JSON and add it as a property.
  return e.set('maxTemp', ee.String.encodeJSON(dict));
});

Export.table.toBigQuery(annotatedStates);

Python 설정

Python API 및 대화형 개발을 위한 geemap 사용에 관한 자세한 내용은 Python 환경 페이지를 참고하세요.

import ee
import geemap.core as geemap

Colab (Python)

states = ee.FeatureCollection('TIGER/2018/States')
mod11a1 = ee.ImageCollection('MODIS/061/MOD11A1')

# Find the max day and night temperatures per pixel for a given time.
max_temp = (
    mod11a1.select(['LST_Day_1km', 'LST_Night_1km'])
    .filterDate('2023-05-15', '2023-05-25')
    .max()
)


def get_max_temp_for_state(e):
  max_temp_dict = max_temp.reduceRegion(
      reducer=ee.Reducer.max(),
      geometry=e.geometry(),
      scale=10 * 1000,  # 10 km
  )
  # Convert the dictionary to JSON and add it as a property.
  return e.set('maxTemp', ee.String.encodeJSON(max_temp_dict))


# Annotate each state with its max day/night temperatures.
annotated_states = states.map(get_max_temp_for_state)

task = ee.batch.Export.table.toBigQuery(
    collection=annotated_states, table='myproject.mydataset.mytable'
)
task.start()

도형 변환

BigQuery는 다양한 투영을 제한적으로 지원하므로 모든 Earth Engine 도형은 오류 마진 1m를 사용하여 지오데시ック EPSG:4326로 변환됩니다.

이 변환 프로세스를 더 세부적으로 제어하려면 지형지물을 수동으로 매핑하고 도형을 변환하면 됩니다.예를 들면 다음과 같습니다.

코드 편집기 (JavaScript)

var transformedCollection = originalCollection.map(function transformGeo(e) {
  var myErrorMargin = 10 * 1000;  // meters
  return e.setGeometry(e.geometry(myErrorMargin, 'EPSG:4326', true));
});

Python 설정

Python API 및 대화형 개발을 위한 geemap 사용에 관한 자세한 내용은 Python 환경 페이지를 참고하세요.

import ee
import geemap.core as geemap

Colab (Python)

def transform_geo(e):
  my_error_margin = 10 * 1000  # meters
  return e.setGeometry(e.geometry(my_error_margin, 'EPSG:4326', True))


transformed_collection = original_collection.map(transform_geo)

성능

Earth Engine 성능

Earth Engine 계산은 종종 Export 작업의 병목 현상입니다. 이를 위해 최대한의 동시 로드를 위해 처리를 구성하는 것이 중요합니다. 직렬 처리에서 베이킹되는 모든 계산 (예: ee.FeatureCollection.iterate())으로 인해 내보내기가 느리게 실행되거나 실패할 수 있습니다.

BigQuery의 성능

데이터를 올바르게 구조화하고 클러스터링하는 것이 BigQuery에서 효율적인 쿼리를 실행하는 가장 좋은 방법입니다. BigQuery에 아직 테이블이 없는 경우 Earth Engine에서 내보낸 테이블은 지형지물의 도형 (있는 경우)에 따라 클러스터링됩니다. 지리 필드별 클러스터링은 지리정보 데이터에서 매우 일반적입니다. 공간 필터를 사용하는 쿼리의 성능을 개선하고 비용을 절감합니다. 주로 다음과 같은 BigQuery 작업에 사용됩니다.

WHERE ST_DWithin(<table_column>, <constant_geography>, <distance>)

WHERE ST_Intersects(<table_column>, <constant_geography>)

클러스터링되지 않은 테이블에 클러스터링을 추가해도 일반적으로 아무런 문제가 없지만 테이블에 데이터를 로드하는 시간이 약간 늘어날 수 있습니다. 쿼리 최적화에 관한 자세한 내용은 BigQuery 문서를 참고하세요.

클러스터링 설정은 테이블에 쓰여진 새 데이터에만 영향을 미칩니다.

데모: `reduceRegions` 사용

경우에 따라 reduceRegions를 사용하여 Earth Engine 처리 인프라에서 최대한 많은 동시 로드를 얻을 수 있습니다. 이 예에서는 수만 개의 reduceRegion 호출 (컬렉션에 함수를 매핑하는 일반적인 접근 방식) 대신 적은 수의 reduceRegions 호출 (수백 개)을 사용하는 방법을 보여줍니다.

코드 편집기 (JavaScript)

var lucas = ee.FeatureCollection('JRC/LUCAS_HARMO/COPERNICUS_POLYGONS/V1/2018');
var s2 = ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED');

// Fetch the unique date values from the dataset.
var dates = lucas.aggregate_array('survey_date')
    .distinct()
    .map(function (date) {
      return ee.Date.parse('dd/MM/yy', date);
    });

// For each date, annotate the LUCAS samples with the Sentinel-2 band values for
// a two-week window.
function getLucasSamplesForDate(date) {
  date = ee.Date(date);
  var imageForDate = s2
    .filterDate(
      date.advance(-1, 'week'),
      date.advance(1, 'week'))
    .select('B.*');
  var median = imageForDate.median();
  var lucasForDate = lucas.filter(
    ee.Filter.equals('survey_date', date.format('dd/MM/yy')));
  var sample = median.reduceRegions({
    collection: lucasForDate,
    reducer: ee.Reducer.mean(),
    scale: 10,
    tileScale: 8,
  });
  return sample;
}

// Flatten the collection.
var withSamples =
    ee.FeatureCollection(dates.map(getLucasSamplesForDate))
      .flatten();

Export.table.toBigQuery({
  collection: withSamples,
  description: 'lucas_s2_annotated'
});

Python 설정

Python API 및 대화형 개발을 위한 geemap 사용에 관한 자세한 내용은 Python 환경 페이지를 참고하세요.

import ee
import geemap.core as geemap

Colab (Python)

lucas = ee.FeatureCollection('JRC/LUCAS_HARMO/COPERNICUS_POLYGONS/V1/2018')
s2 = ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED')

# Fetch the unique date values from the dataset.
dates = (
    lucas.aggregate_array('survey_date')
    .distinct()
    .map(lambda date: ee.Date.parse('dd/MM/yy', date))
)


# For each date, annotate the LUCAS samples with the Sentinel-2 band values for
# a two-week window.
def get_lucas_samples_for_date(date):
  date = ee.Date(date)
  image_for_date = s2.filterDate(
      date.advance(-1, 'week'), date.advance(1, 'week')
  ).select('B.*')
  median = image_for_date.median()
  lucas_for_date = lucas.filter(
      ee.Filter.equals('survey_date', date.format('dd/MM/yy'))
  )
  sample = median.reduceRegions(
      collection=lucas_for_date,
      reducer=ee.Reducer.mean(),
      scale=10,
      tileScale=8,
  )
  return sample


# Flatten the collection.
with_samples = ee.FeatureCollection(
    dates.map(get_lucas_samples_for_date)
).flatten()

task = ee.batch.Export.table.toBigQuery(
    collection=with_samples,
    table='myproject.mydataset.mytable',
    description='lucas_s2_annotated',
)
task.start()

태스크 병렬 처리

{append: true} 옵션을 사용하면 여러 태스크가 BigQuery 테이블에 데이터를 동시에 쓸 수 있습니다. 이는 더 높은 처리량으로 데이터를 쓰기 위한 메커니즘이지만 복잡성 (작업 큐 관리, 재시도 등)이 증가합니다.

`append` 및 `overwrite` 매개변수 간의 성능 차이

BigQuery는 이전 데이터를 덮어쓰기 전에 새 데이터를 처리해야 하므로 덮어쓰기는 추가보다 느립니다. 기존 BigQuery 테이블로 내보낼 때 {overwrite: true} 매개변수를 설정하면 안전한 덮어쓰기 프로세스가 트리거됩니다.

임시 테이블: 데이터가 대상 데이터 세트 내의 새 임시 테이블로 내보내집니다.
원자적 덮어쓰기: 임시 테이블의 콘텐츠가 최종 대상 테이블에 복사되어 단일 원자적 트랜잭션에서 기존 데이터를 대체합니다.
정리: 임시 테이블이 삭제됩니다.

이렇게 하면 내보내기 중 발생한 오류로 인해 기존 데이터가 손상되지 않습니다. 작은 테이블의 경우 일반적으로 몇 분 정도 지연됩니다.

고성능 대안

매우 높은 처리량이 필요한 워크플로의 경우 GeoBeam을 사용하여 Earth Engine에서 BigQuery로 데이터를 이동하는 것이 좋습니다. 이렇게 하려면 더 많은 구성과 인프라가 필요하므로 내장된 Earth Engine 기능으로 시작하는 것이 좋습니다.

가격 책정

BigQuery로 내보내는 작업은 일괄 EECU 시간을 소비하는 일괄 프로세스입니다. Earth Engine을 상업적으로 또는 운영적으로 사용하는 경우 BigQuery로 데이터를 내보내면 작업에 사용된 EECU 시간이 청구됩니다. 나머지 Earth Engine에서 작동하는 것과 정확히 동일한 모니터링 도구를 사용하여 모든 사용량을 모니터링할 수 있습니다.

Cloud Billing 계정

BigQuery에 데이터를 쓰려면 연결된 Cloud 프로젝트에 결제 계정이 사용 설정되어 있어야 합니다. 결제 계정 구성에 대해 자세히 알아보려면 Cloud 결제 계정 문서를 참고하세요.

이그레스

모든 인그레스 및 이그레스 비용은 표준 네트워크 트래픽으로 청구됩니다.

Earth Engine은 미국에서만 호스팅되지만 BigQuery 데이터 세트는 여러 리전에서 호스팅될 수 있습니다. 관련 리전 및 데이터 양에 따라 Earth Engine에서 BigQuery로 데이터를 쓰면 상당한 네트워크 트래픽이 발생할 수 있습니다.

알려진 문제

대형 다각형의 방향

BigQuery Export 함수는 방향을 반대로 하여 (다각형을 기하학적 보완으로 변경) 반구보다 큰 다각형을 뒤집습니다. 드물지만 반구보다 큰 다각형이 로드되지 않을 수 있습니다.

필요한 경우 BigQuery 표현식 ST_Difference(ST_GeogFromText('fullglobe'), geo)를 사용하여 뒤집힌 다각형을 다시 뒤집어 BigQuery 내에서 수정할 수 있습니다.

자세한 내용은 여기를 참고하세요.

BigQuery로 내보내기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

개요

BigQuery 기본사항

데이터 세트 만들기

권한

가격 책정

구성 내보내기

구문

코드 편집기 (JavaScript)

Colab (Python)

자동 또는 수동 스키마 사양

속성 이름

유형 변환

배열

JSON 값

코드 편집기 (JavaScript)

Colab (Python)

도형 변환

코드 편집기 (JavaScript)

Colab (Python)

성능

Earth Engine 성능

BigQuery의 성능

데모: reduceRegions 사용

코드 편집기 (JavaScript)

Colab (Python)

태스크 병렬 처리

append 및 overwrite 매개변수 간의 성능 차이

고성능 대안

가격 책정

Cloud Billing 계정

이그레스

알려진 문제

대형 다각형의 방향

BigQuery로 내보내기

데모: `reduceRegions` 사용

`append` 및 `overwrite` 매개변수 간의 성능 차이