> ## 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.

# Batch Relationship Queries

> Run multiple OMOP concept relationship queries in a single batched request for efficient bulk processing of mappings and vocabulary crosswalks.

## Overview

This endpoint allows you to perform multiple relationship-related queries for multiple concepts in a single API call. It supports different operation types: `relationships`, `related`, and `traverse`.

## Request Body

<ParamField body="queries" type="array" required>
  Array of relationship query requests (1-100 queries)

  <Expandable title="queries">
    <ParamField body="query_id" type="string" required>
      Unique identifier for this query (used to match results)
    </ParamField>

    <ParamField body="concept_id" type="integer" required>
      The OMOP concept ID to query relationships for
    </ParamField>

    <ParamField body="operation" type="string" required>
      Type of relationship query. Options: `relationships`, `related`, `traverse`
    </ParamField>

    <ParamField body="params" type="object">
      Optional parameters for the query

      <Expandable title="params">
        <ParamField body="relationship_types" type="array">
          Array of relationship types to filter by (e.g., \["Maps to", "Is a"])
        </ParamField>

        <ParamField body="vocabulary_ids" type="array">
          Array of vocabulary IDs to filter related concepts
        </ParamField>

        <ParamField body="include_invalid" type="boolean" default="true">
          Include relationships to invalid/deprecated concepts
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Query Parameters

<ParamField query="vocab_release" type="string">
  Specific vocabulary release version (e.g., "2025.1")
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates whether the overall batch request was successful
</ResponseField>

<ResponseField name="data" type="array" required>
  Array of query results matching the input order

  <Expandable title="data">
    <ResponseField name="query_id" type="string">
      The query identifier from the request
    </ResponseField>

    <ResponseField name="concept_id" type="integer">
      The concept ID that was queried
    </ResponseField>

    <ResponseField name="operation" type="string">
      The operation that was performed
    </ResponseField>

    <ResponseField name="success" type="boolean">
      Whether this individual query succeeded
    </ResponseField>

    <ResponseField name="data" type="object">
      Result data if the query succeeded (structure varies by operation)
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message if the query failed
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object" required>
  Response metadata

  <Expandable title="meta">
    <ResponseField name="request_id" type="string">
      Unique request identifier
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="vocab_release" type="string">
      Vocabulary release version used
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.omophub.com/v1/concepts/relationships/batch" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "queries": [
        {
          "query_id": "diabetes_rels",
          "concept_id": 201826,
          "operation": "relationships",
          "params": {
            "relationship_types": ["Maps to", "Is a"]
          }
        },
        {
          "query_id": "hypertension_rels",
          "concept_id": 4182210,
          "operation": "relationships",
          "params": {
            "relationship_types": ["Maps to"],
            "vocabulary_ids": ["ICD10CM", "ICD9CM"]
          }
        },
        {
          "query_id": "afib_related",
          "concept_id": 313217,
          "operation": "related",
          "params": {
            "include_invalid": false
          }
        }
      ]
    }'
  ```

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

  def batch_relationship_query(queries, api_key):
      url = "https://api.omophub.com/v1/concepts/relationships/batch"
      headers = {
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json"
      }
      data = {"queries": queries}

      response = requests.post(url, json=data, headers=headers)
      return response.json()

  # Example: Batch query for cardiovascular conditions
  queries = [
      {
          "query_id": "diabetes",
          "concept_id": 201826,
          "operation": "relationships",
          "params": {
              "relationship_types": ["Maps to", "Is a"]
          }
      },
      {
          "query_id": "hypertension",
          "concept_id": 4182210,
          "operation": "relationships",
          "params": {
              "relationship_types": ["Maps to"],
              "vocabulary_ids": ["ICD10CM"]
          }
      },
      {
          "query_id": "afib",
          "concept_id": 313217,
          "operation": "related",
          "params": {}
      }
  ]

  result = batch_relationship_query(queries, "YOUR_API_KEY")

  for query_result in result['data']:
      if query_result['success']:
          print(f"{query_result['query_id']}: Success")
      else:
          print(f"{query_result['query_id']}: Error - {query_result['error']}")
  ```

  ```javascript JavaScript theme={null}
  const batchRelationshipQuery = async (queries) => {
    const response = await fetch('https://api.omophub.com/v1/concepts/relationships/batch', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ queries })
    });

    return response.json();
  };

  // Example usage
  const queries = [
    {
      query_id: 'q1',
      concept_id: 201826,
      operation: 'relationships',
      params: {
        relationship_types: ['Maps to', 'Is a']
      }
    },
    {
      query_id: 'q2',
      concept_id: 4182210,
      operation: 'relationships',
      params: {
        relationship_types: ['Maps to'],
        vocabulary_ids: ['ICD10CM']
      }
    },
    {
      query_id: 'q3',
      concept_id: 313217,
      operation: 'related',
      params: {}
    }
  ];

  const result = await batchRelationshipQuery(queries);

  result.data.forEach((queryResult) => {
    if (queryResult.success) {
      console.log(`${queryResult.query_id}: Success`);
    } else {
      console.error(`${queryResult.query_id} failed: ${queryResult.error}`);
    }
  });
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "query_id": "diabetes_rels",
        "concept_id": 201826,
        "operation": "relationships",
        "success": true,
        "data": {
          "relationships": [
            {
              "relationship_id": "Maps to",
              "concept_id_2": 44054006,
              "concept_name": "Diabetes mellitus type 2",
              "vocabulary_id": "SNOMED"
            },
            {
              "relationship_id": "Is a",
              "concept_id_2": 73211009,
              "concept_name": "Diabetes mellitus",
              "vocabulary_id": "SNOMED"
            }
          ]
        }
      },
      {
        "query_id": "hypertension_rels",
        "concept_id": 4182210,
        "operation": "relationships",
        "success": true,
        "data": {
          "relationships": [
            {
              "relationship_id": "Maps to",
              "concept_id_2": 312327,
              "concept_name": "Essential hypertension",
              "vocabulary_id": "ICD10CM"
            }
          ]
        }
      },
      {
        "query_id": "afib_related",
        "concept_id": 313217,
        "operation": "related",
        "success": true,
        "data": {
          "related_concepts": [
            {
              "concept_id": 49436004,
              "concept_name": "Atrial fibrillation and flutter",
              "vocabulary_id": "SNOMED"
            }
          ]
        }
      }
    ],
    "meta": {
      "request_id": "req_batch_relationships_123",
      "timestamp": "2024-12-22T10:00:00Z",
      "vocab_release": "2025.1"
    }
  }
  ```
</ResponseExample>

## Usage Examples

### Basic Batch Query

Get relationships for multiple concepts:

```json theme={null}
{
  "queries": [
    {"query_id": "q1", "concept_id": 201826, "operation": "relationships"},
    {"query_id": "q2", "concept_id": 4182210, "operation": "relationships"},
    {"query_id": "q3", "concept_id": 313217, "operation": "relationships"}
  ]
}
```

### Filtered by Relationship Type

Get only mapping relationships:

```json theme={null}
{
  "queries": [
    {
      "query_id": "diabetes_maps",
      "concept_id": 201826,
      "operation": "relationships",
      "params": {
        "relationship_types": ["Maps to"]
      }
    },
    {
      "query_id": "hypertension_maps",
      "concept_id": 4182210,
      "operation": "relationships",
      "params": {
        "relationship_types": ["Maps to"],
        "vocabulary_ids": ["ICD10CM"]
      }
    }
  ]
}
```

### Mixed Operations

Combine different operations in one batch:

```json theme={null}
{
  "queries": [
    {
      "query_id": "rels_query",
      "concept_id": 201826,
      "operation": "relationships",
      "params": {
        "relationship_types": ["Is a", "Subsumes"]
      }
    },
    {
      "query_id": "related_query",
      "concept_id": 4182210,
      "operation": "related",
      "params": {}
    },
    {
      "query_id": "traverse_query",
      "concept_id": 313217,
      "operation": "traverse",
      "params": {
        "relationship_types": ["Is a"]
      }
    }
  ]
}
```

## Important Notes

* **Batch size limit**: Maximum 100 queries per batch request
* **Performance optimization**: Batch processing is significantly more efficient than individual requests
* **Error isolation**: Individual query failures don't affect other queries in the batch
* **Result matching**: Use `query_id` to match results to your input queries
* **Rate limiting**: Batch requests count as single requests for rate limiting purposes

## Related Endpoints

* [Get Concept Relationships](/api-reference/concepts/get-concept-relationships) - Single concept relationships
* [Batch Hierarchy Queries](/api-reference/concepts/batch-hierarchy-queries) - Batch hierarchy queries
* [Traverse Relationships](/api-reference/concepts/traverse-relationships) - Complex relationship traversals