diff --git a/docs/hyperdatasets/dataviews.md b/docs/hyperdatasets/dataviews.md index c02e140a..1f26a841 100644 --- a/docs/hyperdatasets/dataviews.md +++ b/docs/hyperdatasets/dataviews.md @@ -139,9 +139,9 @@ You can retrieve the Dataview frames using [`DataView.to_list()`](../references/ [`DataView.to_dict()`](../references/hyperdataset/dataview.md#to_dict), or [`DataView.get_iterator()`](../references/hyperdataset/dataview.md#get_iterator) (see [Accessing Frames](#accessing-frames)). -#### ROI Queries: +### ROI Query Examples -* **ROI query for a single label** +#### ROI query for a single label This example uses an ROI query to filter for frames containing at least one ROI with the label `cat`: @@ -163,7 +163,7 @@ myDataView.add_query( list_of_frames = myDataView.to_list() ``` -* **ROI query for one label OR another** +#### ROI query for one label OR another This example uses an ROI query to filter for frames containing at least one ROI with either the label `cat` OR the label `dog`: @@ -188,7 +188,7 @@ myDataView.add_query( list_of_frames = myDataView.to_list() ``` -* **ROI query for two specific labels in the same ROI** +#### ROI query for two specific labels in the same ROI This example uses an ROI query to filter for frames containing at least one ROI with both the label `Car` AND the label `partly_occluded`: @@ -207,7 +207,7 @@ myDataView.add_query( list_of_frames = myDataView.to_list() ``` -* **ROI query for one label AND NOT another (Lucene query)** +#### ROI query for one label AND NOT another (Lucene query) This example uses an ROI query to filter for frames containing at least one ROI that has with the label `Car` AND DOES NOT have the label `partly_occluded`: @@ -230,7 +230,7 @@ myDataView.add_query( list_of_frames = myDataView.to_list() ``` -* **ROI query for one label AND another label in different ROIs** +#### ROI query for one label AND another label in different ROIs This example uses an ROI query to filter for frames containing at least one ROI with the label `Car` and at least one ROI with the label `Person`. The example demonstrates using the `roi_queries` parameter of [`DataView.add_multi_query()`](../references/hyperdataset/dataview.md#add_multi_query) @@ -250,7 +250,7 @@ myDataview.add_multi_query( list_of_frames = myDataView.to_list() ``` -* **ROI query for one label AND NOT another label in different ROIs** +#### ROI query for one label AND NOT another label in different ROIs This example uses an ROI query to filter for frames containing at least one ROI with the label `Car` AND that DO NOT contain ROIs with the label `Person`. To exclude an ROI, pass `must_not=True` in the [`DataView.RoiQuery`](../references/hyperdataset/dataview.md#roiquery) @@ -311,7 +311,7 @@ myDataView.add_query( list_of_frames = myDataView.to_list() ``` -#### Frame Queries +### Frame Queries Use frame queries to filter frames by ROI labels and/or frame metadata key-value pairs that a frame must include or exclude for the Dataview to return the frame. @@ -319,6 +319,8 @@ exclude for the Dataview to return the frame. **Frame queries** match frame meta key-value pairs, ROI labels, or both. They use the same logical OR, AND, NOT AND matching as ROI queries. +#### Frame Query by Metadata + This example demonstrates a frame query filtering for frames containing the meta key `city` value of `bremen`: ```python @@ -336,6 +338,59 @@ myDataView.add_query( list_of_frames = myDataView.to_list() ``` +#### Frame Query by Date and Time +Provided that a metadata field stores date and time values, you can query frames based on date ranges and specific time +intervals + +##### Frame Query for Specific Date +This example demonstrates a frame query filtering for frames containing the meta key `updated` with the value of October +20th, 2024: + +```python +# Add a frame query for frames with the meta key "updated" value of "2024-10-20" +myDataView.add_query( + dataset_name='myDataset', + version_name='version', + frame_query='meta.updated:[2024-10-20 TO 2024-10-20]' +) + +# retrieving the actual SingleFrames / FrameGroups +# you can also iterate over the frames with `for frame in myDataView.get_iterator():` +list_of_frames = myDataView.to_list() +``` + +##### Frame Query for Date Range + +This example demonstrates a frame query filtering for frames containing the meta key `updated` with any value between the +dates of October 20th and October 30th, 2024: + +```python +# Add a frame query for frames with the meta key "updated" value between "2024-10-20" and "2024-10-30" +myDataView.add_query( + dataset_name='myDataset', + version_name='version', + frame_query='meta.updated:[2024-10-20 TO 2024-10-30]' +) + +# retrieving the actual SingleFrames / FrameGroups +# you can also iterate over the frames with `for frame in myDataView.get_iterator():` +list_of_frames = myDataView.to_list() +``` + +##### Frame Query for Time Interval + +This example demonstrates a frame query filtering for frames containing the meta key `updated` with any value between +`08:000` and `09:00` on October 20th, 2024: + +```python +# Add a frame query for frames with the meta key's value between 08:00:00 and 09:00:00 on 2024-10-20 + +myDataView.add_query( + dataset_name='myDataset', + version_name='version', + frame_query='meta.:[2024-10-20T08:00:00 TO 2024-10-20T09:00:00]' +) +``` ### Controlling Query Iteration diff --git a/docs/hyperdatasets/webapp/webapp_datasets_versioning.md b/docs/hyperdatasets/webapp/webapp_datasets_versioning.md index 7f2c70e8..dfa64503 100644 --- a/docs/hyperdatasets/webapp/webapp_datasets_versioning.md +++ b/docs/hyperdatasets/webapp/webapp_datasets_versioning.md @@ -163,7 +163,7 @@ described in the example above. "Frame Filter 2" specifies an ROI rule for the f To clear all filters click Clear filters. -#### Filtering Examples +### Filtering Examples @@ -199,7 +199,7 @@ To clear all filters click - + Filter by metadata using Lucene queries. @@ -215,6 +215,40 @@ Filter by metadata using Lucene queries. + + +If your dataset includes a metadata field that stores date and time information, you can filter +based on date ranges or specific time intervals. + +Filter by date/time metadata fields using Lucene queries. + +* **Data range filter** + * Add a frame rule to filter by the metadata key `updated` for the value of `[2024-10-20 TO 2024-10-20]`. The query + will match all frames where the `updated` value matches October 20th 2024. Use the format `meta..[YYYY-MM-DD TO YYYY-MM-DD]`. + + ![Filter by date](../../img/hyperdatasets/frame_filtering_11.png#light-mode-only) + ![Filter by date](../../img/hyperdatasets/frame_filtering_11_dark.png#dark-mode-only) + + * Open a frame in the frame viewer to see its metadata. + + ![Frame date metadata in frame viewer](../../img/hyperdatasets/frame_filtering_12.png#light-mode-only) + ![Frame date metadata in frame viewer](../../img/hyperdatasets/frame_filtering_12_dark.png#dark-mode-only) + +* **Time interval filter** + * Add a frame rule to filter by the metadata key `updated` for the value of `[2024-10-20T08:00:00 TO 2024-10-20T09:00:00]`. + The query will match all frames where the updated value is between 08:00 and 09:00 on October 20th 2024. + Use the format `meta..[YYYY-MM-DDThh:mm:ss TO YYYY-MM-DDThh:mm:ss]`. + + ![Filter by datetime](../../img/hyperdatasets/frame_filtering_13.png#light-mode-only) + ![Filter by datetime](../../img/hyperdatasets/frame_filtering_13_dark.png#dark-mode-only) + + * Open a frame in the frame viewer to see its metadata. + + ![Frame datetimee metadata in frame viewer](../../img/hyperdatasets/frame_filtering_14.png#light-mode-only) + ![Frame datetime metadata in frame viewer](../../img/hyperdatasets/frame_filtering_14_dark.png#dark-mode-only) + + + Filter by sources using Lucene queries. diff --git a/docs/img/hyperdatasets/frame_filtering_11.png b/docs/img/hyperdatasets/frame_filtering_11.png new file mode 100644 index 00000000..ce6be171 Binary files /dev/null and b/docs/img/hyperdatasets/frame_filtering_11.png differ diff --git a/docs/img/hyperdatasets/frame_filtering_11_dark.png b/docs/img/hyperdatasets/frame_filtering_11_dark.png new file mode 100644 index 00000000..394145cb Binary files /dev/null and b/docs/img/hyperdatasets/frame_filtering_11_dark.png differ diff --git a/docs/img/hyperdatasets/frame_filtering_12.png b/docs/img/hyperdatasets/frame_filtering_12.png new file mode 100644 index 00000000..732b761c Binary files /dev/null and b/docs/img/hyperdatasets/frame_filtering_12.png differ diff --git a/docs/img/hyperdatasets/frame_filtering_12_dark.png b/docs/img/hyperdatasets/frame_filtering_12_dark.png new file mode 100644 index 00000000..e3bdde1a Binary files /dev/null and b/docs/img/hyperdatasets/frame_filtering_12_dark.png differ diff --git a/docs/img/hyperdatasets/frame_filtering_13.png b/docs/img/hyperdatasets/frame_filtering_13.png new file mode 100644 index 00000000..dce2435d Binary files /dev/null and b/docs/img/hyperdatasets/frame_filtering_13.png differ diff --git a/docs/img/hyperdatasets/frame_filtering_13_dark.png b/docs/img/hyperdatasets/frame_filtering_13_dark.png new file mode 100644 index 00000000..e76fb604 Binary files /dev/null and b/docs/img/hyperdatasets/frame_filtering_13_dark.png differ diff --git a/docs/img/hyperdatasets/frame_filtering_14.png b/docs/img/hyperdatasets/frame_filtering_14.png new file mode 100644 index 00000000..df6a95a9 Binary files /dev/null and b/docs/img/hyperdatasets/frame_filtering_14.png differ diff --git a/docs/img/hyperdatasets/frame_filtering_14_dark.png b/docs/img/hyperdatasets/frame_filtering_14_dark.png new file mode 100644 index 00000000..3c98b41f Binary files /dev/null and b/docs/img/hyperdatasets/frame_filtering_14_dark.png differ