> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Search

> Perform OMOP concept search on multiple queries simultaneously with optimized batch processing - ideal for ETL pipelines and terminology mapping jobs.

## Overview

This endpoint allows you to submit multiple search queries in a single request, enabling efficient batch processing of search operations. It's ideal for applications that need to search for many terms simultaneously, such as data processing pipelines, bulk concept mapping, or batch validation workflows.

Each query uses full-text search with a default limit of 20 results per query (configurable via `page_size`, max 100). Up to 50 queries can be submitted per request.

> [!NOTE]
>
> For paginated results or semantic search, use the [Basic
> Search](https://docs.omophub.com/api-reference/search/basic-search.md) or [Semantic
> Search](https://docs.omophub.com/api-reference/search/semantic-search.md) endpoints instead.

## Request Body

**searches** `array` *required*

Array of search query objects (1-50 items)

**Search Object**

**search\_id** `string` *required*

Unique identifier for this search within the batch. NUL characters (U+0000)
are stripped before processing; results echo the normalized identifier.
The identifier must remain nonempty after normalization.

**query** `string` *required*

Search term or phrase (3-500 characters), or a configured whole-query
abbreviation: `COPD`, `CHF`, `MI`, `T2DM`, `HTN`, or `CKD`. Leading and
trailing whitespace is ignored. Other one- and two-character terms are
rejected.

**bulk\_mode** `boolean` (default: true)

Enable bulk-optimized search mode for better performance

**vocabulary\_ids** `string[] | string`

Filter results to specific vocabularies (e.g., `["SNOMED", "ICD10CM"]`). A
comma-separated string is also accepted for compatibility. In a mixed
list, inaccessible vocabularies are omitted; an all-inaccessible list
fails that search item. Overrides `defaults.vocabulary_ids`.

**domain\_ids** `string[] | string`

Filter results to specific domains (e.g., `["Condition", "Drug"]`). A
comma-separated string is also accepted for compatibility. Overrides
`defaults.domain_ids` for this search.

**concept\_class\_ids** `string[] | string`

Filter results to specific concept classes (e.g., `["Clinical Finding"]`).
A comma-separated string is also accepted for compatibility. Overrides
`defaults.concept_class_ids` for this search.

**standard\_concept** `string`

Filter by standard concept status: `"S"` (Standard) or `"C"`
(Classification). Overrides `defaults.standard_concept` for this search.

**include\_invalid** `boolean` (default: false)

Include invalid/deprecated concepts. Overrides `defaults.include_invalid`
for this search.

**page\_size** `integer` (default: 20)

Number of results per search (1-100). Overrides `defaults.page_size` for
this search.

**defaults** `object`

Default filter parameters applied to all searches. Individual searches can
override any default.

**Defaults Object**

**vocabulary\_ids** `string[] | string`

Default vocabulary filter for all searches (e.g., `["SNOMED"]`). A
comma-separated string is also accepted for compatibility.

**domain\_ids** `string[] | string`

Default domain filter for all searches (e.g., `["Condition"]`). A
comma-separated string is also accepted for compatibility.

**concept\_class\_ids** `string[] | string`

Default concept class filter for all searches. A comma-separated string is
also accepted for compatibility.

**standard\_concept** `string`

Default standard concept filter: `"S"` or `"C"`

**include\_invalid** `boolean` (default: false)

Default invalid concept inclusion

**page\_size** `integer` (default: 20)

Default results per search (1-100)

## Query Parameters

**vocab\_release** `string`

Specific vocabulary release version (defaults to latest)

## Response

**success** `boolean`

Indicates if the request was successful

**data** `array`

Array of search results, one per query

**Search Result**

**search\_id** `string`

Identifier matching the request's search\_id

**query** `string`

Original search query

**status** `string`

Query execution status: `completed` or `failed`

**results** `array`

Array of matching concepts

**Concept Result**

**concept\_id** `integer`

Unique concept identifier

**concept\_name** `string`

Primary concept name

**concept\_code** `string`

Concept code

**vocabulary\_id** `string`

Source vocabulary

**vocabulary\_name** `string`

Human-readable vocabulary name

**domain\_id** `string`

Domain classification

**concept\_class\_id** `string`

Concept class

**standard\_concept** `string`

Standard concept indicator

**valid\_start\_date** `string`

Concept validity start date

**valid\_end\_date** `string`

Concept validity end date

**invalid\_reason** `string | null`

Invalidity marker, or null for a valid concept

**search\_score** `number`

Normalized effective relevance score in `[0, 1)`. Each item uses the
same identifier, clinical-utility, and lexical-evidence policy as
basic and advanced lexical search.

**match\_type** `string`

Match category: `exact`, `partial`, `fuzzy`, or `semantic`

**error** `string`

Error message (if query failed)

**duration** `number`

Processing time for this query in milliseconds

## Ranking policy

Every valid item is ranked independently with the shared lexical policy. Exact
concept IDs and codes rank first. Text searches use non-overlapping clinical
utility and evidence bands, so a lower-tier exact name cannot accumulate enough
text bonuses to cross above a valid Standard clinical concept. Explicit
`vocabulary_ids`, `domain_ids`, `concept_class_ids`, `standard_concept`, and
`include_invalid` values remain hard filters. Naming a non-clinical class or
measurement-value domain suppresses that default demotion for the affected
item.

**meta** `object`

**Metadata**

**request\_id** `string`

Unique identifier for the request

**timestamp** `string`

Request timestamp

**vocab\_release** `string`

Vocabulary release version used

```bash cURL theme={null}
curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "standard_concept": "S"
    },
    "searches": [
      {
        "search_id": "s1",
        "query": "diabetes"
      },
      {
        "search_id": "s2",
        "query": "hypertension"
      },
      {
        "search_id": "s3",
        "query": "aspirin",
        "vocabulary_ids": ["RxNorm"],
        "domain_ids": ["Drug"]
      }
    ]
  }'
```

```ts TypeScript theme={null}
import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
// Per-search entries (BulkBasicSearchInput) use snake_case; outer
// `defaults` follows the same convention. See SDK Search docs.
const { data } = await client.search.bulkBasic(
  [
    { search_id: 's1', query: 'diabetes' },
    { search_id: 's2', query: 'hypertension' },
    {
      search_id: 's3',
      query: 'aspirin',
      vocabulary_ids: ['RxNorm'],
      domain_ids: ['Drug'],
    },
  ],
  { defaults: { vocabulary_ids: ['SNOMED'], standard_concept: 'S' } }
);
```

```python Python theme={null}
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

payload = {
    'defaults': {
        'vocabulary_ids': ['SNOMED'],
        'standard_concept': 'S'
    },
    'searches': [
        {
            'search_id': 's1',
            'query': 'diabetes'
        },
        {
            'search_id': 's2',
            'query': 'hypertension'
        },
        {
            'search_id': 's3',
            'query': 'aspirin',
            'vocabulary_ids': ['RxNorm'],
            'domain_ids': ['Drug']
        }
    ]
}

response = requests.post(
    'https://api.omophub.com/v1/search/bulk',
    headers=headers,
    json=payload
)

data = response.json()
```

```json Response theme={null}
{
  "success": true,
  "data": [
    {
      "search_id": "s1",
      "query": "diabetes",
      "status": "completed",
      "results": [
        {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED Clinical Terms",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "valid_start_date": "2002-01-31",
          "valid_end_date": "2099-12-31",
          "invalid_reason": null,
          "search_score": 0.843,
          "match_type": "exact"
        },
        {
          "concept_id": 4000678,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 0.786
        }
      ],
      "duration": 856
    },
    {
      "search_id": "s2",
      "query": "hypertension",
      "status": "completed",
      "results": [
        {
          "concept_id": 320128,
          "concept_name": "Essential hypertension",
          "concept_code": "59621000",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 0.843
        },
        {
          "concept_id": 316866,
          "concept_name": "Hypertensive disorder",
          "concept_code": "38341003",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 0.786
        }
      ],
      "duration": 1034
    },
    {
      "search_id": "s3",
      "query": "aspirin",
      "status": "completed",
      "results": [
        {
          "concept_id": 1112807,
          "concept_name": "Aspirin",
          "concept_code": "1191",
          "vocabulary_id": "RxNorm",
          "domain_id": "Drug",
          "concept_class_id": "Ingredient",
          "standard_concept": "S",
          "search_score": 0.843
        }
      ],
      "duration": 957
    }
  ],
  "meta": {
    "request_id": "req_bulk_search_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "vocab_release": "2025.2"
  }
}
```

## Usage Examples

### Basic Bulk Search

Search multiple terms simultaneously without filters:

```bash theme={null}
curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {"search_id": "s1", "query": "diabetes"},
      {"search_id": "s2", "query": "hypertension"},
      {"search_id": "s3", "query": "asthma"}
    ]
  }'
```

### Filtered Bulk Search with Defaults

Apply common filters to all searches using `defaults`, with per-search overrides:

```bash theme={null}
curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "domain_ids": ["Condition"],
      "standard_concept": "S"
    },
    "searches": [
      {"search_id": "s1", "query": "diabetes"},
      {"search_id": "s2", "query": "heart failure"},
      {"search_id": "s3", "query": "metformin", "vocabulary_ids": ["RxNorm"], "domain_ids": ["Drug"]}
    ]
  }'
```

In this example, searches s1 and s2 use the defaults (SNOMED, Condition domain, standard concepts only). Search s3 overrides with RxNorm vocabulary and Drug domain.

### Per-Search Filters

Apply different filters to each search individually:

```bash theme={null}
curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {"search_id": "s1", "query": "diabetes", "vocabulary_ids": ["SNOMED"], "domain_ids": ["Condition"]},
      {"search_id": "s2", "query": "metformin", "vocabulary_ids": ["RxNorm"], "domain_ids": ["Drug"]},
      {"search_id": "s3", "query": "HbA1c", "vocabulary_ids": ["LOINC"], "domain_ids": ["Measurement"]}
    ]
  }'
```

### High-Volume Processing

Process larger batches from a file:

```bash theme={null}
curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @bulk_queries.json
```

Example `bulk_queries.json`:

```json theme={null}
{
  "defaults": {
    "vocabulary_ids": ["SNOMED"],
    "standard_concept": "S"
  },
  "searches": [
    { "search_id": "q1", "query": "diabetes mellitus" },
    { "search_id": "q2", "query": "essential hypertension" },
    { "search_id": "q3", "query": "chronic kidney disease" },
    { "search_id": "q4", "query": "atrial fibrillation" },
    { "search_id": "q5", "query": "congestive heart failure" }
  ]
}
```

## Optimization Strategies

### Query Grouping

* **Batch Size**: Optimal batch size is 10-50 queries per request
* **Bulk Mode**: The `bulk_mode` parameter (default `true`) enables optimized query execution for better throughput
* **Result Limit**: Each query returns up to 20 results by default (configurable via `page_size`, max 100)

### Performance Tips

* Use concise, specific search terms for faster results
* Split very large query sets into multiple requests of 50 queries each
* Use the `search_id` field to correlate results with your source data
* Use `defaults` to apply common filters instead of repeating them per search
* Applying filters (vocabulary, domain) generally improves performance by narrowing the search space

### Error Handling

* Each query in the batch is processed independently
* Failed queries return `status: "failed"` with an `error` message
* Successful queries are not affected by failures in other queries

## Related Endpoints

* [Basic Search](https://docs.omophub.com/api-reference/search/basic-search.md) - Single query search with pagination
* [Advanced Search](https://docs.omophub.com/api-reference/search/advanced-search.md) - Complex search with advanced filters
* [Semantic Search](https://docs.omophub.com/api-reference/search/semantic-search.md) - AI-powered contextual search


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.