อ่านจาก 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)

คุณจะไม่ต้องเสียค่าใช้จ่ายเพิ่มเติมใน BigQuery สำหรับการโอนข้อมูลไปยัง Earth Engine การใช้งาน 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

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

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

สิ่งที่ต้องมีก่อนและสิทธิ์

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