Searching OMOP concepts

Basic Search

Search for concepts by text:

results = client.search.basic("diabetes mellitus", page_size=20)
for concept in results["concepts"]:
    print(f"{concept['concept_id']}: {concept['concept_name']}")

Parameters

Parameter	Type	Default	Description
`query`	string	required	Search query string (3-500 characters)
`vocabulary_ids`	list[str]	None	Filter by vocabulary IDs
`domain_ids`	list[str]	None	Filter by domain IDs
`concept_class_ids`	list[str]	None	Filter by concept class IDs
`standard_concept`	string	None	Filter by standard concept (“S”, “C”, or None)
`include_synonyms`	bool	False	Search in synonyms
`include_invalid`	bool	True	Include invalid concepts
`min_score`	float	None	Minimum relevance score (0.0-1.0)
`exact_match`	bool	False	Require exact match
`page`	int	1	Page number (1-based)
`page_size`	int	20	Results per page
`sort_by`	string	None	Sort field
`sort_order`	string	None	Sort order (“asc” or “desc”)

Filter by Vocabulary

Restrict search to specific vocabularies:

results = client.search.basic(
    "heart attack",
    vocabulary_ids=["SNOMED", "ICD10CM"],
)

Filter by Domain

Search within specific domains:

results = client.search.basic(
    "aspirin",
    domain_ids=["Drug"],
    page_size=10,
)

Filter by Concept Class

Search for specific concept classes:

results = client.search.basic(
    "aspirin",
    concept_class_ids=["Clinical Drug", "Ingredient"],
    page_size=10,
)

Standard Concepts Only

Filter to standard concepts:

results = client.search.basic(
    "diabetes",
    standard_concept="S",  # "S" = Standard, "C" = Classification
    vocabulary_ids=["SNOMED"],
)

Search with Synonyms

Include concept synonyms in search:

results = client.search.basic(
    "heart attack",
    include_synonyms=True,
    vocabulary_ids=["SNOMED"],
)

Combined Filters

results = client.search.basic(
    "myocardial infarction",
    vocabulary_ids=["SNOMED"],
    domain_ids=["Condition"],
    standard_concept="S",
    include_synonyms=True,
    min_score=0.5,
    page_size=20,
)

Autocomplete

Get suggestions as the user types: autocomplete() returns the list of suggestions directly - it reads suggestions out of the response envelope for you, so there is no ["suggestions"] key left to index. Each compact suggestion contains the matched suggestion, its type, and the number of matching concepts.

suggestions = client.search.autocomplete(
    "diab",
    page_size=10,
    vocabulary_ids=["SNOMED"],
    domain_ids=["Condition"],
)
for suggestion in suggestions:
    print(suggestion["suggestion"])  # "Type 2 diabetes mellitus"
    print(suggestion["type"], suggestion["count"])  # "concept_name", 12

Autocomplete returns grouped typeahead values, not concept records. Use basic search when you need concept IDs and other concept metadata.

Pagination

Manual Pagination

# Get first page
results = client.search.basic("diabetes", page=1, page_size=50)

# Access pagination metadata
pagination = results["meta"]["pagination"]
print(f"Total: {pagination['total_items']}")
print(f"Pages: {pagination['total_pages']}")
print(f"Has next: {pagination['has_next']}")

# Get next page
if pagination["has_next"]:
    results = client.search.basic("diabetes", page=2, page_size=50)

Auto-Pagination Iterator

Iterate through all results automatically:

count = 0
for concept in client.search.basic_iter("diabetes", page_size=100):
    print(concept["concept_name"])
    count += 1
    if count >= 500:  # Limit for demo
        break

Advanced Search

Use advanced search with additional filtering options and facets:

results = client.search.advanced(
    "diabetes",
    vocabulary_ids=["SNOMED", "ICD10CM"],
    domain_ids=["Condition"],
    standard_concepts_only=True,
    page_size=50,
)

# Access results
for concept in results["data"]:
    print(f"{concept['concept_id']}: {concept['concept_name']}")

# Access pagination
print(f"Total: {results['meta']['pagination']['total_items']}")

Advanced Search Parameters

Parameter	Type	Default	Description
`query`	string	required	Search query string
`vocabulary_ids`	list[str]	None	Filter by vocabulary IDs
`domain_ids`	list[str]	None	Filter by domain IDs
`concept_class_ids`	list[str]	None	Filter by concept class IDs
`standard_concepts_only`	bool	False	Only return standard concepts
`include_invalid`	bool	True	Include invalid concepts
`relationship_filters`	list[dict]	None	Relationship-based filters
`page`	int	1	Page number (1-based)
`page_size`	int	20	Results per page

Relationship Filters

Apply relationship-based filtering:

results = client.search.advanced(
    "diabetes",
    relationship_filters=[
        {
            "relationship_id": "Is a",
            "target_concept_id": 201820,
            "direction": "forward",
        }
    ],
    standard_concepts_only=True,
)

Semantic Search

Search for concepts using natural language with neural embeddings. Semantic search understands meaning, not just keywords.

# Basic semantic search
results = client.search.semantic("heart attack", page_size=10)

# With filters
results = client.search.semantic(
    "diabetes mellitus",
    vocabulary_ids=["SNOMED"],
    domain_ids=["Condition"],
    threshold=0.5,  # Higher = more similar
    page_size=20,
)

# Access results with similarity scores
for concept in results["data"]["results"]:
    print(f"{concept['concept_name']}: {concept['similarity_score']:.2f}")

Semantic Search Parameters

Parameter	Type	Default	Description
`query`	string	required	Natural language search query
`vocabulary_ids`	list[str]	None	Filter by vocabulary IDs
`domain_ids`	list[str]	None	Filter by domain IDs
`standard_concept`	”S” \| “C”	None	Filter by standard concept flag
`concept_class_id`	string	None	Filter by concept class
`threshold`	float	0.5	Minimum similarity (0.0-1.0)
`page`	int	1	Page number
`page_size`	int	20	Results per page (max 100)

Semantic Search Iterator

Iterate through all semantic search results with automatic pagination:

# Iterate through all results
for concept in client.search.semantic_iter("diabetes", page_size=50):
    print(concept["concept_name"])

# Collect first N results
import itertools
top_100 = list(itertools.islice(
    client.search.semantic_iter("diabetes"), 100
))

# With filters
for concept in client.search.semantic_iter(
    "heart failure",
    vocabulary_ids=["SNOMED"],
    threshold=0.4,
):
    print(f"{concept['concept_id']}: {concept['concept_name']}")

Async Semantic Search

# Async semantic search
results = await client.search.semantic("heart attack", page_size=10)

# Async iterator
async for concept in client.search.semantic_iter("diabetes"):
    print(concept["concept_name"])

Bulk Lexical Search

Search for multiple queries in a single API call (up to 50 queries). Much more efficient than individual calls when you have many terms to look up.

results = client.search.bulk_basic([
    {"search_id": "q1", "query": "diabetes mellitus"},
    {"search_id": "q2", "query": "hypertension"},
    {"search_id": "q3", "query": "aspirin"},
], defaults={"vocabulary_ids": ["SNOMED"], "page_size": 5})

for item in results["results"]:
    print(f"{item['search_id']}: {len(item['results'])} results ({item['status']})")

Bulk Search Parameters

Parameter	Type	Description
`searches`	list	List of search inputs (max 50)
`searches[].search_id`	string	Unique ID to match results
`searches[].query`	string	Search query
`searches[].vocabulary_ids`	list[str]	Per-search vocabulary filter
`searches[].domain_ids`	list[str]	Per-search domain filter
`searches[].page_size`	int	Per-search result limit (1-100)
`defaults`	dict	Shared defaults for all searches

With Shared Defaults

# Defaults apply to all searches; per-search values override
results = client.search.bulk_basic(
    [
        {"search_id": "q1", "query": "diabetes"},
        {"search_id": "q2", "query": "heart failure"},
        {"search_id": "q3", "query": "metformin", "domain_ids": ["Drug"]},  # overrides default
    ],
    defaults={
        "vocabulary_ids": ["SNOMED"],
        "domain_ids": ["Condition"],
        "page_size": 10,
    },
)

Bulk Semantic Search

Search for multiple natural-language queries using neural embeddings in a single call (up to 25 queries).

results = client.search.bulk_semantic([
    {"search_id": "s1", "query": "heart failure treatment options"},
    {"search_id": "s2", "query": "type 2 diabetes medication"},
    {"search_id": "s3", "query": "elevated blood pressure"},
], defaults={"threshold": 0.5, "page_size": 10})

for item in results["results"]:
    print(f"{item['search_id']}: {item.get('result_count', 0)} results")
    for concept in item["results"]:
        print(f"  {concept['concept_name']} ({concept['similarity_score']:.2f})")

Bulk Semantic Parameters

Parameter	Type	Description
`searches`	list	List of search inputs (max 25)
`searches[].search_id`	string	Unique ID to match results
`searches[].query`	string	Natural language query (1-500 chars)
`searches[].threshold`	float	Per-search similarity threshold (0-1)
`searches[].page_size`	int	Per-search result limit (1-50)
`searches[].vocabulary_ids`	list[str]	Per-search vocabulary filter
`defaults`	dict	Shared defaults for all searches

Async Bulk Search

# Both bulk methods have async variants
results = await client.search.bulk_basic([...])
results = await client.search.bulk_semantic([...])

Find Similar Concepts

Find concepts similar to a reference concept or query. Provide exactly one of: concept_id, concept_name, or query.

# By concept ID
similar = client.search.similar(concept_id=4329847)  # MI

# By concept name
similar = client.search.similar(concept_name="Type 2 diabetes mellitus")

# By natural language query
similar = client.search.similar(query="elevated blood sugar")

# With all options
similar = client.search.similar(
    concept_id=4329847,
    algorithm="semantic",  # or "lexical", "hybrid"
    similarity_threshold=0.7,
    page=1,
    page_size=50,
    vocabulary_ids=["SNOMED"],
    domain_ids=["Condition"],
    concept_class_ids=["Clinical Finding"],
    standard_concept="S",
    include_scores=True,
    include_explanations=True,
    exclude_self=True,
)

# Access results
for concept in similar["similar_concepts"]:
    print(f"{concept['concept_name']}: {concept['similarity_score']:.2f}")

Similar Concepts Parameters

Parameter	Type	Default	Description
`concept_id`	int	None	Source concept ID
`concept_name`	string	None	Source concept name
`query`	string	None	Natural language query
`algorithm`	string	”semantic"	"semantic”, “lexical”, or “hybrid”
`similarity_threshold`	float	0.7	Minimum similarity (0.0-1.0). `0` is valid and honoured
`page`	int	1	Page of the ranked candidate pool (1-based)
`page_size`	int	20	Results per page (max 1000)
`vocabulary_ids`	list[str]	None	Filter by vocabulary
`domain_ids`	list[str]	None	Filter by domain
`concept_class_ids`	list[str]	None	Filter by concept class
`standard_concept`	string	None	”S”, “C”, or “N” (`N` selects non-standard concepts)
`include_invalid`	bool	None	Include invalid/deprecated concepts. `lexical` only
`include_scores`	bool	None	Include `similarity_score` (default true at the API)
`include_explanations`	bool	None	Include an `explanation` per concept (default false)
`exclude_self`	bool	None	Exclude the reference concept from its own results

include_invalid=True is supported only with algorithm="lexical". The embedding index contains valid concepts only, so combining it with semantic or hybrid returns a 400 naming the combination rather than silently ignoring the filter.

Pagination

similar() returns a pagination key alongside similar_concepts and search_metadata:

similar = client.search.similar(concept_id=4329847, page=1, page_size=20)

page = similar["pagination"]
print(f"Page {page['page']} of {page['total_pages']}")

# Page while `has_next` is true, rather than comparing page to total_pages.
concepts = []
page_number = 1
while True:
    result = client.search.similar(
        concept_id=4329847, page=page_number, page_size=20
    )
    concepts.extend(result["similar_concepts"])
    if not result.get("pagination", {}).get("has_next"):
        break
    page_number += 1

total_candidates counts the concepts that cleared similarity_threshold inside a bounded candidate pool — not the concepts evaluated. It and the pagination totals may therefore be lower bounds — similar["search_metadata"]["totals_are_lower_bound"] says when. Reachable depth is bounded at roughly 500 / page_size pages — the pool is a constant 500 candidates, so a score never changes with page_size; a page past the end returns an empty list with has_next: False, not an error.

Result Fields

Field	Description
`similar_concepts`	Ranked concepts. `similarity_score` is absent if `include_scores=False`
`search_metadata.algorithm_used`	The algorithm that actually ran
`search_metadata.degraded_from`	Present when a fallback ran instead of what was asked for
`search_metadata.totals_are_lower_bound`	`True` when retrieval hit its candidate bound
`source_concept`	The reference concept, when the search started from a `concept_id`
`pagination`	Page position and `has_next`

Algorithm Comparison

Algorithm	Best For	Speed
`semantic`	Meaning-based similarity	Slower
`lexical`	Text/string similarity	Faster
`hybrid`	Balanced approach	Medium

hybrid fuses both signals as 0.7 x semantic + 0.3 x lexical. Every candidate is scored by that rule, with a signal neither retrieval established counting as 0. So a concept sharing no words with the query keeps only 0.7 x its semantic score, and one the embedding search did not return keeps only 0.3 x its lexical score — capping it at 0.3. Hybrid scores sit on a different scale from both semantic and lexical scores, and the same similarity_threshold is stricter than in either. Lower the threshold for hybrid, use semantic for conceptual matches that share no vocabulary, or use lexical for exact name and code matches: hybrid is not a superset of the other two. If the embedding service is unavailable it serves its lexical half and reports algorithm_used: "lexical" with degraded_from: "hybrid" rather than failing.

Async Similar Concepts

# Async version
similar = await client.search.similar(concept_id=4329847)

Python SDK

Node.js / TypeScript SDK

R SDK

Basic Search

Parameters

Filter by Vocabulary

Filter by Domain

Filter by Concept Class

Standard Concepts Only

Search with Synonyms

Combined Filters

Autocomplete

Advanced Search

Advanced Search Parameters

Relationship Filters

Semantic Search

Semantic Search Parameters

Semantic Search Iterator

Async Semantic Search

Bulk Lexical Search

Bulk Search Parameters

With Shared Defaults

Bulk Semantic Search

Bulk Semantic Parameters

Async Bulk Search

Find Similar Concepts

Similar Concepts Parameters

Result Fields

Algorithm Comparison

Async Similar Concepts

​Basic Search

​Parameters

​Filter by Vocabulary

​Filter by Domain

​Filter by Concept Class

​Standard Concepts Only

​Search with Synonyms

​Combined Filters

​Autocomplete

​Pagination

​Manual Pagination

​Auto-Pagination Iterator

​Advanced Search

​Advanced Search Parameters

​Relationship Filters

​Semantic Search

​Semantic Search Parameters

​Semantic Search Iterator

​Async Semantic Search

​Bulk Lexical Search

​Bulk Search Parameters

​With Shared Defaults

​Bulk Semantic Search

​Bulk Semantic Parameters

​Async Bulk Search

​Find Similar Concepts

​Similar Concepts Parameters

​Pagination

​Result Fields

​Algorithm Comparison

​Async Similar Concepts

Basic Search

Parameters

Filter by Vocabulary

Filter by Domain

Filter by Concept Class

Standard Concepts Only

Search with Synonyms

Combined Filters

Autocomplete

Pagination

Manual Pagination

Auto-Pagination Iterator

Advanced Search

Advanced Search Parameters

Relationship Filters

Semantic Search

Semantic Search Parameters

Semantic Search Iterator

Async Semantic Search

Bulk Lexical Search

Bulk Search Parameters

With Shared Defaults

Bulk Semantic Search

Bulk Semantic Parameters

Async Bulk Search

Find Similar Concepts

Similar Concepts Parameters

Pagination

Result Fields

Algorithm Comparison

Async Similar Concepts