Shared-memory term cache
A cache of dictionary terms in PostgreSQL shared memory, used by every session. Terms that keep coming back, such as
rdf:type,rdfs:labeland your own predicates, are resolved from memory rather than by a table lookup.
What it does
Every load has to turn each parsed term into its dictionary id, or add it as a new term. The shared cache holds recently used term ↔ id pairs so that repeated terms skip the dictionary table. Because it lives in shared memory, a term one session has loaded is a cache hit for the next.
- It needs
shared_preload_libraries = 'pgrdf'and a server restart; see Install. Without the preload, pgRDF still works but the cache is off andpgrdf.stats()->'shmem_ready'isfalse. - It has a fixed number of slots. When it is full, older entries are evicted; correctness never depends on a hit.
- It serves the standard loaders (
parse_turtle,load_turtle). The staged loader resolves terms with set-based SQL instead, so its memory stays bounded at billion scale.
Why you'd use it
- Project managers — loading several vocabularies that share terms (RDF, RDFS, OWL, FOAF) gets cheaper after the first.
- Data scientists — repeated loads of similar data avoid most dictionary lookups.
- Operators — the counters in
pgrdf.stats()show how the cache is doing on a real workload.
Example
SELECT key, value
FROM jsonb_each(pgrdf.stats())
WHERE key LIKE 'shmem%';
-- key | value
-- ------------------+-------
-- shmem_hits | 462
-- shmem_ready | true
-- shmem_slots | 16384
-- shmem_misses | 101038
-- shmem_inserts | 100949
-- shmem_evictions | 83705(Your numbers will differ; the counters count everything since the server started.)
| Key | Meaning |
|---|---|
shmem_ready | The cache is active (pgRDF is preloaded). |
shmem_slots | Cache capacity, in terms. |
shmem_hits / shmem_misses | Lookups answered by the cache / not found in it. |
shmem_inserts | Terms added to the cache. |
shmem_evictions | Entries pushed out to make room. Many evictions mean the working set of terms is larger than the cache. |
These counters are cumulative and server-wide. For the cache's effect on one load, look at shmem_cache_hits in the verbose ingest report.
Resetting the cache
SELECT pgrdf.shmem_reset();This invalidates every cached term. It is needed after DROP EXTENSION pgrdf / CREATE EXTENSION pgrdf on a running server, because the recreated dictionary hands out new ids. It is not part of normal operation. It does not reset the stats() counters.