Join elements table

CHANGELOG.md

@@ -16,6 +16,12 @@ and this project adheres to [Semantic Versioning][].
 
 -   Implemented support in SpatialData for storing multiple tables. These tables
     can annotate a SpatialElement but not necessarily so.
+-   Added SQL like joins that can be executed by calling one public function `join_sdata_spatialelement_table`. The following
+    joins are supported: `left`, `left_exclusive`, `right`, `right_exclusive` and `inner`. The function has an option to
+    match rows. For `left` only matching `left` is supported and for `right` join only `right` matching of rows is supported.
+    Not all joins are supported for `Labels` elements.
+-   Added function `match_element_to_table` which allows the user to perform a right join of `SpatialElement`(s) with a table
+    with rows matching the row order in the table.
 -   Increased in-memory vs on-disk control: changes performed in-memory (e.g. adding a new image) are not automatically performed on-disk.
 
 #### Minor

docs/api.md

@@ -27,6 +27,8 @@ Operations on `SpatialData` objects.
     polygon_query
     get_values
     get_extent
+    join_sdata_spatialelement_table
+    match_element_to_table
     match_table_to_element
     concatenate
     transform

docs/design_doc.md

@@ -564,6 +564,7 @@ with coordinate systems:
     with axes: c, y, x
     with elements: /images/point8, /labels/point8
 """
+
 sdata0 = sdata.query.coordinate_system("point23", filter_rows=False)
 sdata1 = sdata.query.bounding_box((0, 20, 0, 300))
 sdata1 = sdata.query.polygon("/polygons/annotations")

src/spatialdata/__init__.py

@@ -22,6 +22,8 @@
     "bounding_box_query",
     "polygon_query",
     "get_values",
+    "join_sdata_spatialelement_table",
+    "match_element_to_table",
     "match_table_to_element",
     "SpatialData",
     "get_extent",
@@ -38,7 +40,12 @@
 from spatialdata._core.operations.rasterize import rasterize
 from spatialdata._core.operations.transform import transform
 from spatialdata._core.query._utils import circles_to_polygons, get_bounding_box_corners
-from spatialdata._core.query.relational_query import get_values, match_table_to_element
+from spatialdata._core.query.relational_query import (
+    get_values,
+    join_sdata_spatialelement_table,
+    match_element_to_table,
+    match_table_to_element,
+)
 from spatialdata._core.query.spatial_query import bounding_box_query, polygon_query
 from spatialdata._core.spatialdata import SpatialData
 from spatialdata._io._utils import get_dask_backing_files, save_transformations