Retrieve facts as of a time and preserve how they were known
How to study this lesson
Read one section, trace the worked example, and try the knowledge check. Bookmark saves a shortcut; notes appear in My notebook. Mark lesson complete is your own assessment and does not mark its lab passed.
By the end, you can
- Separate valid time from recording time.
- Carry provenance through extraction and summarization.
- Construct temporal evidence paths without mixing incompatible versions.
A fact can have two relevant clocks
Valid time describes when a fact applies in the world being modeled. Recording time describes when the system learned or stored it. These clocks answer different questions. Who owned checkout on Tuesday? concerns valid time. What owner could the system have known on Tuesday? also constrains recording time. A late-arriving correction can change the best current reconstruction of Tuesday without changing what the system knew then.
Represent validity with an interval and document its endpoints. This module uses half-open intervals: valid_from is included, valid_to is excluded, and no end means continuing validity. Store recorded_at independently. Use explicit timestamps in UTC or an agreed domain time scale, and preserve the original source time zone when interpreting human documents. A date with no timezone is not automatically a precise global instant.
A worked ownership history
Team red owns a service from time one until time five. Team blue owns it starting at time five, but that update is recorded at time six. Asking at valid time five with knowledge cutoff five returns no known active owner in the fixture. Asking the same valid-time question with cutoff six returns team blue. This is not a contradiction; the questions have different knowledge boundaries.
The code implements exactly that distinction. It assumes the supplied intervals are authoritative and nonconflicting. A real system may receive overlapping owner claims from different sources. Do not silently choose whichever row happens to be last in a database result. Define authority, correction, and conflict rules, or return the disagreement with its sources. Temporal filtering narrows relevant claims but does not resolve every conflict among them.
Provenance describes a derivation
W3C PROV-O models relationships among entities, activities, and agents involved in producing information. In an agent application, a source document is an entity, extraction is an activity, and the configured process or organization responsible for that activity is an agent in the provenance sense. This vocabulary helps express how a graph edge or summary was produced without confusing the producing software with the subject of the extracted claim.
For each extracted edge, retain document revision, passage location, extraction method version, recording time, and source IDs. A content hash can help detect changed source bytes, but it does not prove accuracy or authority. If a human corrects an edge, preserve the correction as a new provenance event. The goal is to reconstruct the evidence path and transformation history when an answer is challenged or a source changes.
A path must be coherent at the requested time
Suppose service A depended on library Q only before time five, while team red owned A only after time five. Joining both edges without temporal filtering can produce a path suggesting team red owned a service while it depended on Q, even though those conditions never overlapped. Filter every edge at the query time before traversal, or compute interval intersections when the question asks whether a relationship ever held.
The lab takes a simpler as-of query: first retain edges valid at a chosen time and known by a chosen cutoff, then find a shortest evidence path within a hop limit. Each returned hop includes its evidence reference. The path supports a relational explanation only under the stated edge meanings. It does not establish causation, and it cannot justify a current answer if the selected time is historical.
Time-aware indexing needs reproducible snapshots
Record corpus, parser, extractor, ontology, and index versions for an evaluation run. If source documents change during evaluation, a retrieval regression may actually be a corpus change. Freeze a snapshot or log the exact revisions used for each query. Keep current retrieval and historical reconstruction as explicit modes so the system does not mix them accidentally.
Add tests at valid_from, just before valid_to, exactly valid_to, and before recorded_at. Include an edge discovered late and a superseded claim that remains useful for history. A production graph may need more sophisticated bitemporal correction semantics than the fixture supplies. The important engineering habit is to state which time question the system answers and preserve enough provenance to reproduce that answer later, rather than attaching a single ambiguous timestamp to every fact.
Work through the code
Two authoritative fixture records separate world validity from knowledge arrival. The exact endpoint at time five excludes red, and blue becomes knowable at time six. This simulates temporal filtering, not a complete bitemporal database or conflict-resolution system.
facts = [
{"owner": "red", "valid_from": 1, "valid_to": 5, "recorded_at": 1},
{"owner": "blue", "valid_from": 5, "valid_to": None, "recorded_at": 6},
]
def owners_at(facts, valid_at, known_by):
result = []
for fact in facts:
valid = fact["valid_from"] <= valid_at
if fact["valid_to"] is not None:
valid = valid and valid_at < fact["valid_to"]
known = fact["recorded_at"] <= known_by
if valid and known:
result.append(fact["owner"])
return sorted(result)
print(owners_at(facts, valid_at=4, known_by=5))
print(owners_at(facts, valid_at=5, known_by=5))
print(owners_at(facts, valid_at=5, known_by=6))
['red'] [] ['blue']
Run Python snippets locally with the prerequisites named above. The module coding lab runs directly in your browser.
Pause and reason
A dependency edge ends at time 5 and an ownership edge begins at time 5. Can they form a simultaneous relationship under half-open intervals?
Check your understanding
A correction about Monday is recorded on Wednesday. Which query needs both clocks?
Your notes
Explain the mechanism in your own words. Add a failure you want to test.