อ่านจาก BigQuery

หน้านี้อธิบายวิธีผสานรวมตาราง BigQuery เข้ากับเวิร์กโฟลว์ของ Earth Engine เป็นออบเจ็กต์ ee.FeatureCollection โดยใช้เมธอด ee.FeatureCollection.loadBigQueryTable() และ ee.FeatureCollection.runBigQuery()

โหลดข้อมูลจาก BigQuery

ฟังก์ชัน ee.FeatureCollection.loadBigQueryTable() จะอ่านตาราง BigQuery ลงในออบเจ็กต์ ee.FeatureCollection ได้อย่างราบรื่น โดยจะเชื่อมต่อกับตารางที่ระบุ แปลงประเภทข้อมูลทั้งหมด ใช้ตัวกรองและตัวเลือกที่จำเป็น และเพิ่มการจัดทำดัชนีลงในคอลเล็กชันหากจำเป็น ฟังก์ชันนี้ใช้สภาพแวดล้อมแบบอินเทอร์แอกทีฟ ของ Earth Engine โดยแสดงผลลัพธ์โดยตรงต่อไคลเอ็นต์เพื่อให้ดูหรือใช้เป็นส่วนประกอบของ การวิเคราะห์ที่ใหญ่ขึ้น

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

การเรียกเก็บเงิน

ระบบจะเรียกเก็บเงินค่าชั่วโมง EECU ที่ใช้ในระหว่างการประมวลผลคำขอจากผู้เรียกใช้เหมือนกับวิธีอื่นๆ ของ Earth Engine (ดูภาพรวม EECU)

การโอนข้อมูลไปยัง Earth Engine จะไม่มีค่าใช้จ่าย BigQuery เพิ่มเติม การใช้งาน BigQuery ที่เกี่ยวข้องจะปรากฏใน แดชบอร์ด Google Cloud API ของโปรเจ็กต์ที่ใช้ (ดูการตรวจสอบการใช้งาน API) แต่ จะไม่มีค่าใช้จ่ายสำหรับการอ่านข้อมูล BigQuery ด้วยวิธีนี้

ค้นหาข้อมูลจาก BigQuery

เมธอด ee.FeatureCollection.runBigQuery() จะเรียกใช้การค้นหา SQL ของ BigQuery และแสดงผลลัพธ์เป็นออบเจ็กต์ ee.FeatureCollection (ดูข้อมูลเพิ่มเติมเกี่ยวกับการค้นหาได้ที่เอกสารการเรียกใช้การค้นหา )

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

การค้นหา BigQuery

การเรียกใช้ ee.FeatureCollection.runBigQuery() แต่ละครั้ง จะเริ่มต้นงานการค้นหา BigQuery แยกต่างหาก (ดูข้อมูลเพิ่มเติมเกี่ยวกับการค้นหาในเอกสารประกอบการเรียกใช้การค้นหา) ซึ่งช่วยให้คุณใช้ความสามารถหลักของ BigQuery ได้ดังนี้

  • ประวัติงาน: เข้าถึงประวัติการเรียกใช้คิวรีของโปรเจ็กต์ในช่วง 6 เดือนที่ผ่านมา (ดูเพิ่มเติมได้ที่รายการ งาน)
  • การแคชการค้นหา: BigQuery จะแคชผลลัพธ์การค้นหาโดยอัตโนมัติเมื่อเป็นไปได้ การค้นหาที่เหมือนกันในครั้งต่อๆ ไปจะดึงข้อมูลจากแคช เพื่อป้องกันการเรียกเก็บเงินซ้ำ (ดูข้อมูลเพิ่มเติมได้ที่การใช้ผลการค้นหาที่แคชไว้)

ดูข้อมูลเกี่ยวกับการค้นหาหรือวิธีใช้การค้นหาใน BigQuery ได้ที่เอกสารประกอบของ BigQuery

การเรียกเก็บเงิน

ระบบจะเรียกเก็บเงินค่า EECU ที่ใช้ในระหว่างการประมวลผลคำขอจากผู้เรียกเหมือนกับวิธีอื่นๆ ของ Earth Engine (ดูภาพรวม EECU) นอกจากนี้ ระบบจะเรียกเก็บเงินสำหรับการเรียกใช้การค้นหาจากผู้เรียกตามรูปแบบการเรียกเก็บเงินของ BigQuery

การโอนข้อมูลไปยัง Earth Engine จะไม่มีค่าใช้จ่าย BigQuery เพิ่มเติม การใช้งาน BigQuery ที่เกี่ยวข้องจะปรากฏใน แดชบอร์ด Google Cloud API ของโปรเจ็กต์ที่ใช้ (ดูการตรวจสอบการใช้งาน API) แต่ จะไม่มีค่าใช้จ่ายสำหรับการอ่านข้อมูล BigQuery ด้วยวิธีนี้

พารามิเตอร์ maxBytesBilled จะทำหน้าที่เป็นตัวป้องกันเพื่อควบคุมค่าใช้จ่ายที่อาจเกิดขึ้นซึ่งเชื่อมโยงกับ ee.FeatureCollection.runBigQuery() งาน BigQuery ที่เกินขีดจำกัดนี้จะล้มเหลวและระบบจะไม่เรียกเก็บเงิน ค่าเริ่มต้นของ maxBytesBilled คือ 100 GB หากการเรียกของคุณถูกบล็อกเนื่องจากเกินขีดจำกัดนี้ คุณ สามารถระบุค่าอื่นในสคริปต์ได้

ข้อกำหนดเบื้องต้นและสิทธิ์

หากต้องการใช้ฟีเจอร์นี้ โปรเจ็กต์ 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) เราจะแปลตัวกรอง Earth Engine เป็นภาษาที่ BigQuery เข้าใจได้และส่งพร้อมกับคำขออ่านตาราง เพื่อให้ผู้ใช้ Google Earth Engine ได้รับประโยชน์จากการประมวลผลข้อมูลแบบตารางของ BigQuery ที่มีการประมวลผลแบบคู่ขนานสูง แม้ว่าวิธีนี้จะย้ายการประมวลผลตัวกรองไปยังสแต็ก BigQuery แต่ก็มีข้อจำกัด 2 ประการดังนี้

  1. เช่นเดียวกับการค้นหาอื่นๆ ใน BigQuery (ดูโควต้า BigQuery) คำขอนี้ มีขนาดไม่เกิน 10 MB ซึ่งหมายความว่าตัวกรองที่ผ่านจะต้องไม่ซับซ้อนจนเกินไป หากมีขนาดเกินขีดจำกัด 10 MB จะเกิดข้อผิดพลาดต่อไปนี้

    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 ไม่แนะนำ ให้จัดทำดัชนีตาราง เราสร้างดัชนีคอลเล็กชันด้วยวิธีต่อไปนี้เพื่อให้ระบบทั้ง 2 ทำงานร่วมกันได้

  • หากตาราง BigQuery มีคอลัมน์ชื่อ system:index เราจะใช้คอลัมน์นี้เพื่อ จัดทำดัชนี FeatureCollection

    ในกรณีดังกล่าว ผู้โทรจะต้องตรวจสอบว่าดัชนีไม่ซ้ำกัน ไม่เช่นนั้น การรวบรวมอาจทำงานผิดปกติในลักษณะที่ไม่คาดคิด ดัชนีฟีเจอร์ต้องเป็น สตริงที่ไม่ว่างเปล่า ดังนั้นการโหลดตาราง BigQuery ที่มีค่าที่ไม่ใช่สตริงหรือnull ค่าสำหรับคอลัมน์ system:index จะล้มเหลว

  • หากตาราง BigQuery ไม่มีคอลัมน์ system:index ระบบจะสร้างคอลัมน์นี้โดยอัตโนมัติ

    ดัชนีระหว่างคำขออ่าน 2 รายการจะคงที่ แต่จะคงที่ก็ต่อเมื่อคำขอ เหมือนกันทุกประการ โดยคำนึงถึงตัวกรองด้วย มิฉะนั้นเราจะใช้ดัชนีเพื่ออ้างอิงฟีเจอร์เดียวกันไม่ได้ ดังนั้นหากการจัดทำดัชนีข้อมูลที่ไม่ซ้ำกันอย่างแม่นยำมีความสำคัญต่อผู้โทร เราขอแนะนำให้เพิ่มคอลัมน์ system:index ใน BigQuery ด้วยตนเอง

ข้อจำกัด

  • ขนาดของคอลัมน์ที่เลือกทั้งหมดของตารางที่อ้างอิงใน ee.FeatureCollection.loadBigQueryTable() การเรียกใช้มีขนาดไม่เกิน 400 GB การเกินขีดจำกัดนี้จะส่งผลให้เกิดข้อผิดพลาดต่อไปนี้

    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() จะกำหนดขีดจำกัดขนาดผลลัพธ์การค้นหาไว้ที่ 10 GB แม้ว่าตารางแหล่งข้อมูล จะมีขนาดเท่าใดก็ได้ แต่การประมวลผลข้อมูลปริมาณมากจะเพิ่มค่าใช้จ่ายในการค้นหา

  • ฟิลเตอร์ที่แปลแล้วต้องมีขนาดไม่เกิน 10 MB ดูรายละเอียดได้ที่ส่วนการกรองข้อมูล

  • การใช้ ee.FeatureCollection.loadBigQueryTable() หรือ ee.FeatureCollection.runBigQuery() จะใช้กับแอป Earth Engine ไม่ได้

คำเตือน

  • ee.FeatureCollection.loadBigQueryTable() ไม่รองรับทรัพยากรจากชุดข้อมูลที่ลิงก์ การพยายามโหลดข้อมูลจากตารางดังกล่าวจะทำให้เกิดข้อผิดพลาด "ไม่พบตาราง"

    วิธีแก้ปัญหาเฉพาะหน้าคือลองเรียกใช้ ee.FeatureCollection.runBigQuery() ด้วยการค้นหาที่ระบุตารางที่ขอจากชุดข้อมูลที่ลิงก์ เช่น

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

  • การรวมใน system:index สำหรับตาราง BigQuery ที่มีรหัสที่สร้างขึ้นโดยอัตโนมัติอาจ ทำให้เกิดลักษณะการทำงานที่ไม่คาดคิด หากต้องการป้องกันไม่ให้เกิดเหตุการณ์นี้ ให้พิจารณา เพิ่ม system:index ลงในตาราง BigQuery ด้วยตนเอง หรือรวมตารางในพร็อพเพอร์ตี้อื่น อ่านเพิ่มเติมเกี่ยวกับการจัดทำดัชนีในส่วนการจัดทำดัชนีข้อมูล

  • เมธอด ee.FeatureCollection.randomColumn() ใช้กับรหัสที่ BigQuery สร้างขึ้นโดยอัตโนมัติไม่ได้ ลองระบุคีย์อื่นโดยใช้พารามิเตอร์ rowKeys ในเมธอด ee.FeatureCollection.randomColumn() นอกจากนี้ คุณยังเพิ่มคอลัมน์ random หรือ system:index ลงในตารางแหล่งข้อมูล BigQuery ด้วยตนเองได้ด้วย อ่านเพิ่มเติมเกี่ยวกับการจัดทำดัชนีในส่วนการจัดทำดัชนีข้อมูล