القراءة من 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())

الفوترة

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

ما مِن تكاليف إضافية في 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.

الفوترة

يتم تحصيل تكلفة وحدات معالجة الطاقة الإلكترونية المستخدَمة أثناء معالجة الطلب من المتصل، تمامًا كما هو الحال مع أي طريقة أخرى في Earth Engine (راجِع نظرة عامة على وحدات معالجة الطاقة الإلكترونية). بالإضافة إلى ذلك، تتم الفوترة للمتصل مقابل تنفيذ طلب بحث وفقًا لموديل فوترة 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، يتم إنشاؤه تلقائيًا.

    تكون الفهارس بين طلبَي القراءة ثابتة، ولكن فقط إذا كانت الطلبات متطابقة تمامًا، مع أخذ الفلاتر في الاعتبار. وبخلاف ذلك، لا يمكننا الاعتماد على الفهارس لمطابقة العناصر نفسها. لذلك، إذا كانت فهرسة data الفريدة بدقة مهمة للمتصل، ننصحك بإضافة عمود 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. يمكنك الاطّلاع على مزيد من المعلومات عن الفهرسة في قسم "فهرسة البيانات".