Đọc từ BigQuery

Trang này mô tả cách tích hợp các bảng BigQuery vào quy trình làm việc của Earth Engine dưới dạng các đối tượng ee.FeatureCollection, bằng cách sử dụng các phương thức ee.FeatureCollection.loadBigQueryTable() và ee.FeatureCollection.runBigQuery().

Tải dữ liệu từ BigQuery

Hàm ee.FeatureCollection.loadBigQueryTable() đọc liền mạch một bảng BigQuery vào một đối tượng ee.FeatureCollection. Thao tác này kết nối với một bảng được chỉ định, chuyển đổi tất cả các kiểu dữ liệu, áp dụng các bộ lọc và bộ chọn cần thiết, đồng thời thêm chỉ mục vào tập hợp nếu cần. Hàm này sử dụng môi trường tương tác của Earth Engine, trả về kết quả trực tiếp cho máy khách để xem hoặc sử dụng làm thành phần của một quy trình phân tích lớn hơn.

JavaScript

// 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())

Thanh toán

Chi phí của số giờ EECU được sử dụng trong quá trình xử lý yêu cầu sẽ được tính cho phương thức gọi như đối với mọi phương thức khác của Earth Engine (xem Tổng quan về EECU).

Bạn sẽ không phải trả thêm phí BigQuery khi chuyển dữ liệu sang Earth Engine. Mức sử dụng BigQuery tương ứng sẽ xuất hiện trong Google Cloud API Dashboard (Trang tổng quan về API Google Cloud) của dự án đã sử dụng (xem phần Giám sát mức sử dụng API), nhưng bạn sẽ không phải trả phí khi đọc dữ liệu BigQuery theo cách này.

Truy vấn dữ liệu từ BigQuery

Phương thức ee.FeatureCollection.runBigQuery() chạy một truy vấn SQL BigQuery và trả về kết quả dưới dạng đối tượng ee.FeatureCollection (xem Tài liệu về cách chạy truy vấn để tìm hiểu thêm về truy vấn).

JavaScript

// 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())

Truy vấn BigQuery

Mỗi lệnh gọi đến ee.FeatureCollection.runBigQuery() sẽ bắt đầu một công việc truy vấn BigQuery riêng biệt (xem thêm về truy vấn trong Tài liệu Chạy truy vấn), cho phép bạn sử dụng các chức năng chính của BigQuery:

  • Nhật ký công việc: Truy cập vào nhật ký 6 tháng về các lần thực thi truy vấn của dự án (xem thêm tại Liệt kê các công việc).
  • Lưu kết quả truy vấn vào bộ nhớ đệm: BigQuery tự động lưu kết quả truy vấn vào bộ nhớ đệm khi có thể. Các truy vấn giống hệt nhau sau đó sẽ truy xuất dữ liệu từ bộ nhớ đệm, ngăn chặn các khoản phí dư thừa (xem thêm tại phần Sử dụng kết quả truy vấn trong bộ nhớ đệm)

Để tìm hiểu về các truy vấn hoặc cách sử dụng các truy vấn trong BigQuery, hãy xem tài liệu về BigQuery.

Thanh toán

Chi phí EECU được sử dụng trong quá trình xử lý yêu cầu sẽ được tính cho người gọi như đối với mọi phương thức khác của Earth Engine (xem Tổng quan về EECU). Ngoài ra, việc chạy một truy vấn sẽ được tính phí cho phương thức gọi theo mô hình thanh toán của BigQuery.

Bạn sẽ không phải trả thêm phí BigQuery khi chuyển dữ liệu sang Earth Engine. Mức sử dụng BigQuery tương ứng sẽ xuất hiện trong Google Cloud API Dashboard (Trang tổng quan về API Google Cloud) của dự án đã sử dụng (xem phần Giám sát mức sử dụng API), nhưng bạn sẽ không phải trả phí khi đọc dữ liệu BigQuery theo cách này.

Để kiểm soát các chi phí có thể phát sinh liên quan đến ee.FeatureCollection.runBigQuery(), tham số maxBytesBilled đóng vai trò là biện pháp bảo vệ. Mọi công việc BigQuery vượt quá hạn mức này sẽ không thành công và không bị tính phí. Giá trị mặc định của maxBytesBilled là 100 GB. Nếu lệnh gọi của bạn bị chặn do vượt quá giới hạn này, bạn có thể chỉ định một giá trị khác trong tập lệnh.

Điều kiện tiên quyết và quyền

Để sử dụng tính năng này, dự án trên Google Cloud của người gọi cần bật BigQuery API và BigQuery Storage API. Làm theo hướng dẫn trên trang Bật API để bật các API phù hợp.

Ngoài các vai trò và quyền tiêu chuẩn của Earth Engine, bạn cần có quyền đọc đối với bảng BigQuery được tham chiếu, quyền tạo các phiên đọc và tác vụ trong dự án mục tiêu. Các quyền cụ thể cần có trên BigQuery là:

  • bigquery.tables.get (trên mọi bảng được truy cập)
  • bigquery.tables.getData (trên mọi bảng được truy cập)
  • bigquery.readSession.create
  • bigquery.jobs.create

Hãy tham khảo tài liệu về chế độ kiểm soát quyền truy cập vào BigQuery để biết thông tin chi tiết về cách quản lý quyền.

Tính năng lọc dữ liệu

Bạn có thể lọc mọi ee.FeatureCollection bằng phương thức .filter(Filter). Để cho phép người dùng Google Earth Engine hưởng lợi từ quá trình xử lý dữ liệu dạng bảng BigQuery có mức độ song song hoá cao, chúng tôi sẽ dịch các bộ lọc Earth Engine sang ngôn ngữ mà BigQuery có thể hiểu được và gửi các bộ lọc đó cùng với yêu cầu đọc bảng. Cách tiếp cận này thực sự chuyển quy trình xử lý bộ lọc sang ngăn xếp BigQuery, nhưng cũng phải tuân theo 2 hạn chế:

  1. Giống như mọi truy vấn khác trong BigQuery (xem hạn mức BigQuery), yêu cầu này bị giới hạn ở kích thước 10 MB. Điều này có nghĩa là các bộ lọc đã được truyền không được quá phức tạp. Nếu vượt quá giới hạn 10 MB, bạn sẽ gặp phải lỗi sau:

    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.

    Lọc theo các hình học chứa nhiều đỉnh là nguyên nhân phổ biến gây ra lỗi này. Để giải quyết vấn đề này, hãy cân nhắc sử dụng ee.Geometry.simplify() trên đối tượng có vấn đề.

  2. Một số bộ lọc Earth Engine phức tạp hơn không thể chuyển đổi thành các bộ lọc tương đương trong BigQuery. Ví dụ: BigQuery không hỗ trợ các lượt kiểm tra tính bình đẳng ARRAY. Trong những trường hợp như vậy, chúng tôi không dịch bộ lọc mà áp dụng bộ lọc đó trong Earth Engine sau khi đọc dữ liệu.

Lập chỉ mục dữ liệu

Các tập hợp Earth Engine dựa vào việc lập chỉ mục nội bộ, trong khi BigQuery không khuyến khích việc giữ các bảng được lập chỉ mục. Để hai hệ thống đó hoạt động cùng nhau, chúng ta sẽ tạo chỉ mục tập hợp theo cách sau:

  • Nếu bảng BigQuery chứa một cột có tên là system:index, chúng tôi sẽ dùng cột đó để lập chỉ mục FeatureCollection.

    Trong những trường hợp như vậy, người gọi phải đảm bảo rằng các chỉ mục là duy nhất. Nếu không, tập hợp có thể hoạt động sai cách theo một cách không mong muốn. Chỉ mục đối tượng phải là một chuỗi không trống, vì vậy, việc tải bảng BigQuery bằng một giá trị không phải là chuỗi hoặc null cho cột system:index sẽ không thành công.

  • Nếu bảng BigQuery không chứa cột system:index, thì cột này sẽ được tạo tự động.

    Các chỉ mục giữa hai yêu cầu đọc là ổn định, nhưng chỉ khi các yêu cầu hoàn toàn giống nhau, có tính đến các bộ lọc. Nếu không, chúng tôi không thể dựa vào các chỉ mục để tương ứng với cùng một đối tượng. Do đó, nếu việc lập chỉ mục dữ liệu hoàn toàn duy nhất là quan trọng đối với người gọi, thì bạn nên thêm cột system:index vào BigQuery theo cách thủ công.

Các điểm hạn chế

  • Kích thước của tất cả các cột đã chọn trong bảng được tham chiếu trong lệnh gọi ee.FeatureCollection.loadBigQueryTable() bị giới hạn ở mức 400 GB. Khi đạt đến giới hạn này, bạn sẽ gặp phải lỗi sau:

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

    Trong những trường hợp như vậy, hãy cân nhắc việc chọn các bộ chọn hạn chế hơn để chỉ đọc các cột cần thiết hoặc cân nhắc sử dụng ee.FeatureCollection.runBigQuery() để xử lý trước bảng trong BigQuery và giảm lượng dữ liệu được tìm nạp.

  • Phương thức ee.FeatureCollection.runBigQuery() áp đặt giới hạn 10 GB đối với kích thước kết quả truy vấn. Mặc dù các bảng nguồn có thể có kích thước tuỳ ý, nhưng việc xử lý khối lượng dữ liệu lớn hơn sẽ làm tăng chi phí truy vấn.

  • Kích thước bộ lọc đã dịch tối đa là 10 MB. Hãy xem phần Lọc dữ liệu để biết thông tin chi tiết.

  • Bạn không thể sử dụng ee.FeatureCollection.loadBigQueryTable() hoặc ee.FeatureCollection.runBigQuery() với các ứng dụng Earth Engine.

Chú ý

  • ee.FeatureCollection.loadBigQueryTable() không hỗ trợ các tài nguyên từ Tập dữ liệu được liên kết. Việc cố gắng tải dữ liệu từ bảng như vậy sẽ dẫn đến lỗi "không tìm thấy bảng".

    Để khắc phục, hãy cân nhắc chạy ee.FeatureCollection.runBigQuery() bằng một truy vấn chỉ định bảng được yêu cầu từ tập dữ liệu được liên kết. Ví dụ:

    JavaScript

    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')

  • Việc kết hợp trên system:index cho các bảng BigQuery có mã nhận dạng được tạo tự động có thể dẫn đến những hành vi không mong muốn. Để ngăn tình trạng này xảy ra, hãy cân nhắc việc thêm system:index vào bảng BigQuery theo cách thủ công hoặc kết hợp bảng này với một tài sản khác. Đọc thêm về việc lập chỉ mục trong phần Lập chỉ mục dữ liệu.

  • Phương thức ee.FeatureCollection.randomColumn() không hoạt động với các mã nhận dạng do BigQuery tự động tạo. Hãy cân nhắc việc chỉ định một khoá thay thế bằng cách sử dụng tham số rowKeys trong phương thức ee.FeatureCollection.randomColumn(). Bạn cũng có thể thêm cột random hoặc system:index vào bảng nguồn BigQuery theo cách thủ công. Đọc thêm về việc lập chỉ mục trong phần Lập chỉ mục dữ liệu.