Announcement: All noncommercial projects registered to use Earth Engine beforeApril 15, 2025 mustverify noncommercial eligibility to maintain access. If you have not verified by September 26, 2025, your access may be on hold.

ee.FeatureCollection.runBigQuery

  • Theee.FeatureCollection.runBigQuery function executes a BigQuery query and returns the results as a FeatureCollection.

  • Arguments for the function include the SQLquery string, an optionalgeometryColumn to specify the geometry column, and an optionalmaxBytesBilled to set a limit on billed bytes.

  • The examples demonstrate how to userunBigQuery in both JavaScript and Python to fetch data from BigQuery and visualize or analyze it.

 Runs a BigQuery query, fetches the results and presents the them as a FeatureCollection.

UsageReturns
ee.FeatureCollection.runBigQuery(query,geometryColumn,maxBytesBilled)FeatureCollection
ArgumentTypeDetails
queryStringGoogleSQL query to perform on the BigQuery resources.
geometryColumnString, default: nullThe name of the column to use as the main feature geometry. If not specified, the first geometry column will be used.
maxBytesBilledLong, default: 100000000000Maximum number of bytes billed while processing the query. Any BigQuery job that exceeds this limit will fail and won't be billed.

Examples

Code Editor (JavaScript)

// Get places from Overture Maps Dataset in BigQuery public data.Map.setCenter(-3.69,40.41,12)varmapGeometry=ee.Geometry(Map.getBounds(true)).toGeoJSONString();varsql="SELECT geometry, names.primary as name, categories.primary as category "+" FROM bigquery-public-data.overture_maps.place "+" WHERE ST_INTERSECTS(geometry, ST_GEOGFROMGEOJSON('"+mapGeometry+"'))";varfeatures=ee.FeatureCollection.runBigQuery({query:sql,geometryColumn:'geometry'});// Display all relevant features on the map.Map.addLayer(features,{'color':'black'},'Places from Overture Maps Dataset');// Create a histogram of the categories and print it.varpropertyOfInterest='category';varhistogram=features.filter(ee.Filter.notNull([propertyOfInterest])).aggregate_histogram(propertyOfInterest);print(histogram);// Create a frequency chart for the histogram.varcategories=histogram.keys().map(function(k){returnee.Feature(null,{key:k,value:histogram.get(k)});});varsortedCategories=ee.FeatureCollection(categories).sort('value',false);print(ui.Chart.feature.byFeature(sortedCategories).setChartType('Table'));

Python setup

See the Python Environment page for information on the Python API and usinggeemap for interactive development.

importeeimportgeemap.coreasgeemap

Colab (Python)

importjsonimportpandasaspd# Get places from Overture Maps Dataset in BigQuery public data.location=ee.Geometry.Point(-3.69,40.41)map_geometry=json.dumps(location.buffer(5e3).getInfo())sql=f"""SELECT geometry, names.primary as name, categories.primary as categoryFROM bigquery-public-data.overture_maps.placeWHERE ST_INTERSECTS(geometry, ST_GEOGFROMGEOJSON('{map_geometry}'))"""features=ee.FeatureCollection.runBigQuery(query=sql,geometryColumn="geometry")# Display all relevant features on the map.m=geemap.Map()m.center_object(location,13)m.add_layer(features,{'color':'black'},'Places from Overture Maps Dataset')display(m)# Create a histogram of the place categories.property_of_interest='category'histogram=(features.filter(ee.Filter.notNull([property_of_interest])).aggregate_histogram(property_of_interest)).getInfo()# Display the histogram as a pandas DataFrame.df=pd.DataFrame(list(histogram.items()),columns=['category','frequency'])df=df.sort_values(by=['frequency'],ascending=False,ignore_index=True)display(df)

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-06-23 UTC.