BigQuery에서 읽어오기

이 페이지에서는 ee.FeatureCollection.loadBigQueryTable() 및 ee.FeatureCollection.runBigQuery() 메서드를 사용하여 BigQuery 테이블을 Earth Engine 워크플로에 ee.FeatureCollection 객체로 통합하는 방법을 설명합니다.

BigQuery에서 데이터 로드

ee.FeatureCollection.loadBigQueryTable() 함수는 BigQuery 테이블을 ee.FeatureCollection 객체로 원활하게 읽습니다. 지정된 테이블에 연결하고 모든 데이터 유형을 변환하며 필요한 필터와 선택기를 적용하고 필요한 경우 컬렉션에 색인을 추가합니다. 이 함수는 Earth Engine의 대화형 환경을 사용하여 결과를 클라이언트로 직접 반환하여 더 큰 분석의 구성요소로 보거나 사용할 수 있도록 합니다.

자바스크립트

// Load the BigQuery table with a specified geometry column.
var features = ee.FeatureCollection.loadBigQueryTable({
  table: 'my_project.my_dataset.my_table',
  geometryColumn: 'geo'
});

// Display features on the map.
Map.addLayer(features);

Python

# Load the BigQuery table with a specified geometry column.
features = ee.FeatureCollection.loadBigQueryTable(
    table='my_project.my_dataset.my_table',
    geometryColumn='geo')

# Display the first feature.
display(features.first().getInfo())

결제

요청 처리 중에 사용된 EECU 시간의 비용은 다른 Earth Engine 메서드와 마찬가지로 호출자에게 청구됩니다 (EECU 개요 참고).

데이터를 Earth Engine으로 전송하는 것과 관련하여 추가 BigQuery 비용은 발생하지 않습니다. 사용된 프로젝트의 Google Cloud API 대시보드에 상응하는 BigQuery 사용량이 표시되지만(API 사용량 모니터링 참고) 이 방법으로 BigQuery 데이터를 읽는 데는 비용이 발생하지 않습니다.

BigQuery에서 데이터 쿼리

ee.FeatureCollection.runBigQuery() 메서드는 BigQuery SQL 쿼리를 실행하고 결과를 ee.FeatureCollection 객체로 반환합니다 (쿼리에 관한 자세한 내용은 쿼리 실행 문서 참고).

자바스크립트

// Construct a BigQuery query.
var query = 'SELECT * FROM my_project.my_dataset.my_table WHERE column > 1000';

// Run the query and return the results as a FeatureCollection.
var features = ee.FeatureCollection.runBigQuery(query);

// Print the first feature.
print(features.first());

Python

# Construct a BigQuery query.
query = 'SELECT * FROM my_project.my_dataset.my_table WHERE column > 1000'

# Run the query and retrieve the results as a FeatureCollection.
features = ee.FeatureCollection.runBigQuery(query)

# Print the first feature.
print(features.first().getInfo())

BigQuery 쿼리

ee.FeatureCollection.runBigQuery()를 호출할 때마다 별도의 BigQuery 쿼리 작업이 시작됩니다 (쿼리 실행 문서에서 쿼리에 관해 자세히 알아보기). 이를 통해 다음과 같은 주요 BigQuery 기능을 사용할 수 있습니다.

  • 작업 기록: 프로젝트의 쿼리 실행에 관한 6개월간의 기록에 액세스합니다 (작업 목록 참고).
  • 쿼리 캐싱: BigQuery는 가능하면 쿼리 결과를 자동으로 캐시합니다. 후속 동일 쿼리는 캐시에서 데이터를 가져와 중복 청구를 방지합니다 (캐시 처리된 쿼리 결과 사용 참고).

쿼리 또는 BigQuery에서 쿼리를 사용하는 방법에 대한 자세한 내용은 BigQuery 문서를 참고하세요.

결제

요청 처리 중에 사용된 EECU 비용은 다른 Earth Engine 메서드와 마찬가지로 호출자에게 청구됩니다 (EECU 개요 참고). 또한 BigQuery 결제 모델에 따라 쿼리 실행에 대한 요금이 호출자에게 청구됩니다.

데이터를 Earth Engine으로 전송하는 것과 관련하여 추가 BigQuery 비용은 발생하지 않습니다. 사용된 프로젝트의 Google Cloud API 대시보드에 상응하는 BigQuery 사용량이 표시되지만(API 사용량 모니터링 참고) 이 방법으로 BigQuery 데이터를 읽는 데는 비용이 발생하지 않습니다.

ee.FeatureCollection.runBigQuery()와 관련된 잠재적 비용을 제어하기 위해 maxBytesBilled 매개변수가 보호 조치 역할을 합니다. 이 한도를 초과하는 BigQuery 작업은 실패하고 요금이 청구되지 않습니다. maxBytesBilled의 기본값은 100GB입니다. 이 한도를 초과하여 호출이 차단되면 스크립트에서 다른 값을 지정할 수 있습니다.

기본 요건 및 권한

이 기능을 사용하려면 호출자의 Cloud 프로젝트에 BigQuery API와 BigQuery Storage API가 사용 설정되어 있어야 합니다. API 사용 설정 페이지의 안내에 따라 적절한 API를 사용 설정합니다.

표준 Earth Engine 역할 및 권한 외에도 참조된 BigQuery 테이블에 대한 읽기 액세스 권한과 대상 프로젝트에서 읽기 세션 및 작업을 만들 권한이 있어야 합니다. 필요한 구체적인 BigQuery 권한은 다음과 같습니다.

  • bigquery.tables.get (액세스된 테이블)
  • bigquery.tables.getData (액세스된 테이블)
  • bigquery.readSession.create
  • bigquery.jobs.create

권한 관리에 관한 자세한 내용은 BigQuery 액세스 제어 문서를 참고하세요.

데이터 필터링

모든 ee.FeatureCollection는 .filter(Filter) 메서드를 사용하여 필터링할 수 있습니다. Google Earth Engine 사용자가 고도로 병렬화된 BigQuery 테이블 형식 데이터 처리의 이점을 누릴 수 있도록 Google에서는 Earth Engine 필터를 BigQuery에서 이해할 수 있는 언어로 변환하고 읽기 테이블 요청과 함께 전송합니다. 이 접근 방식은 실제로 필터 처리를 BigQuery 스택으로 이동하지만 다음과 같은 두 가지 제한사항이 있습니다.

  1. BigQuery의 다른 모든 쿼리와 마찬가지로 (BigQuery 할당량 참고) 이 요청은 크기가 10MB로 제한됩니다. 즉, 전달된 필터는 지나치게 복잡해서는 안 됩니다. 10MB 한도를 초과하면 다음과 같은 오류가 발생합니다.

    Filter sent to BigQuery is too long. This error may be caused by too complicated geometry in geometry filters. Consider simplifying the filter and used values.

    정점이 많은 도형으로 필터링하면 이 오류가 발생하는 경우가 많습니다. 이 문제를 해결하려면 문제가 있는 객체에 ee.Geometry.simplify()를 사용하는 것이 좋습니다.

  2. 더 복잡한 Earth Engine 필터의 경우 BigQuery에 상응하는 필터로 변환할 수 없습니다. 예를 들어 BigQuery는 ARRAY 등식 검사를 지원하지 않습니다. 이 경우 필터를 변환하지 않고 대신 데이터를 읽은 후에 Earth Engine에 적용합니다.

데이터 색인 생성

Earth Engine 컬렉션은 내부 색인을 사용하는 반면 BigQuery는 테이블의 색인을 유지하는 것을 권장하지 않습니다. 이러한 두 시스템이 함께 작동하도록 하려면 다음과 같이 수집 색인을 만듭니다.

  • BigQuery 테이블에 system:index라는 열이 포함된 경우 FeatureCollection 색인을 생성하는 데 사용됩니다.

    이 경우 호출자가 색인이 고유한지 확인해야 합니다. 그러지 않으면 컬렉션이 예기치 않게 잘못 작동할 수 있습니다. 지형지물 색인은 비어 있지 않은 문자열이어야 하므로 system:index 열에 문자열이 아닌 값이나 null 값이 있는 BigQuery 테이블을 로드하면 실패합니다.

  • BigQuery 테이블에 system:index 열이 없으면 열이 자동으로 생성됩니다.

    두 읽기 요청 사이의 색인은 필터를 고려하여 요청이 정확히 동일한 경우에만 안정적입니다. 그렇지 않으면 색인을 사용하여 동일한 지형지물에 대응할 수 없습니다. 따라서 호출자에게 정확하게 고유한 데이터 색인이 중요한 경우 BigQuery에 system:index 열을 수동으로 추가하는 것이 좋습니다.

제한사항

  • ee.FeatureCollection.loadBigQueryTable() 호출에서 참조된 테이블의 선택된 모든 열의 크기는 400GB로 제한됩니다. 이 한도를 초과하면 다음 오류가 발생합니다.

    Failed to read table from BigQuery: Requested data size is too large to read. Consider using selectors to specify only required columns.

    이 경우 더 제한적인 선택기를 선택하여 필요한 열을 읽기 전용으로 설정하거나 ee.FeatureCollection.runBigQuery()를 사용하여 BigQuery에서 테이블을 사전 처리하고 가져온 데이터의 양을 줄이는 것이 좋습니다.

  • ee.FeatureCollection.runBigQuery() 메서드는 쿼리 결과 크기에 10GB 제한을 적용합니다. 소스 테이블의 크기는 임의로 지정할 수 있지만, 대용량 데이터를 처리하면 쿼리 비용이 증가합니다.

  • 번역된 필터 크기는 10MB로 제한됩니다. 자세한 내용은 데이터 필터링 섹션을 참고하세요.

  • Earth Engine 앱에서는 ee.FeatureCollection.loadBigQueryTable() 또는 ee.FeatureCollection.runBigQuery()를 사용할 수 없습니다.

주의사항

  • ee.FeatureCollection.loadBigQueryTable()는 연결된 데이터 세트의 리소스를 지원하지 않습니다. 이러한 테이블에서 데이터를 로드하려고 하면 '테이블을 찾을 수 없음' 오류가 발생합니다.

    해결 방법으로 연결된 데이터 세트에서 요청된 테이블을 지정하는 쿼리와 함께 ee.FeatureCollection.runBigQuery()를 실행해 보세요. 예를 들면 다음과 같습니다.

    자바스크립트

    var features = ee.FeatureCollection.runBigQuery({
  query: 'SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn: 'geo'
});

    Python

    features = ee.FeatureCollection.runBigQuery(
  query='SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn='geo')

  • 자동 생성된 ID가 있는 BigQuery 테이블의 system:index에서 조인하면 예기치 않은 동작이 발생할 수 있습니다. 이를 방지하려면 BigQuery 테이블에 system:index를 수동으로 추가하거나 다른 속성에서 테이블을 조인하는 것이 좋습니다. 데이터 색인 생성 섹션에서 색인 생성에 대해 자세히 알아보세요.

  • ee.FeatureCollection.randomColumn() 메서드는 BigQuery 자동 생성 ID와 호환되지 않습니다. ee.FeatureCollection.randomColumn() 메서드에서 rowKeys 매개변수를 사용하여 대체 키를 지정하는 것이 좋습니다. BigQuery 소스 테이블에 random 또는 system:index 열을 수동으로 추가할 수도 있습니다. 데이터 색인 생성 섹션에서 색인 생성에 대해 자세히 알아보세요.