docs: queries return MultiPolygons whole

src/spatialdata/_core/query/spatial_query.py

@@ -527,6 +527,10 @@ def bounding_box_query(
     -----
     If the object has `points` element, depending on the number of points, it MAY suffer from performance issues. Please
     consider filtering the object before calling this function by calling the `subset()` method of `SpatialData`.
+
+    Shapes are not cut to the bounding box: a shape that intersects it is returned whole. For a `MultiPolygon` this
+    includes components that lie entirely outside the bounding box. To cut the shapes to the bounding box, use
+    :func:`polygon_query` with `clip=True` and the bounding box as polygon, e.g. `shapely.box(xmin, ymin, xmax, ymax)`.
     """
     raise RuntimeError("Unsupported type for bounding_box_query: " + str(type(element)) + ".")
 
@@ -891,8 +895,10 @@ def polygon_query(
         Specifies whether to filter the tables to only include tables that annotate elements in the retrieved
         SpatialData object of the query.
     clip
-        If `True`, the shapes are clipped to the polygon. This behavior is implemented only when querying
-        polygons/multipolygons or circles, and it is ignored for other types of elements (images, labels, points).
+        If `True`, the shapes are clipped to the polygon. If `False`, a shape that intersects the polygon is returned
+        whole, and for a `MultiPolygon` this includes components that lie entirely outside the polygon. This behavior is
+        implemented only when querying polygons/multipolygons or circles, and it is ignored for other types of elements
+        (images, labels, points).
         Importantly, when clipping is enabled, the circles will be converted to polygons before the clipping. This may
         affect downstream operations that rely on the circle radius or on performance, so it is recommended to disable
         clipping when querying circles or when querying a `SpatialData` object that contains circles.