Work with raster data using Earth Engine in BigQuery

This document explains how to combine raster and vector data by using the ST_REGIONSTATS function, which uses Google Earth Engine to get access to image and raster data in BigQuery.

Overview

A raster is a two-dimensional grid of pixels, each of which is assigned one or more values called bands. For example, each pixel could correspond to one particular square kilometer on the earth's surface and have bands for average temperature and average rainfall. Raster data includes satellite imagery and other continuous, grid-based data such as weather forecasts and land cover. Many common image formats, such as PNG or JPEG files, are formatted as raster data.

Raster data is often contrasted with vector data, in which the data is described by lines or curves rather than a fixed rectangular grid. For example, you can use the GEOGRAPHY data type in BigQuery to describe the boundaries of countries, cities, or other regions.

Geospatial raster and vector data is often combined using a zonal statistics operation, which computes an aggregate of all raster values within a given vector region. For example, you might want to compute the following:

• Average air quality in a collection of cities.
• Solar potential for a collection of building polygons.
• Fire risk summarized along power line corridors in forested areas.

BigQuery excels in processing vector data, and Google Earth Engine excels in processing raster data. You can use the ST_REGIONSTATS geography function to combine raster data using Earth Engine with your vector data stored in BigQuery.

Before you begin

1. To use the ST_REGIONSTATS function in your queries, enable the Earth Engine API.

   Enable the API

2. Optional: To subscribe to and use data published to BigQuery sharing (formerly Analytics Hub) by using the ST_REGIONSTATS function, enable the Analytics Hub API.

   Enable the API

Required permissions

To get the permissions that you need to call the ST_REGIONSTATS function, ask your administrator to grant you the following IAM roles on your project:

• Earth Engine Resource Viewer (roles/earthengine.viewer)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• Subscribe to datasets in BigQuery sharing: BigQuery Data Editor (roles/bigquery.dataEditor)

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to call the ST_REGIONSTATS function. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to call the ST_REGIONSTATS function:

• earthengine.computations.create
• serviceusage.services.use
• bigquery.datasets.create

You might also be able to get these permissions with custom roles or other predefined roles.

Find raster data

The raster_id parameter in the ST_REGIONSTATS function is a string that specifies the source of your raster data. The following sections explain how to find and format the raster ID.

BigQuery image tables

You can use BigQuery sharing (formerly Analytics Hub) to discover and access raster datasets in BigQuery. To use BigQuery sharing, you need to enable the Analytics Hub API and ensure that you have required permissions to view and subscribe to listings and data exchanges.

Google Earth Engine publishes publicly available datasets that contain raster data in the US and EU multi-regions. To subscribe to an Earth Engine dataset with raster data, follow these steps:

1. Go to the Sharing (Analytics Hub) page.

   Go to Sharing (Analytics Hub)

2. Click search Search listings.

3. In the Search for listings field, enter "Google Earth Engine".

4. Click a dataset that you want to subscribe to.

5. Click Subscribe.

6. Optional: Update the Project or Linked dataset name fields.

7. Click Save. The linked dataset is added to your project.

The dataset contains an image table that stores metadata for a collection of raster images following the