ontocast.link¶
Cross-document identity: link each document's entities, resolve them on read.
Document graphs are never changed. For each document, :func:links_for
derives a links graph (<graph>/identity-links) from the document and the
catalog's declarations alone: one skos:closeMatch link from an entity to
a match node per declared key value, inverse-functional value, caller
identifier, or normalised name of a globally named class. The resolution
graph is the union of these links graphs; :func:build,
:func:add_documents and :func:remove_documents keep it in step with the
documents. :func:cluster_of reads which entities are one, with vetoes.
Modules:
| Name | Description |
|---|---|
clusters |
Read-time clusters: which stored entities are one, from the resolution graph. |
declarations |
What the catalog declares about identity across documents. |
links |
The link pass: one document's facts graph to its identity links graph. |
resolution |
The resolution graph: every document's identity links, one named graph each. |
Attributes¶
__all__ = ['ClusterMember', 'EntityCluster', 'IdentityDeclarations', 'KeptApart', 'ResolutionReport', 'add_documents', 'build', 'cluster_of', 'document_graphs', 'identity_links_graph_uri', 'links_for', 'match_node_iri', 'remove_documents', 'write_document_links']
module-attribute
¶
Classes¶
ClusterMember
¶
Bases: BaseModel
One entity of a cluster.
Source code in ontocast/link/clusters.py
Attributes¶
graph = Field(description='The document graph that holds the entity.')
class-attribute
instance-attribute
¶
iri
instance-attribute
¶
labels = Field(default_factory=list)
class-attribute
instance-attribute
¶
reason = Field(description='`self` for the entity asked about, else the strongest kind of link it shares with the cluster (key, ifp, identifier, label).')
class-attribute
instance-attribute
¶
types = Field(default_factory=list)
class-attribute
instance-attribute
¶
via = Field(default_factory=list, description='Match nodes it shares with the cluster.')
class-attribute
instance-attribute
¶
EntityCluster
¶
Bases: BaseModel
The entities stored as one with iri, and the candidates kept apart.
Source code in ontocast/link/clusters.py
IdentityDeclarations
¶
Bases: BaseModel
The catalog's identity declarations, read once per catalog state.
Attributes:
| Name | Type | Description |
|---|---|---|
globally_named |
dict[str, bool]
|
Each class with |
parents |
dict[str, frozenset[str]]
|
Each class's |
keys |
dict[str, tuple[tuple[str, ...], ...]]
|
Each class's |
inverse_functional |
frozenset[str]
|
Properties declared |
functional |
frozenset[str]
|
Properties the catalog caps at one value
( |
disjoint |
frozenset[frozenset[str]]
|
Class pairs declared disjoint. |
catalog_terms |
frozenset[str]
|
Every IRI the catalog declares or references. |
Source code in ontocast/link/declarations.py
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 | |
Attributes¶
catalog_terms = frozenset()
class-attribute
instance-attribute
¶
declares_anything
property
¶
Whether any class or property can produce a link.
disjoint = frozenset()
class-attribute
instance-attribute
¶
functional = frozenset()
class-attribute
instance-attribute
¶
globally_named = Field(default_factory=dict)
class-attribute
instance-attribute
¶
inverse_functional = frozenset()
class-attribute
instance-attribute
¶
keys = Field(default_factory=dict)
class-attribute
instance-attribute
¶
model_config = ConfigDict(frozen=True)
class-attribute
instance-attribute
¶
parents = Field(default_factory=dict)
class-attribute
instance-attribute
¶
Methods:¶
ancestors(class_iri)
¶
class_iri and every class above it.
Source code in ontocast/link/declarations.py
are_disjoint(left_types, right_types)
¶
Whether some class of one typing is declared disjoint with one of the other.
Source code in ontocast/link/declarations.py
declaring_classes(types)
¶
The globally named classes an instance of types belongs to.
Walks up from each type and stops at the first class on each path that
states the annotation: true makes it a declaring class, false
stops the path.
Source code in ontocast/link/declarations.py
keys_for(types)
¶
Each (class, properties) key that applies to an instance of types.
Source code in ontocast/link/declarations.py
of(graphs)
classmethod
¶
The declarations stated across graphs.
Source code in ontocast/link/declarations.py
KeptApart
¶
Bases: BaseModel
A candidate that shares a match node with the cluster but is not in it.
Source code in ontocast/link/clusters.py
ResolutionReport
¶
Bases: BaseModel
What one operation on the resolution graph did.
Source code in ontocast/link/resolution.py
Attributes¶
documents = Field(default=0, description='Documents whose links were written.')
class-attribute
instance-attribute
¶
links = Field(default=0, description='Links written.')
class-attribute
instance-attribute
¶
removed = Field(default=0, description='Links graphs dropped.')
class-attribute
instance-attribute
¶
Functions:¶
add_documents(store, graph_uris, declarations, *, domain, value_classes=frozenset())
async
¶
Write the links graph of each document graph in graph_uris.
A document graph that is not stored has its links graph dropped.
Source code in ontocast/link/resolution.py
build(store, declarations, *, domain, value_classes=frozenset())
async
¶
Recompute the whole resolution graph from the stored document graphs.
Links graphs whose document graph is gone are dropped. Running it twice gives the same store.
Source code in ontocast/link/resolution.py
cluster_of(store, declarations, iri, *, max_candidates=DEFAULT_MAX_CANDIDATES)
async
¶
The cluster of the stored entity iri, or None when no document holds it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
store
|
TripleStoreManager
|
The triple store holding the documents and their links graphs. |
required |
declarations
|
IdentityDeclarations
|
The catalog's identity declarations. |
required |
iri
|
str
|
An entity of some document graph. |
required |
max_candidates
|
int
|
Stop collecting candidates beyond this many. |
DEFAULT_MAX_CANDIDATES
|
Source code in ontocast/link/clusters.py
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 | |
document_graphs(store)
async
¶
Every document graph in the facts partition, auxiliary graphs excluded.
Source code in ontocast/link/resolution.py
identity_links_graph_uri(graph_uri)
¶
links_for(graph, declarations, *, domain, value_classes=frozenset())
¶
The identity links of one document's facts graph.
Each entity gets one skos:closeMatch link per:
owl:hasKeythat applies to its types and whose properties all have key values (one link per combination of values);- value of an
owl:InverseFunctionalProperty; dcterms:identifieron an entity the document node links to (the caller's document metadata), scoped to each of its types;- normalised
rdfs:label/skos:altLabel, when one of its types is under a globally named class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
graph
|
RDFGraph
|
One document's facts graph, as written to the store. |
required |
declarations
|
IdentityDeclarations
|
The catalog's identity declarations. |
required |
domain
|
str
|
The deployment domain; match nodes are minted under it. |
required |
value_classes
|
frozenset[str]
|
Classes whose instances are values, never linked. |
frozenset()
|
Returns:
| Name | Type | Description |
|---|---|---|
RDFGraph |
RDFGraph
|
The links graph; empty when nothing is declared or matched. |
Source code in ontocast/link/links.py
match_node_iri(domain, payload)
¶
The match node for payload under domain: the same IRI everywhere.
Source code in ontocast/link/links.py
remove_documents(store, graph_uris)
async
¶
Drop the links graphs of the document graphs in graph_uris.
Source code in ontocast/link/resolution.py
write_document_links(store, graph_uri, links)
async
¶
Replace the links graph of the document graph_uri with links.