feat(instance-search): add sorting options for instances by created and updated date (#849)

psmagin · web-flow · commit 33783a188bb7 · 2025-10-13T16:53:23.000+03:00
Closes: MSEARCH-825
diff --git a/NEWS.md b/NEWS.md
@@ -34,6 +34,7 @@
   * Add support for searching by instance/holdings/item electronic access relationship ID ([MSEARCH-816](https://folio-org.atlassian.net/browse/MSEARCH-816))
   * Normalize ISSN search ([MSEARCH-658](https://folio-org.atlassian.net/browse/MSEARCH-658))
   * Separate LCCN and Canceled LCCN identifiers search to lccn and canceledLccn options ([MSEARCH-1065](https://folio-org.atlassian.net/browse/MSEARCH-1065))
+  * Add sorting options for instances by created and updated date ([MSEARCH-825](https://folio-org.atlassian.net/browse/MSEARCH-825))
 * **Linked Data Instance and Work**
   * Search by classification type/number/additionalNumber ([MSEARCH-989](https://folio-org.atlassian.net/browse/MSEARCH-989))
 
diff --git a/README.md b/README.md
@@ -963,21 +963,22 @@ In case where options are similar, secondary sort is used
 
 ##### Instance sort options
 
-| Option              |   Type    | Secondary sort | Description                        |
-|:--------------------|:---------:|:---------------|:-----------------------------------|
-| `title`             | full text | relevancy      | Sort instances by title            |
-| `contributors`      |   term    | relevancy      | Sort instances by contributors     |
-| `items.status.name` |   term    | `title`        | Sort instances by status           |
-| `item.status.name`  |   term    | `title`        | Sort instances by status           |
-| `normalizedDate1`   |   term    | relevancy      | Sort instances by normalizedDate1  |
+| Option                  | Secondary sort | Description                           |
+|:------------------------|:---------------|:--------------------------------------|
+| `title`                 | relevancy      | Sort instances by title               |
+| `contributors`          | relevancy      | Sort instances by contributors        |
+| `item.status.name`      | `title`        | Sort instances by status              |
+| `normalizedDate1`       | relevancy      | Sort instances by normalizedDate1     |
+| `metadata.createdDate`  | relevancy      | Sort instances by created date        |
+| `metadata.updatedDate`  | relevancy      | Sort instances by updated date        |
 
 ##### Authority sort options
 
-| Option        | Type | Secondary sort | Description                             |
-|:--------------|:----:|:---------------|:----------------------------------------|
-| `headingRef`  | term | relevancy      | Sort authorities by Heading/Reference   |
-| `headingType` | term | `headingRef`   | Sort authorities by Type of heading     |
-| `authRefType` | term | `headingRef`   | Sort authorities by Authority/Reference |
+| Option        | Secondary sort | Description                             |
+|:--------------|:---------------|:----------------------------------------|
+| `headingRef`  | relevancy      | Sort authorities by Heading/Reference   |
+| `headingType` | `headingRef`   | Sort authorities by Type of heading     |
+| `authRefType` | `headingRef`   | Sort authorities by Authority/Reference |
 
 ### Browse API
 
diff --git a/src/main/resources/model/instance.json b/src/main/resources/model/instance.json
@@ -177,15 +177,23 @@
       "type": "object",
       "properties": {
         "createdDate": {
-          "searchTypes": "filter",
-          "index": "date"
+          "searchTypes": [ "filter", "sort" ],
+          "index": "date",
+          "sort": {
+            "fieldName": "metadata.createdDate",
+            "type": "single"
+          }
         },
         "createdByUserId": {
           "index": "keyword_lowercase"
         },
         "updatedDate": {
-          "searchTypes": "filter",
-          "index": "date"
+          "searchTypes": [ "filter", "sort" ],
+          "index": "date",
+          "sort": {
+            "fieldName": "metadata.updatedDate",
+            "type": "single"
+          }
         },
         "updatedByUserId": {
           "index": "keyword_lowercase"
diff --git a/src/main/resources/swagger.api/parameters/instance-search-cql-query.yaml b/src/main/resources/swagger.api/parameters/instance-search-cql-query.yaml
@@ -331,6 +331,48 @@ description: |
     </tr>
     </tbody>
     </table>
+    <h5 id="instance-sort-options">Instance sort options</h5>
+    <table>
+    <thead>
+    <tr>
+        <th>Option</th>
+        <th>Secondary sort</th>
+        <th>Description</th>
+    </tr>
+    </thead>
+    <tbody>
+    <tr>
+        <td>title</td>
+        <td>relevancy</td>
+        <td>Sort instances by title</td>
+    </tr>
+    <tr>
+        <td>contributors</td>
+        <td>relevancy</td>
+        <td>Sort instances by contributors</td>
+    </tr>
+    <tr>
+        <td>item.status.name</td>
+        <td>title</td>
+        <td>Sort instances by status</td>
+    </tr>
+    <tr>
+        <td>normalizedDate1</td>
+        <td>relevancy</td>
+        <td>Sort instances by normalizedDate1</td>
+    </tr>
+    <tr>
+        <td>metadata.createdDate</td>
+        <td>relevancy</td>
+        <td>Sort instances by created date</td>
+    </tr>
+    <tr>
+        <td>metadata.updatedDate</td>
+        <td>relevancy</td>
+        <td>Sort instances by updated date</td>
+    </tr>
+    </tbody>
+    </table>
     <h5 id="holdings-search-options">Holdings search options</h5>
     <table>
     <thead>
diff --git a/src/test/java/org/folio/api/search/SortInstanceIT.java b/src/test/java/org/folio/api/search/SortInstanceIT.java
@@ -12,6 +12,7 @@
 import org.folio.search.domain.dto.Contributor;
 import org.folio.search.domain.dto.Dates;
 import org.folio.search.domain.dto.Instance;
+import org.folio.search.domain.dto.Metadata;
 import org.folio.spring.testing.type.IntegrationTest;
 import org.folio.support.base.BaseIntegrationTest;
 import org.junit.jupiter.api.AfterAll;
@@ -21,6 +22,12 @@
 @IntegrationTest
 class SortInstanceIT extends BaseIntegrationTest {
 
+  private static final String ID_ANIMAL_FARM = randomId();
+  private static final String ID_ZERO_MINUS_TEN = randomId();
+  private static final String ID_CALLING_ME_HOME = randomId();
+  private static final String ID_WALK_IN_MY_SOUL = randomId();
+  private static final String ID_STAR_WARS = randomId();
+
   @BeforeAll
   static void prepare() {
     setUpTenant(instances());
@@ -91,6 +98,50 @@ void canSortInstancesByTitle_desc() throws Exception {
       .andExpect(jsonPath("instances[4].title", is("Calling Me Home")));
   }
 
+  @Test
+  void canSortInstancesByMetadataCreatedDate_asc() throws Exception {
+    doSearchByInstances(allRecordsSortedBy("metadata.createdDate", ASCENDING))
+      .andExpect(jsonPath("totalRecords", is(5)))
+      .andExpect(jsonPath("instances[0].id", is(ID_ANIMAL_FARM)))
+      .andExpect(jsonPath("instances[1].id", is(ID_ZERO_MINUS_TEN)))
+      .andExpect(jsonPath("instances[2].id", is(ID_CALLING_ME_HOME)))
+      .andExpect(jsonPath("instances[3].id", is(ID_WALK_IN_MY_SOUL)))
+      .andExpect(jsonPath("instances[4].id", is(ID_STAR_WARS)));
+  }
+
+  @Test
+  void canSortInstancesByMetadataCreatedDate_desc() throws Exception {
+    doSearchByInstances(allRecordsSortedBy("metadata.createdDate", DESCENDING))
+      .andExpect(jsonPath("totalRecords", is(5)))
+      .andExpect(jsonPath("instances[0].id", is(ID_STAR_WARS)))
+      .andExpect(jsonPath("instances[1].id", is(ID_WALK_IN_MY_SOUL)))
+      .andExpect(jsonPath("instances[2].id", is(ID_CALLING_ME_HOME)))
+      .andExpect(jsonPath("instances[3].id", is(ID_ZERO_MINUS_TEN)))
+      .andExpect(jsonPath("instances[4].id", is(ID_ANIMAL_FARM)));
+  }
+
+  @Test
+  void canSortInstancesByMetadataUpdatedDate_asc() throws Exception {
+    doSearchByInstances(allRecordsSortedBy("metadata.updatedDate", ASCENDING))
+      .andExpect(jsonPath("totalRecords", is(5)))
+      .andExpect(jsonPath("instances[0].id", is(ID_ANIMAL_FARM)))
+      .andExpect(jsonPath("instances[1].id", is(ID_ZERO_MINUS_TEN)))
+      .andExpect(jsonPath("instances[2].id", is(ID_CALLING_ME_HOME)))
+      .andExpect(jsonPath("instances[3].id", is(ID_WALK_IN_MY_SOUL)))
+      .andExpect(jsonPath("instances[4].id", is(ID_STAR_WARS)));
+  }
+
+  @Test
+  void canSortInstancesByMetadataUpdatedDate_desc() throws Exception {
+    doSearchByInstances(allRecordsSortedBy("metadata.updatedDate", DESCENDING))
+      .andExpect(jsonPath("totalRecords", is(5)))
+      .andExpect(jsonPath("instances[0].id", is(ID_STAR_WARS)))
+      .andExpect(jsonPath("instances[1].id", is(ID_WALK_IN_MY_SOUL)))
+      .andExpect(jsonPath("instances[2].id", is(ID_CALLING_ME_HOME)))
+      .andExpect(jsonPath("instances[3].id", is(ID_ZERO_MINUS_TEN)))
+      .andExpect(jsonPath("instances[4].id", is(ID_ANIMAL_FARM)));
+  }
+
   @Test
   void search_negative_invalidSortOption() throws Exception {
     attemptSearchByInstances(allRecordsSortedBy("unknownSort", DESCENDING)).andExpect(
@@ -103,35 +154,52 @@ void search_negative_invalidSortOption() throws Exception {
   }
 
   private static Instance[] instances() {
-    var instances = new Instance[] {getSemanticWeb().id(randomId()).contributors(new ArrayList<>()),
-                                    getSemanticWeb().id(randomId()).contributors(new ArrayList<>()),
-                                    getSemanticWeb().id(randomId()).contributors(new ArrayList<>()),
-                                    getSemanticWeb().id(randomId()).contributors(new ArrayList<>()),
-                                    getSemanticWeb().id(randomId()).contributors(new ArrayList<>())};
-
+    var instances = new Instance[] {
+      getSemanticWeb().id(ID_ANIMAL_FARM).contributors(new ArrayList<>()),
+      getSemanticWeb().id(ID_ZERO_MINUS_TEN).contributors(new ArrayList<>()),
+      getSemanticWeb().id(ID_CALLING_ME_HOME).contributors(new ArrayList<>()),
+      getSemanticWeb().id(ID_WALK_IN_MY_SOUL).contributors(new ArrayList<>()),
+      getSemanticWeb().id(ID_STAR_WARS).contributors(new ArrayList<>())
+    };
     instances[0].title("Animal farm")
       .indexTitle("B1 Animal farm")
       .addContributorsItem(new Contributor().name("yyy zzz"))
-      .setDates(getDates("1999", "2000"));
+      .dates(getDates("1999", "2000"))
+      .metadata(new Metadata()
+        .createdDate("2021-01-01T10:00:00.000+00:00")
+        .updatedDate("2021-01-15T10:00:00.000+00:00"));
 
     instances[1].title("Zero Minus Ten")
       .indexTitle(null)
       .addContributorsItem(new Contributor().name("aaa bbb").primary(false))
       .addContributorsItem(new Contributor().name("bbb ccc").primary(true))
-      .setDates(getDates("199u", "2000"));
+      .dates(getDates("199u", "2000"))
+      .metadata(new Metadata()
+        .createdDate("2021-02-01T10:00:00.000+00:00")
+        .updatedDate("2021-02-15T10:00:00.000+00:00"));
 
     instances[2].title("Calling Me Home")
       .indexTitle("A1 Calling Me Home")
       .addContributorsItem(new Contributor().name("bcc ccc"))
-      .setDates(getDates("2021", "2022"));
+      .dates(getDates("2021", "2022"))
+      .metadata(new Metadata()
+        .createdDate("2021-03-01T10:00:00.000+00:00")
+        .updatedDate("2021-03-15T10:00:00.000+00:00"));
 
     instances[3].title("Walk in My Soul")
       .indexTitle(null)
       .addContributorsItem(new Contributor().name("1111 2222").primary(true))
-      .setDates(getDates("2001", "2002"));
-
-    instances[4].title("Star Wars").indexTitle(null).addContributorsItem(new Contributor().name("Śląsk").primary(true))
-      .setDates(getDates("19u5", "1998"));
+      .dates(getDates("2001", "2002"))
+      .metadata(new Metadata()
+        .createdDate("2021-04-01T10:00:00.000+00:00")
+        .updatedDate("2021-04-15T10:00:00.000+00:00"));
+
+    instances[4].title("Star Wars").indexTitle(null)
+      .addContributorsItem(new Contributor().name("Śląsk").primary(true))
+      .dates(getDates("19u5", "1998"))
+      .metadata(new Metadata()
+        .createdDate("2021-05-01T10:00:00.000+00:00")
+        .updatedDate("2021-05-15T10:00:00.000+00:00"));
 
     return instances;
   }
