Stay organized with collectionsSave and categorize content based on your preferences.
Saving joins are one way of representing one-to-many relationships in Earth Engine.
Unlike aninner join, a saving join stores matches from thesecondarycollection as a named property of the features in theprimarycollection. To save all such matches, use anee.Join.saveAll(). If there is a one-to-many relationship, asaveAll()join stores all matching features as anee.List. Unmatched elements in theprimarycollection are
dropped. For example, suppose there is a need to get all MODIS imagery acquired
within two days of each Landsat image in a collection. This example uses asaveAll()join for that purpose:
In this example, note that thesecondaryMODIS collection is pre-filtered to be
chronologically similar to theprimaryLandsat collection for efficiency. To
compare the Landsat acquisition time to the MODIS composite time, which has a daily range,
the filter compares the endpoints of the image timestamps. The join is defined with the
name of the property used to store the list of matches for each Landsat image
(‘terra’) and optional parameter to sort the list of matches by thesystem:time_startproperty
Inspection of the result indicates that images within the primary collection have the
addedterraproperty which stores a list of the matching MODIS images.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-12-27 UTC."],[[["\u003cp\u003eSaving joins represent one-to-many relationships in Earth Engine by storing matches from a secondary collection as a property in the primary collection.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eee.Join.saveAll()\u003c/code\u003e stores all matching features from the secondary collection as a list in a new property of the primary collection's features, dropping unmatched primary features.\u003c/p\u003e\n"],["\u003cp\u003eThis approach is useful for scenarios like associating all MODIS images within a specific time window to each Landsat image in a collection.\u003c/p\u003e\n"],["\u003cp\u003eThe example code demonstrates filtering and joining Landsat and MODIS collections based on their timestamps, storing the matching MODIS images in a 'terra' property on each Landsat image.\u003c/p\u003e\n"]]],["Saving joins represent one-to-many relationships by storing matches from a secondary collection as a property within the primary collection's features. `ee.Join.saveAll()` stores all matching features as an `ee.List`. The example filters Landsat and MODIS imagery collections, defining a two-day time difference as the matching condition using a time filter. A `saveAll()` join, named `'terra'`, is applied, sorting matches by `system:time_start`. The result has the added property `terra` with a list of matching MODIS images. Unmatched primary collection elements are dropped.\n"],null,["# Save-All Joins\n\nSaving joins are one way of representing one-to-many relationships in Earth Engine.\nUnlike an [inner join](/earth-engine/guides/joins_inner), a saving join stores matches from the\n`secondary` collection as a named property of the features in the\n`primary` collection. To save all such matches, use an\n`ee.Join.saveAll()`. If there is a one-to-many relationship, a\n`saveAll()` join stores all matching features as an\n`ee.List`. Unmatched elements in the `primary` collection are\ndropped. For example, suppose there is a need to get all MODIS imagery acquired\nwithin two days of each Landsat image in a collection. This example uses a\n`saveAll()` join for that purpose:\n\n### Code Editor (JavaScript)\n\n```javascript\n// Load a primary collection: Landsat imagery.\nvar primary = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')\n .filterDate('2014-04-01', '2014-06-01')\n .filterBounds(ee.Geometry.Point(-122.092, 37.42));\n\n// Load a secondary collection: MODIS imagery.\nvar modSecondary = ee.ImageCollection('MODIS/006/MOD09GA')\n .filterDate('2014-03-01', '2014-07-01');\n\n// Define an allowable time difference: two days in milliseconds.\nvar twoDaysMillis = 2 * 24 * 60 * 60 * 1000;\n\n// Create a time filter to define a match as overlapping timestamps.\nvar timeFilter = ee.Filter.or(\n ee.Filter.maxDifference({\n difference: twoDaysMillis,\n leftField: 'system:time_start',\n rightField: 'system:time_end'\n }),\n ee.Filter.maxDifference({\n difference: twoDaysMillis,\n leftField: 'system:time_end',\n rightField: 'system:time_start'\n })\n);\n\n// Define the join.\nvar saveAllJoin = ee.Join.saveAll({\n matchesKey: 'terra',\n ordering: 'system:time_start',\n ascending: true\n});\n\n// Apply the join.\nvar landsatModis = saveAllJoin.apply(primary, modSecondary, timeFilter);\n\n// Display the result.\nprint('Join.saveAll:', landsatModis);\n```\nPython setup\n\nSee the [Python Environment](/earth-engine/guides/python_install) page for information on the Python API and using\n`geemap` for interactive development. \n\n```python\nimport ee\nimport geemap.core as geemap\n```\n\n### Colab (Python)\n\n```python\n# Load a primary collection: Landsat imagery.\nprimary = (\n ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')\n .filterDate('2014-04-01', '2014-06-01')\n .filterBounds(ee.Geometry.Point(-122.092, 37.42))\n)\n\n# Load a secondary collection: MODIS imagery.\nmod_secondary = ee.ImageCollection('MODIS/006/MOD09GA').filterDate(\n '2014-03-01', '2014-07-01'\n)\n\n# Define an allowable time difference: two days in milliseconds.\ntwo_days_millis = 2 * 24 * 60 * 60 * 1000\n\n# Create a time filter to define a match as overlapping timestamps.\ntime_filter = ee.Filter.Or(\n ee.Filter.maxDifference(\n difference=two_days_millis,\n leftField='system:time_start',\n rightField='system:time_end',\n ),\n ee.Filter.maxDifference(\n difference=two_days_millis,\n leftField='system:time_end',\n rightField='system:time_start',\n ),\n)\n\n# Define the join.\nsave_all_join = ee.Join.saveAll(\n matchesKey='terra', ordering='system:time_start', ascending=True\n)\n\n# Apply the join.\nlandsat_modis = save_all_join.apply(primary, mod_secondary, time_filter)\n\n# Display the result.\ndisplay('Join.saveAll:', landsat_modis)\n```\n\nIn this example, note that the `secondary` MODIS collection is pre-filtered to be\nchronologically similar to the `primary` Landsat collection for efficiency. To\ncompare the Landsat acquisition time to the MODIS composite time, which has a daily range,\nthe filter compares the endpoints of the image timestamps. The join is defined with the\nname of the property used to store the list of matches for each Landsat image\n(`'terra'`) and optional parameter to sort the list of matches by the\n`system:time_start` property\n\nInspection of the result indicates that images within the primary collection have the\nadded `terra` property which stores a list of the matching MODIS images."]]
