از BigQuery بخوانید

این صفحه نحوه ادغام جداول BigQuery را با استفاده از روش‌های ee.FeatureCollection.loadBigQueryTable() و ee.FeatureCollection.runBigQuery() در گردش‌های کاری Earth Engine به عنوان اشیاء ee.FeatureCollection شرح می‌دهد.

بارگیری داده ها از BigQuery

تابع ee.FeatureCollection.loadBigQueryTable() یک جدول BigQuery را در یک شیء ee.FeatureCollection می خواند. به جدول مشخصی متصل می شود، تمام انواع داده ها را تبدیل می کند، فیلترها و انتخابگرهای لازم را اعمال می کند و در صورت لزوم فهرست بندی را به مجموعه اضافه می کند. این تابع از محیط تعاملی Earth Engine استفاده می‌کند و نتایج را مستقیماً به مشتری برمی‌گرداند تا به عنوان جزئی از یک تجزیه و تحلیل بزرگ‌تر مشاهده یا استفاده شود.

جاوا اسکریپت 

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

پایتون 

# 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() یک پرس و جو BigQuery SQL را اجرا می کند و نتایج را به عنوان یک شی ee.FeatureCollection برمی گرداند (برای اطلاعات بیشتر در مورد کوئری ها به اجرای یک query doc مراجعه کنید).

جاوا اسکریپت 

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

پایتون 

# 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 پروژه مورد استفاده قابل مشاهده خواهد بود ( به نظارت بر استفاده از API مراجعه کنید)، اما هیچ هزینه ای برای خواندن داده های BigQuery از این طریق متحمل نمی شود.

برای کنترل هزینه‌های بالقوه مرتبط با ee.FeatureCollection.runBigQuery() ، پارامتر maxBytesBilled به عنوان محافظ عمل می‌کند. هر کار BigQuery که بیش از این حد باشد با شکست مواجه می شود و صورتحساب دریافت نمی شود. مقدار پیش فرض maxBytesBilled 100 گیگابایت است. اگر تماس شما با فراتر رفتن از این حد مسدود شد، می توانید مقدار دیگری را در اسکریپت خود تعیین کنید.

پیش نیازها و مجوزها

برای استفاده از این ویژگی، پروژه Cloud تماس‌گیرنده باید دارای BigQuery API و BigQuery Storage API فعال باشد. دستورالعمل های صفحه Enable API را دنبال کنید تا 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() را با یک پرس و جو که جدول درخواستی را از مجموعه داده پیوندی مشخص می کند، در نظر بگیرید. به عنوان مثال:

    جاوا اسکریپت 

    var features = ee.FeatureCollection.runBigQuery({
  query: 'SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn: 'geo'
});

    پایتون 

    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 اضافه کنید. اطلاعات بیشتر در مورد نمایه سازی را در بخش نمایه سازی داده ها بخوانید.