KnowledgeGraph

omop_graph.graph.kg

OMOP-backed graph facade.

This module provides the KnowledgeGraph class, which acts as the primary interface (facade) to the OMOP Common Data Model database.

Responsibilities

• SQLAlchemy Access: Manages the database session and executes queries.
• Caching: Implements LRU caching for high-frequency lookups (concepts, predicates).
• Predicate Semantics: Resolves relationship IDs to Predicate objects and Kinds.
• Edge/Node Retrieval: Provides methods to traverse the graph (parents, children, edges).

KnowledgeGraph

Bases: GraphBackend

The main entry point for interacting with the OMOP Graph.

This class wraps a SQLAlchemy session and provides high-level methods to query concepts, relationships, and metadata.

Parameters:

Name	Type	Description	Default
cdm_engine	Engine	The SQLAlchemy engine for the OMOP CDM database.	required

compute_missing_embeddings property

Indicates whether on-the-fly computation of missing concept embeddings is enabled.

emb property

Namespace for all embedding operations.

Returns an EmbeddingWriterInterface when self._emb_config.write is True, otherwise an EmbeddingReaderInterface (read-only).

The interface/reader is created lazily on first access, from the already-constructed backend supplied via KnowledgeGraphEmbeddingConfiguration.backend; omop-graph itself never resolves omop-emb's config.

embedding_configuration property

Returns the current embedding configuration, if set.

children(concept_id)

Retrieve children Concept IDs of concept using Concept_Ancestor table.

concept_id_by_code(vocabulary_id, concept_code)

Look up a Concept ID using the vocabulary ID and concept code.

Parameters:

Name	Type	Description	Default
vocabulary_id	str	The vocabulary ID (e.g., 'SNOMED', 'RxNorm').	required
concept_code	str	The source code within that vocabulary.	required

Returns:

Type	Description
int	The resolved OMOP Concept ID.

concept_ids_by_label(label)

Find concept IDs that match the label exactly (case-insensitive).

concept_lookup(query_term, match_kind, synonym=False, search_constraint=None, sort=True)

Resolve a query to concept_id(s).

Parameters:

Name	Type	Description	Default
query_term	str	The term to search for.	required
match_kind	LabelMatchKind	The kind of match to perform (exact, fulltext, partial).	required
synonym	bool	If True, searches in Concept_Synonym instead of Concept.	False
search_constraint	ConceptFilter	Additional filters for domain/vocabulary.	None

concept_view(concept_id)

Retrieve a single concept view by ID.

Parameters:

Name	Type	Description	Default
concept_id	int	The OMOP Concept ID.	required

Returns:

Type	Description
ConceptView	The immutable view of the concept.

concept_views(concept_ids, sort=True)

Retrieve multiple concept views in a batch.

Parameters:

Name	Type	Description	Default
concept_ids	tuple[int, ...]	A tuple of OMOP Concept IDs.	required

Returns:

Type	Description
tuple[ConceptView, ...]	A tuple of concept views.

edges(concept_ids, direction, predicate_ids=None, predicate_kinds=None, active_only=True, on=None, within_domain=True)

Convenience method to retrieve all edges from one or multiple concepts.

Parameters:

Name	Type	Description	Default
concept_ids	(int, tuple[int, ...])	The source/target concept ID(s).	required
direction	str	'out' for outgoing, 'in' for incoming.	required
predicate_ids	frozenset[str]	Filter by specific relationship IDs.	None
predicate_kinds	Set[PredicateKind]	Filter by semantic kind of relationship.	None
active_only	bool	If True, return only valid/active edges.	True
on	date	Check validity on a specific date.	None
within_domain	bool	If True, only return edges where source/target domains match.	True

get_num_ancestors(concept_ids)

Get the count of ancestors for a batch of concepts.

get_potential_ancestor(child_id, parent_id)

Check if an ancestry relationship exists between a child and parent.

get_potential_ancestors_batch(child_ids, parent_ids)

Check which candidate parents are ancestors of one or more children.

Parameters:

Name	Type	Description	Default
child_ids	tuple of int	A tuple of descendant concept IDs for batch mode.	required
parent_ids	tuple of int	Candidate ancestor concept IDs to check.	required

Returns:

Type	Description
Dict[int, Dict[int, AncestorMatch]]	When child_id is tuple: maps child_id -> {ancestor_concept_id -> AncestorMatch}.

leaves(domain_id=None, vocabulary_id=None)

Retrieve leaf concepts (no children).

parents(concept_id)

Retrieve parent Concept IDs of concept using Concept_Ancestor table.

predicate(relationship_id)

Retrieve a Predicate object by its relationship ID.

Parameters:

Name	Type	Description	Default
relationship_id	str	The OMOP relationship ID (e.g., 'maps to').	required

Returns:

Type	Description
Predicate	The predicate definition.

predicate_kind(relationship_id)

Classify the predicate into a semantic kind.

predicate_kinds(relationship_ids)

Classify a batch of predicates.

predicate_name(relationship_id)

Retrieve the human-readable name of a relationship.

predicates()

Return all predicates known to the knowledge graph.

relationships(session, subjects, predicates, objects, invert=False)

Query relationships between concepts.

Parameters:

Name	Type	Description	Default
subjects	list[CURIE] | None	List of subject CURIEs.	required
predicates	list[str] | None	List of predicate (relationship) IDs.	required
objects	list[CURIE] | None	List of object CURIEs.	required
invert	bool	If True, swaps subjects and objects in the query and result.	False

Yields:

Type	Description
Tuple[int, str, int]	Triples of (subject_concept_id, relationship_id, object_concept_id). When invert=True, the triple is (object_concept_id, relationship_id, subject_concept_id).

reverse_predicate_id(relationship_id)

Get the reverse relationship ID, if it exists.

roots(domain_id=None, vocabulary_id=None)

Retrieve root concepts (no parents).

singletons(domain_id=None, vocabulary_id=None)

Retrieve singleton concepts (no parents and no children).

specificity(concept_id)

Compute specificity as the inverse of out-degree. Higher is more specific.

synonyms_for_concept(concept_id)

Retrieve all synonyms for a concept.

KnowledgeGraphEmbeddingConfiguration dataclass

Configuration for embedding-based operations in the knowledge graph.

A complete configuration: whenever embedding support is used at all (read or write), a real backend and a real resolved model are both required. The caller resolves the vector store and the model, builds the backend, and passes both in here. Used to enhance the knowledge graph with embedding-based grounding and similarity scoring.

Parameters:

Name	Type	Description	Default
metric_type	EmbeddingMetricType	The similarity/distance metric to use for embedding comparisons (e.g., cosine, euclidean). This is required to ensure that the correct type of index is used in the backend and that similarity computations are consistent.	required
backend	EmbeddingBackend	An already-constructed embedding backend, e.g. via omop_emb.backends.resolve_backend_from_resolved.	required
resolved_model	ResolvedModel	A model resolved via oa_configurator.Resolver.resolve_model(), carrying real provider connection details. model_name/provider_type (see below) are read directly off it; used to build the embedding model backend via omop_llm.build_model_backend_from_resolved when write=True.	required
write	bool	If True, the KG holds a write-capable interface that can generate and persist embeddings. If False (default), the KG only holds a read-only interface over already-computed embeddings.	False
compute_missing_embeddings	bool	If True, the system will compute embeddings on-the-fly for any concept that is not yet present in the embedding store. Requires write=True as it needs a write-capable interface. Default: False	False
faiss_cache_dir	str	Directory to cache FAISS index files, for the read-only path only. Passed straight through to EmbeddingReaderInterface.	None

model_name property

The model name to use, read directly off resolved_model.

provider_type property

The provider key to use, read directly off resolved_model.