از BigQuery بخوانید

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

بارگیری داده‌ها از 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

The ee.FeatureCollection.runBigQuery() method runs a BigQuery SQL query and returns the results as an ee.FeatureCollection object (see Run a query doc to learn more about queries).

// 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 جداگانه را آغاز می‌کند (برای اطلاعات بیشتر در مورد پرس‌وجوها به مستندات Run a query مراجعه کنید)، و به شما امکان می‌دهد از قابلیت‌های کلیدی BigQuery استفاده کنید:

• سابقه کار : به سابقه شش ماهه اجرای کوئری‌های پروژه خود دسترسی پیدا کنید (برای اطلاعات بیشتر به فهرست مشاغل مراجعه کنید).
• ذخیره سازی کوئری : BigQuery به طور خودکار نتایج کوئری را در صورت امکان ذخیره می‌کند. کوئری‌های مشابه بعدی، داده‌ها را از حافظه پنهان بازیابی می‌کنند و از هزینه‌های اضافی جلوگیری می‌کنند (برای اطلاعات بیشتر به بخش استفاده از نتایج کوئری ذخیره شده مراجعه کنید).

To learn about queries or how to use them in BigQuery see BigQuery documentation .

صورتحساب

هزینه EECU های استفاده شده در طول پردازش درخواست، مانند هر روش دیگر Earth Engine، برای تماس گیرنده صورتحساب می‌شود ( به نمای کلی EECU ها مراجعه کنید). علاوه بر این، اجرای یک پرس و جو طبق مدل صورتحساب BigQuery برای تماس گیرنده صورتحساب می‌شود .

هیچ هزینه اضافی برای BigQuery برای انتقال داده‌ها به Earth Engine وجود ندارد. میزان استفاده از BigQuery مربوطه در داشبورد Google Cloud API پروژه استفاده شده قابل مشاهده خواهد بود (به بخش نظارت بر میزان استفاده از API مراجعه کنید)، اما هیچ هزینه‌ای برای خواندن داده‌های BigQuery به این روش متحمل نخواهید شد.

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

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

برای استفاده از این ویژگی، پروژه ابری تماس‌گیرنده باید 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) فیلتر کرد. برای اینکه کاربران 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() به آن ارجاع داده می‌شود، به ۴۰۰ گیگابایت محدود شده است. رسیدن به این محدودیت منجر به خطای زیر خواهد شد:

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

• اتصال به جدول‌های BigQuery با شناسه‌های خودکار تولید شده از طریق system:index ممکن است منجر به رفتارهای غیرمنتظره‌ای شود. برای جلوگیری از این اتفاق، اضافه کردن system:index به جدول BigQuery به صورت دستی یا اتصال به جدول از طریق یک ویژگی دیگر را در نظر بگیرید. برای اطلاعات بیشتر در مورد اندیس‌گذاری، به بخش اندیس‌گذاری داده‌ها مراجعه کنید.

• متد ee.FeatureCollection.randomColumn() با شناسه‌های خودکار تولید شده توسط BigQuery کار نمی‌کند. می‌توانید با استفاده از پارامتر rowKeys در متد ee.FeatureCollection.randomColumn() یک کلید جایگزین تعیین کنید. همچنین می‌توانید ستون‌های random یا system:index به صورت دستی به جدول منبع BigQuery اضافه کنید. برای اطلاعات بیشتر در مورد اندیس‌گذاری، به بخش اندیس‌گذاری داده‌ها مراجعه کنید.