Add bulk search functionality to SearchResource

alex-omophub · alex-omophub · commit 7fda72c7fdad · 2026-03-26T17:40:58.000Z
- Introduced `bulk_basic()` method for executing multiple lexical searches in a single request, supporting up to 50 queries.
- Added `bulk_semantic()` method for performing multiple semantic searches, allowing up to 25 queries.
- Updated README with examples for both bulk search methods.
- Enhanced tests to validate the new bulk search functionalities, including input validation and endpoint correctness.
diff --git a/R/search.R b/R/search.R
@@ -327,6 +327,66 @@ SearchResource <- R6::R6Class(
       paginate_all(fetch_fn, page_size = page_size, max_pages = max_pages, progress = progress)
     },
 
+    #' @description
+    #' Execute multiple lexical searches in a single request (max 50).
+    #'
+    #' @param searches List of search inputs. Each element is a named list with:
+    #'   - `search_id` (required): Unique ID to match results.
+    #'   - `query` (required): Search query string.
+    #'   - `vocabulary_ids`, `domain_ids`, `concept_class_ids`: Optional filters.
+    #'   - `standard_concept`, `include_invalid`, `page_size`: Optional params.
+    #' @param defaults Named list of default filters applied to all searches.
+    #'   Individual search-level values override defaults.
+    #'
+    #' @returns List with `results` (per-search), `total_searches`,
+    #'   `completed_searches`, `failed_searches`.
+    bulk_basic = function(searches, defaults = NULL) {
+      checkmate::assert_list(searches, min.len = 1, max.len = 50)
+      for (s in searches) {
+        checkmate::assert_list(s)
+        checkmate::assert_string(s$search_id, min.chars = 1)
+        checkmate::assert_string(s$query, min.chars = 1)
+      }
+
+      body <- list(searches = searches)
+      if (!is.null(defaults)) {
+        checkmate::assert_list(defaults)
+        body$defaults <- defaults
+      }
+
+      perform_post(private$.base_req, "search/bulk", body = body)
+    },
+
+    #' @description
+    #' Execute multiple semantic searches in a single request (max 25).
+    #'
+    #' @param searches List of search inputs. Each element is a named list with:
+    #'   - `search_id` (required): Unique ID to match results.
+    #'   - `query` (required): Natural language query (1-500 chars).
+    #'   - `threshold`: Per-search similarity threshold (0-1).
+    #'   - `page_size`: Per-search result limit (1-50).
+    #'   - `vocabulary_ids`, `domain_ids`, `standard_concept`: Optional filters.
+    #' @param defaults Named list of default filters applied to all searches.
+    #'
+    #' @returns List with `results` (per-search), `total_searches`,
+    #'   `completed_count`, `failed_count`, `total_duration`.
+    bulk_semantic = function(searches, defaults = NULL) {
+      checkmate::assert_list(searches, min.len = 1, max.len = 25)
+      for (s in searches) {
+        checkmate::assert_list(s)
+        checkmate::assert_string(s$search_id, min.chars = 1)
+        checkmate::assert_string(s$query, min.chars = 1, max.chars = 500)
+      }
+
+      body <- list(searches = searches)
+      if (!is.null(defaults)) {
+        checkmate::assert_list(defaults)
+        body$defaults <- defaults
+      }
+
+      perform_post(private$.base_req, "search/semantic-bulk", body = body)
+    },
+
     #' @description
     #' Find concepts similar to a reference concept or query.
     #'
@@ -419,7 +479,7 @@ SearchResource <- R6::R6Class(
     #' Print resource information.
     print = function() {
       cat("<OMOPHub SearchResource>\n")
-      cat("  Methods: basic, basic_all, advanced, autocomplete, semantic, semantic_all, similar\n")
+      cat("  Methods: basic, basic_all, advanced, autocomplete, semantic, semantic_all, bulk_basic, bulk_semantic, similar\n")
       invisible(self)
     }
   ),
diff --git a/README.md b/README.md
@@ -111,6 +111,29 @@ for (s in similar$similar_concepts) {
 }
 ```
 
+### Bulk Search
+
+Search for multiple terms in a single API call:
+
+```r
+# Bulk lexical search (up to 50 queries)
+results <- client$search$bulk_basic(list(
+  list(search_id = "q1", query = "diabetes mellitus"),
+  list(search_id = "q2", query = "hypertension"),
+  list(search_id = "q3", query = "aspirin")
+), defaults = list(vocabulary_ids = list("SNOMED"), page_size = 5))
+
+for (item in results$results) {
+  cat(sprintf("%s: %d results\n", item$search_id, length(item$results)))
+}
+
+# Bulk semantic search (up to 25 queries)
+results <- client$search$bulk_semantic(list(
+  list(search_id = "s1", query = "heart failure treatment options"),
+  list(search_id = "s2", query = "type 2 diabetes medication")
+), defaults = list(threshold = 0.5, page_size = 10))
+```
+
 ## Use Cases
 
 ### ETL & Data Pipelines
@@ -198,7 +221,7 @@ concepts_df %>%
 | Resource | Description | Key Methods |
 |----------|-------------|-------------|
 | `concepts` | Concept lookup and batch operations | `get()`, `get_by_code()`, `batch()`, `suggest()` |
-| `search` | Full-text and semantic search | `basic()`, `advanced()`, `semantic()`, `semantic_all()`, `similar()`, `basic_all()` |
+| `search` | Full-text and semantic search | `basic()`, `advanced()`, `semantic()`, `similar()`, `bulk_basic()`, `bulk_semantic()` |
 | `hierarchy` | Navigate concept relationships | `ancestors()`, `descendants()` |
 | `mappings` | Cross-vocabulary mappings | `get()`, `map()` |
 | `vocabularies` | Vocabulary metadata | `list()`, `get()`, `stats()` |
diff --git a/tests/testthat/test-search-integration.R b/tests/testthat/test-search-integration.R
@@ -315,3 +315,76 @@ test_that("similar with vocabulary filter works", {
     }
   }
 })
+
+# ==============================================================================
+# Bulk lexical search integration tests
+# ==============================================================================
+
+test_that("bulk_basic search works with multiple queries", {
+  skip_if_no_integration_key()
+  client <- integration_client()
+
+  result <- client$search$bulk_basic(list(
+    list(search_id = "q1", query = "diabetes mellitus"),
+    list(search_id = "q2", query = "hypertension"),
+    list(search_id = "q3", query = "aspirin")
+  ), defaults = list(page_size = 5))
+
+  results <- extract_data(result, "results")
+  expect_length(results, 3)
+
+  for (item in results) {
+    expect_true(item$search_id %in% c("q1", "q2", "q3"))
+    expect_equal(item$status, "completed")
+    expect_gt(length(item$results), 0)
+  }
+})
+
+test_that("bulk_basic search works with vocabulary filter", {
+  skip_if_no_integration_key()
+  client <- integration_client()
+
+  result <- client$search$bulk_basic(
+    list(list(search_id = "snomed1", query = "diabetes")),
+    defaults = list(vocabulary_ids = list("SNOMED"), page_size = 3)
+  )
+
+  results <- extract_data(result, "results")
+  expect_length(results, 1)
+  expect_equal(results[[1]]$status, "completed")
+})
+
+# ==============================================================================
+# Bulk semantic search integration tests
+# ==============================================================================
+
+test_that("bulk_semantic search works with multiple queries", {
+  skip_if_no_integration_key()
+  client <- integration_client()
+
+  result <- client$search$bulk_semantic(list(
+    list(search_id = "s1", query = "heart failure treatment options"),
+    list(search_id = "s2", query = "type 2 diabetes medication")
+  ), defaults = list(threshold = 0.5, page_size = 5))
+
+  results <- extract_data(result, "results")
+  expect_length(results, 2)
+
+  for (item in results) {
+    expect_true(item$search_id %in% c("s1", "s2"))
+    expect_equal(item$status, "completed")
+  }
+})
+
+test_that("bulk_semantic search works with single query", {
+  skip_if_no_integration_key()
+  client <- integration_client()
+
+  result <- client$search$bulk_semantic(
+    list(list(search_id = "one", query = "elevated blood pressure", threshold = 0.5))
+  )
+
+  results <- extract_data(result, "results")
+  expect_length(results, 1)
+  expect_equal(results[[1]]$search_id, "one")
+})
diff --git a/tests/testthat/test-search.R b/tests/testthat/test-search.R
@@ -915,3 +915,122 @@ test_that("SearchResource print method includes new methods", {
   expect_output(print(resource), "similar")
 })
 
+# ==============================================================================
+# bulk_basic() method
+# ==============================================================================
+
+test_that("search$bulk_basic validates searches", {
+  base_req <- httr2::request("https://api.omophub.com/v1")
+  resource <- SearchResource$new(base_req)
+
+  expect_error(resource$bulk_basic(list()))  # Empty list
+  expect_error(resource$bulk_basic(list(list(search_id = "", query = "test"))))  # Empty search_id
+  expect_error(resource$bulk_basic(list(list(search_id = "q1", query = ""))))  # Empty query
+})
+
+test_that("search$bulk_basic calls correct endpoint", {
+  base_req <- httr2::request("https://api.omophub.com/v1")
+  resource <- SearchResource$new(base_req)
+
+  called_with <- NULL
+  local_mocked_bindings(
+    perform_post = function(req, path, body = NULL) {
+      called_with <<- list(path = path, body = body)
+      list(results = list(), total_searches = 0, completed_searches = 0, failed_searches = 0)
+    }
+  )
+
+  resource$bulk_basic(list(
+    list(search_id = "q1", query = "diabetes"),
+    list(search_id = "q2", query = "hypertension")
+  ))
+
+  expect_equal(called_with$path, "search/bulk")
+  expect_length(called_with$body$searches, 2)
+  expect_equal(called_with$body$searches[[1]]$search_id, "q1")
+  expect_equal(called_with$body$searches[[2]]$query, "hypertension")
+})
+
+test_that("search$bulk_basic passes defaults", {
+  base_req <- httr2::request("https://api.omophub.com/v1")
+  resource <- SearchResource$new(base_req)
+
+  called_with <- NULL
+  local_mocked_bindings(
+    perform_post = function(req, path, body = NULL) {
+      called_with <<- list(path = path, body = body)
+      list(results = list(), total_searches = 1, completed_searches = 1, failed_searches = 0)
+    }
+  )
+
+  resource$bulk_basic(
+    list(list(search_id = "q1", query = "diabetes")),
+    defaults = list(vocabulary_ids = list("SNOMED"), page_size = 5)
+  )
+
+  expect_equal(called_with$body$defaults$vocabulary_ids, list("SNOMED"))
+  expect_equal(called_with$body$defaults$page_size, 5)
+})
+
+# ==============================================================================
+# bulk_semantic() method
+# ==============================================================================
+
+test_that("search$bulk_semantic validates searches", {
+  base_req <- httr2::request("https://api.omophub.com/v1")
+  resource <- SearchResource$new(base_req)
+
+  expect_error(resource$bulk_semantic(list()))  # Empty list
+  expect_error(resource$bulk_semantic(list(list(search_id = "", query = "test"))))  # Empty search_id
+  expect_error(resource$bulk_semantic(list(list(search_id = "s1", query = ""))))  # Empty query
+})
+
+test_that("search$bulk_semantic calls correct endpoint", {
+  base_req <- httr2::request("https://api.omophub.com/v1")
+  resource <- SearchResource$new(base_req)
+
+  called_with <- NULL
+  local_mocked_bindings(
+    perform_post = function(req, path, body = NULL) {
+      called_with <<- list(path = path, body = body)
+      list(results = list(), total_searches = 0, completed_count = 0, failed_count = 0)
+    }
+  )
+
+  resource$bulk_semantic(list(
+    list(search_id = "s1", query = "heart failure treatment")
+  ))
+
+  expect_equal(called_with$path, "search/semantic-bulk")
+  expect_length(called_with$body$searches, 1)
+  expect_equal(called_with$body$searches[[1]]$search_id, "s1")
+})
+
+test_that("search$bulk_semantic passes defaults", {
+  base_req <- httr2::request("https://api.omophub.com/v1")
+  resource <- SearchResource$new(base_req)
+
+  called_with <- NULL
+  local_mocked_bindings(
+    perform_post = function(req, path, body = NULL) {
+      called_with <<- list(path = path, body = body)
+      list(results = list(), total_searches = 1, completed_count = 1, failed_count = 0)
+    }
+  )
+
+  resource$bulk_semantic(
+    list(list(search_id = "s1", query = "diabetes medications")),
+    defaults = list(threshold = 0.8, page_size = 10)
+  )
+
+  expect_equal(called_with$body$defaults$threshold, 0.8)
+  expect_equal(called_with$body$defaults$page_size, 10)
+})
+
+test_that("SearchResource print includes bulk methods", {
+  base_req <- httr2::request("https://api.omophub.com/v1")
+  resource <- SearchResource$new(base_req)
+
+  expect_output(print(resource), "bulk_basic")
+  expect_output(print(resource), "bulk_semantic")
+})
