القراءة من 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 الخاصة بالمشروع المستخدَم (راجِع مراقبة استخدام واجهة برمجة التطبيقات)، ولكن لن يتم فرض أي تكلفة مقابل قراءة بيانات 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 الرئيسية:

  • سجلّ المهام: يمكنك الوصول إلى سجلّ لمدة ستة أشهر لعمليات تنفيذ طلبات البحث الخاصة بمشروعك (يمكنك الاطّلاع على المزيد في قائمة المهام).
  • تخزين نتائج طلبات البحث مؤقتًا: يخزّن BigQuery نتائج طلبات البحث مؤقتًا تلقائيًا عند الإمكان. تسترجع طلبات البحث المتطابقة اللاحقة البيانات من ذاكرة التخزين المؤقت، ما يمنع فرض رسوم مكرّرة (يمكنك الاطّلاع على المزيد في استخدام نتائج طلبات البحث المخزّنة مؤقتًا).

للتعرّف على طلبات البحث أو كيفية استخدامها في BigQuery، يمكنك الاطّلاع على مستندات BigQuery.

الفوترة

تتم فوترة تكلفة وحدات EECU المستخدَمة أثناء معالجة الطلب إلى مقدّم الطلب كما هو الحال مع أي طريقة أخرى في Earth Engine (راجِع نظرة عامة حول وحدات EECU). بالإضافة إلى ذلك، يتم تحصيل رسوم مقابل تنفيذ طلب البحث من مقدّم الطلب وفقًا لنموذج فوترة BigQuery.

ما مِن تكاليف إضافية في BigQuery مرتبطة بنقل البيانات إلى Earth Engine. سيظهر استخدام BigQuery ذو الصلة في لوحة بيانات Google Cloud API الخاصة بالمشروع المستخدَم (راجِع مراقبة استخدام واجهة برمجة التطبيقات)، ولكن لن يتم فرض أي تكلفة مقابل قراءة بيانات BigQuery بهذه الطريقة.

للتحكّم في التكاليف المحتملة المرتبطة بـ ee.FeatureCollection.runBigQuery()، يعمل المَعلمة maxBytesBilled كإجراء وقائي. أي مهمة في BigQuery تتجاوز هذا الحد ستفشل ولن يتم تحصيل رسوم مقابلها. القيمة التلقائية لـ maxBytesBilled هي 100 غيغابايت. إذا تم حظر مكالمتك بسبب تجاوز هذا الحد، يمكنك تحديد قيمة مختلفة في النص البرمجي.

المتطلّبات الأساسية والأذونات

لاستخدام هذه الميزة، يجب أن يكون مشروع Cloud الخاص بالمتصل مزوّدًا بواجهة BigQuery API وواجهة BigQuery Storage 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 الجدولية المتوازية بشكل كبير، نحول فلاتر Earth Engine إلى لغة تفهمها BigQuery ونرسلها مع طلب قراءة الجدول. يؤدي هذا الأسلوب إلى نقل عملية معالجة الفلاتر إلى حزمة BigQuery، ولكنّه يخضع أيضًا لقيودَين:

  1. وكما هو الحال مع كل طلب بحث آخر في BigQuery (راجِع حصص BigQuery)، يقتصر حجم هذا الطلب على 10 ميغابايت. وهذا يعني أنّه لا يمكن أن تكون الفلاتر التي تم اجتيازها معقّدة للغاية. سيؤدي تجاوز الحدّ الأقصى البالغ 10 ميغابايت إلى ظهور الخطأ التالي:

    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.

    في هذه الحالات، يكون المتصل مسؤولاً عن التأكّد من أنّ الفهارس فريدة. وإلا، قد لا تعمل المجموعة بالشكل المطلوب. يجب أن يكون فهرس الميزة سلسلة غير فارغة، لذا سيتعذّر تحميل جدول BigQuery بقيمة غير سلسلة أو null لعمود system:index.

  • إذا لم يكن جدول BigQuery يحتوي على العمود system:index، سيتم إنشاؤه تلقائيًا.

    تكون الفهارس بين طلبَي قراءة ثابتة، ولكن فقط إذا كان الطلبان متطابقَين تمامًا، مع أخذ الفلاتر في الاعتبار. وبخلاف ذلك، لا يمكننا الاعتماد على الفهارس لتتوافق مع الميزات نفسها. لذلك، إذا كان من المهم أن تكون فهارس البيانات فريدة بدقة بالنسبة إلى المتصل، ننصح بإضافة العمود system:index في BigQuery يدويًا.

القيود

  • يقتصر حجم جميع الأعمدة المحدّدة من الجدول المشار إليه في طلب ee.FeatureCollection.loadBigQueryTable() على 400 غيغابايت. سيؤدي بلوغ هذا الحدّ إلى ظهور الخطأ التالي:

    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 غيغابايت على أحجام نتائج طلب البحث. على الرغم من أنّ جداول المصدر يمكن أن تكون بأي حجم، ستؤدي معالجة كميات أكبر من البيانات إلى زيادة تكاليف طلبات البحث.

  • يقتصر حجم الفلتر المترجَم على 10 ميغابايت. راجِع قسم فلترة البيانات لمعرفة التفاصيل.

  • لا يمكن استخدام 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. يمكنك الاطّلاع على مزيد من المعلومات حول الفهرسة في قسم "فهرسة البيانات".