Searching OMOP concepts

Basic Search

Search for concepts by text:

results <- client$search$basic("diabetes mellitus", page_size = 20)
for (concept in results$data) {
  cat(sprintf("%s: %s\n", concept$concept_id, concept$concept_name))
}

Parameters

Parameter	Type	Default	Description
`query`	character	required	Search query string
`vocabulary_ids`	character	NULL	Filter by vocabulary IDs
`domain_ids`	character	NULL	Filter by domain IDs
`concept_class_ids`	character	NULL	Filter by concept class IDs
`standard_concept`	character	NULL	Filter by standard concept (“S”, “C”, or NULL)
`include_synonyms`	logical	FALSE	Search in synonyms
`include_invalid`	logical	TRUE	Include invalid concepts
`min_score`	numeric	NULL	Minimum relevance score (0.0-1.0)
`exact_match`	logical	FALSE	Require exact match
`page`	integer	1	Page number (1-based)
`page_size`	integer	20	Results per page
`sort_by`	character	NULL	Sort field
`sort_order`	character	NULL	Sort order (“asc” or “desc”)

Filter by Vocabulary

Restrict search to specific vocabularies:

results <- client$search$basic(
  "heart attack",
  vocabulary_ids = "SNOMED"
)

# Multiple vocabularies
results <- client$search$basic(
  "heart attack",
  vocabulary_ids = c("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 = c("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:

result <- client$search$autocomplete("diab", page_size = 10)
for (suggestion in result$suggestions) {
  print(suggestion$suggestion)
}

# With vocabulary and domain filters
result <- client$search$autocomplete(
  "diab",
  vocabulary_ids = c("SNOMED"),
  domains = c("Condition"),
  page_size = 10
)

Pagination

Manual Pagination

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

# Access pagination metadata
pagination <- results$meta
cat(sprintf("Total: %d\n", pagination$total_items))
cat(sprintf("Pages: %d\n", pagination$total_pages))
cat(sprintf("Has next: %s\n", pagination$has_next))

# Get next page
if (isTRUE(pagination$has_next)) {
  results <- client$search$basic("diabetes", page = 2, page_size = 50)
}

Auto-Pagination with basic_all()

Fetch all results automatically and return as a tibble:

# Fetch up to 5 pages of results
all_results <- client$search$basic_all(
  "diabetes",
  page_size = 100,
  max_pages = 5,
  progress = TRUE  # Show progress bar
)

# Results are returned as a tibble
print(nrow(all_results))
print(names(all_results))

# Use with dplyr
library(dplyr)
all_results %>%
  filter(vocabulary_id == "SNOMED") %>%
  select(concept_id, concept_name, domain_id)

The basic_all() method returns a tibble, making it easy to integrate with tidyverse workflows.

Advanced Search

Use advanced search with additional filtering options and facets:

results <- client$search$advanced(
  "diabetes",
  vocabulary_ids = c("SNOMED", "ICD10CM"),
  domain_ids = "Condition",
  standard_concepts_only = TRUE,
  page_size = 50
)

# Access results
for (concept in results$data) {
  cat(sprintf("%s: %s\n", concept$concept_id, concept$concept_name))
}

# Access pagination
cat(sprintf("Total: %d\n", results$meta$pagination$total_items))

Advanced Search Parameters

Parameter	Type	Default	Description
`query`	character	required	Search query string
`vocabulary_ids`	character	NULL	Filter by vocabulary IDs
`domain_ids`	character	NULL	Filter by domain IDs
`concept_class_ids`	character	NULL	Filter by concept class IDs
`standard_concepts_only`	logical	FALSE	Only return standard concepts
`include_invalid`	logical	TRUE	Include invalid concepts
`relationship_filters`	list	NULL	Relationship-based filters
`page`	integer	1	Page number (1-based)
`page_size`	integer	20	Results per page

Relationship Filters

Apply relationship-based filtering:

results <- client$search$advanced(
  "diabetes",
  relationship_filters = list(
    list(relationship_id = "Is a", concept_id = 4116142)  # Has parent concept
  ),
  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) {
  cat(sprintf("%s: %.2f\n", concept$concept_name, concept$similarity_score))
}

Semantic Search Parameters

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

Auto-Pagination with semantic_all()

Fetch all semantic search results automatically and return as a tibble:

# Fetch all results as tibble
all_results <- client$search$semantic_all(
  "diabetes",
  page_size = 100,
  max_pages = 5,
  progress = TRUE
)

# Returns tibble with concept_id, similarity_score, etc.
print(all_results)

# Use with dplyr
library(dplyr)
all_results %>%
  filter(similarity_score > 0.6) %>%
  select(concept_id, concept_name, similarity_score)

# With filters
all_results <- client$search$semantic_all(
  "heart failure",
  vocabulary_ids = "SNOMED",
  threshold = 0.4,
  page_size = 50
)

The semantic_all() method returns a tibble, making it easy to integrate with tidyverse workflows.

Bulk Lexical Search

Search for multiple queries in a single API call (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 (%s)\n", item$search_id, length(item$results), item$status))
}

Bulk Search Parameters

Parameter	Type	Description
`searches`	list	List of search inputs (max 50)
`searches[[i]]$search_id`	character	Unique ID to match results
`searches[[i]]$query`	character	Search query
`searches[[i]]$vocabulary_ids`	list	Per-search vocabulary filter
`defaults`	list	Shared defaults for all searches

Bulk Semantic Search

Search for multiple natural-language queries using neural embeddings (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))

for (item in results$results) {
  cat(sprintf("%s: %d results\n", item$search_id, item$result_count))
}

Bulk Semantic Parameters

Parameter	Type	Description
`searches`	list	List of search inputs (max 25)
`searches[[i]]$search_id`	character	Unique ID to match results
`searches[[i]]$query`	character	Natural language query (1-500 chars)
`searches[[i]]$threshold`	numeric	Per-search similarity threshold (0-1)
`defaults`	list	Shared defaults for all searches

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_size = 50,
  vocabulary_ids = "SNOMED",
  domain_ids = "Condition",
  include_scores = TRUE,
  include_explanations = TRUE
)

# Access results
for (concept in similar$similar_concepts) {
  cat(sprintf("%s: %.2f\n", concept$concept_name, concept$similarity_score))
}

Similar Concepts Parameters

Parameter	Type	Default	Description
`concept_id`	integer	NULL	Source concept ID
`concept_name`	character	NULL	Source concept name
`query`	character	NULL	Natural language query
`algorithm`	character	”hybrid"	"semantic”, “lexical”, or “hybrid”
`similarity_threshold`	numeric	0.7	Minimum similarity (0.0-1.0)
`page_size`	integer	20	Max results (max 1000)
`vocabulary_ids`	character	NULL	Filter by vocabulary
`domain_ids`	character	NULL	Filter by domain
`standard_concept`	character	NULL	”S”, “C”, or “N”
`include_invalid`	logical	NULL	Include invalid/deprecated concepts
`include_scores`	logical	NULL	Include detailed scores
`include_explanations`	logical	NULL	Include similarity explanations

Algorithm Comparison

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

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

Bulk Lexical Search

Bulk Search Parameters

Bulk Semantic Search

Bulk Semantic Parameters

Find Similar Concepts

Similar Concepts Parameters

Algorithm Comparison

​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 with basic_all()

​Advanced Search

​Advanced Search Parameters

​Relationship Filters

​Semantic Search

​Semantic Search Parameters

​Auto-Pagination with semantic_all()

​Bulk Lexical Search

​Bulk Search Parameters

​Bulk Semantic Search

​Bulk Semantic Parameters

​Find Similar Concepts

​Similar Concepts Parameters

​Algorithm Comparison

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 with basic_all()

Advanced Search

Advanced Search Parameters

Relationship Filters

Semantic Search

Semantic Search Parameters

Auto-Pagination with semantic_all()

Bulk Lexical Search

Bulk Search Parameters

Bulk Semantic Search

Bulk Semantic Parameters

Find Similar Concepts

Similar Concepts Parameters

Algorithm Comparison