# How to Enable Temporal Support When Building a Knowledge Graph with Semantica

> Learn how to enable temporal support for your Semantica knowledge graph. Easily integrate time-based data by setting enable_temporal=True or using environment variables. Build smarter graphs today.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-10

---

**Enable temporal support in Semantica by passing `enable_temporal=True` to the `GraphBuilder` constructor or `build_kg()` function, or by setting the `KG_ENABLE_TEMPORAL=true` environment variable before running your script.**

Semantica is an open-source framework for constructing knowledge graphs that evolve over time. When you enable temporal support while building a knowledge graph with Semantica, the `GraphBuilder` class parses validity periods from relationships and embeds chronological metadata directly into the graph structure. This activates downstream components like `TemporalGraphQuery` and `TemporalVersionManager`, allowing you to execute time-aware queries and create versioned snapshots of your data.


## Understanding Temporal Knowledge Graphs

In Semantica, a temporal knowledge graph tracks when relationships are valid through time-stamped edges. According to the semantica-agi/semantica source code, the system parses fields like `valid_from` and `valid_until` from your source documents using utilities in [`semantica/kg/temporal_model.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/temporal_model.py). This feature is **disabled by default** and must be explicitly activated to enable the parsing pipeline and metadata tracking required for temporal reasoning.


## Four Methods to Enable Temporal Support

You can activate temporal support through multiple configuration paths depending on your deployment architecture and coding style.

### 1. Pass the Flag to GraphBuilder

The most direct approach is providing the `enable_temporal` parameter when instantiating the core builder class. In [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py) (lines 57-78), the `GraphBuilder.__init__` method stores this flag as the instance attribute `self.enable_temporal` and injects `"temporal_enabled": True` into the resulting graph's metadata dictionary.

```python
from semantica.kg import GraphBuilder

builder = GraphBuilder(
    merge_entities=True,
    resolve_conflicts=True,
    enable_temporal=True,        # Activates temporal parsing

    temporal_granularity="day"   # Optional: controls timestamp precision

)

kg = builder.build(sources=[my_documents])
print(kg["metadata"]["temporal_enabled"])   # → True

```

### 2. Set the Environment Variable

For containerized or production deployments, export `KG_ENABLE_TEMPORAL=true` before execution. The `KGConfig._load_env_vars` method in [`semantica/kg/config.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/config.py) (lines 96-104) reads this environment variable and merges the boolean value into the global configuration object, which `GraphBuilder` consumes automatically during instantiation.

```bash
export KG_ENABLE_TEMPORAL=true
python build_graph.py

```

### 3. Configure via a Config File

Add the setting to a YAML or TOML configuration file under the `kg` section. The `KGConfig._load_config_file` method in [`semantica/kg/config.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/config.py) (lines 81-92) merges these values into the internal configuration dictionary that propagates to the builder.

```yaml

# config.yaml

kg:
  enable_temporal: true
  temporal_granularity: month
  merge_entities: true

```

Load the configuration before building your graph:

```python
from semantica.kg.config import kg_config
from semantica.kg.methods import build_kg

kg_config._load_config_file("config.yaml")
kg = build_kg(sources=my_documents)  # Temporal support active automatically

```

### 4. Use the build_kg Helper

The convenience wrapper `build_kg` in [`semantica/kg/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/methods.py) (lines 64-78) accepts the flag directly and forwards it to `GraphBuilder`. Specify `method="temporal"` to explicitly select the temporal building path and activate temporal field parsing.

```python
from semantica.kg.methods import build_kg

kg = build_kg(
    sources=my_documents,
    method="temporal",
    enable_temporal=True
)

```


## Architectural Components Activated

When you enable temporal support, Semantica initializes specialized subsystems to handle validity periods and time-based queries.

**TemporalModel Utilities**

The `TemporalModel` class in [`semantica/kg/temporal_model.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/temporal_model.py) provides normalization functions such as `parse_temporal_value` and `deserialize_relationship_temporal_fields`. These utilities convert ISO-8601 timestamps into internal representations and handle open-ended validity periods using the `TemporalBound.OPEN` constant when `valid_until` is unspecified.

**Query and Version Management**

With temporal support enabled, you can utilize `TemporalGraphQuery` (defined in [`semantica/kg/temporal_query.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/temporal_query.py)) to execute Allen-style temporal interval queries and compute relationships between time periods. The system also instantiates `TemporalVersionManager` to handle graph snapshotting, allowing you to export or analyze the knowledge graph state at specific historical timestamps.


## Summary

- Pass `enable_temporal=True` to `GraphBuilder` or `build_kg()` for direct activation, or set the `KG_ENABLE_TEMPORAL` environment variable for configuration-free deployments
- The builder stores the flag in `self.enable_temporal` and sets `"temporal_enabled": True` in graph metadata
- Temporal fields (`valid_from`, `valid_until`) are parsed using `TemporalModel` utilities in [`semantica/kg/temporal_model.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/temporal_model.py)
- Activated graphs support `TemporalGraphQuery` for point-in-time lookups and Allen-relation queries
- `TemporalVersionManager` enables snapshotting and versioning of temporal knowledge graphs


## Frequently Asked Questions

### Does enabling temporal support affect graph build performance?

Yes, temporal parsing introduces computational overhead during the construction phase. The `TemporalModel` utilities in [`semantica/kg/temporal_model.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/temporal_model.py) must validate and normalize ISO-8601 timestamps for every relationship containing temporal fields. However, query performance remains optimized because `GraphBuilder` creates temporal indexes when `enable_temporal` is `True`, allowing `TemporalGraphQuery` to execute point-in-time lookups without scanning the entire graph.

### What date formats does Semantica support for temporal fields?

Semantica accepts ISO-8601 formatted timestamps through the `parse_temporal_value` function. You can specify open-ended validity periods by omitting the `valid_until` field or explicitly setting it to `TemporalBound.OPEN`, which the system interprets as valid indefinitely from the `valid_from` date. The `deserialize_relationship_temporal_fields` function handles normalization of these values during the build process.

### Can I convert an existing static graph to a temporal graph?

No, you must rebuild the graph with `enable_temporal=True`. The `GraphBuilder` class only parses temporal metadata during the initial build phase in [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py). Static graphs lack the required temporal indexes and metadata entries that `TemporalGraphQuery` and `TemporalVersionManager` require for time-aware operations. Reprocess your source documents with temporal fields included and the flag enabled.

### Is temporal granularity configurable?

Yes. When instantiating `GraphBuilder`, pass the `temporal_granularity` parameter with values such as `"day"`, `"month"`, or `"year"`. According to the implementation in [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py), this setting controls how timestamps are bucketed and indexed, affecting storage efficiency and the precision of temporal queries executed through `TemporalGraphQuery`.