GitHub

Storage API

Abstract Interface

In-Memory Store

SemanticSpacetime.MemoryStore — Type
MemoryStore <: AbstractSSTStore

A fully in-memory graph store. Holds nodes, links, page map entries, and per-size-class counters for NodePtr allocation. Arrow and context directories use the existing module-level state.

Example

store = MemoryStore()
n1 = mem_vertex!(store, "hello", "ch1")
n2 = mem_vertex!(store, "world", "ch1")
mem_edge!(store, n1, "then", n2)
SemanticSpacetime.mem_vertex! — Function
mem_vertex!(store::MemoryStore, name::AbstractString, chap::AbstractString) -> Node

Create or retrieve a node in the in-memory store. Idempotent — if a node with the same text already exists, returns the existing node.

SemanticSpacetime.mem_edge! — Function
mem_edge!(store::MemoryStore, from::Node, arrow::AbstractString,
          to::Node, context::Vector{String}=String[],
          weight::Float32=1.0f0) -> (ArrowPtr, Int)

Create a directed link between two nodes using a named arrow type. The arrow must already be registered in the arrow directory. Also creates the inverse link if one is registered.

Returns (arrow_ptr, sttype).

SemanticSpacetime.mem_get_node — Function
mem_get_node(store::MemoryStore, nptr::NodePtr) -> Union{Node, Nothing}

Retrieve a node by its pointer. Returns nothing if not found.

SemanticSpacetime.mem_search_text — Function
mem_search_text(store::MemoryStore, query::AbstractString) -> Vector{Node}

Simple case-insensitive substring search across all node texts. Returns nodes whose text contains query.

SemanticSpacetime.link_count — Function
link_count(store::MemoryStore) -> Int

Return the total number of links that have been added to the store.

DBStore (SQLite / DuckDB)

SemanticSpacetime.DBStore — Type
DBStore <: AbstractSSTStore

Database-backed graph store using DBInterface.jl for portable SQL access. Works with SQLite, DuckDB, or any DBInterface-compatible connection.

Example

using SQLite
db = SQLite.DB(":memory:")
store = DBStore(db)
db_vertex!(store, "hello", "ch1")
SemanticSpacetime.open_sqlite — Function
open_sqlite(path::AbstractString=":memory:") -> DBStore

Open a SQLite-backed SST store. Requires using SQLite.

SemanticSpacetime.open_duckdb — Function
open_duckdb(path::AbstractString=":memory:") -> DBStore

Open a DuckDB-backed SST store. Requires using DuckDB.

SemanticSpacetime.db_vertex! — Function
db_vertex!(store::DBStore, name::AbstractString, chap::AbstractString) -> Node

Create or retrieve a node. Idempotent.

SemanticSpacetime.db_edge! — Function
db_edge!(store::DBStore, from::Node, arrow::AbstractString, to::Node;
         context::Vector{String}=String[], weight::Float32=1.0f0)

Create a directed link between two nodes. Also creates the inverse link.

PostgreSQL Connection

SemanticSpacetime.SSTConnection — Type
SSTConnection

Wraps a PostgreSQL database connection with cached SST state. Create with open_sst(), close with close_sst(sst).

SemanticSpacetime.open_sst — Function
open_sst(; load_arrows::Bool=false, host::String="localhost", port::Int=5432) -> SSTConnection

Open a connection to the SSTorytime PostgreSQL database. If load_arrows is true, arrow and context directories are loaded from the database on connection.

SemanticSpacetime.configure! — Function
configure!(sst::SSTConnection)

Configure the database connection: create types, tables, stored functions, and optionally load arrows and contexts from existing data.

High-Level Graph API

SemanticSpacetime.vertex! — Function
vertex!(sst::SSTConnection, name::AbstractString, chap::AbstractString) -> Node

Create or retrieve a node in the SST graph. Idempotent — if a node with the same text already exists, returns the existing node.

Arguments

  • sst: Open database connection
  • name: Text content of the node
  • chap: Chapter/section this node belongs to

Example

sst = open_sst()
n1 = vertex!(sst, "Mary had a little lamb", "nursery rhymes")
n2 = vertex!(sst, "Whose fleece was white as snow", "nursery rhymes")
close_sst(sst)
SemanticSpacetime.edge! — Function
edge!(sst::SSTConnection, from::Node, arrow::AbstractString, to::Node,
      context::Vector{String}=String[], weight::Float32=1.0f0) -> (ArrowPtr, Int)

Create a directed link between two nodes using a named arrow type. The arrow must already be registered in the arrow directory.

Returns (arrow_ptr, sttype) for the created link.

Arguments

  • sst: Open database connection
  • from: Source node (returned by vertex!)
  • arrow: Short or long name of a registered arrow
  • to: Destination node (returned by vertex!)
  • context: Optional context labels for the link
  • weight: Optional link weight (default 1.0)

Example

sst = open_sst(load_arrows=true)
n1 = vertex!(sst, "Event A", "chapter1")
n2 = vertex!(sst, "Event B", "chapter1")
edge!(sst, n1, "then", n2, String[], 1.0f0)
close_sst(sst)
SemanticSpacetime.hub_join! — Function
hub_join!(sst::SSTConnection, name::AbstractString, chap::AbstractString,
          from_ptrs::Vector{NodePtr}, arrow::AbstractString,
          context::Vector{String}, weights::Vector{Float32}) -> Node

Create a hub node and link multiple source nodes to it with the same arrow type. Used for many-to-one relationships.

Returns the hub node.

SemanticSpacetime.graph_to_db! — Function
graph_to_db!(sst::SSTConnection; show_progress::Bool=false)

Upload the entire in-memory graph (from the global node directory) to the database. This is typically called after building a graph with the N4L compiler.

DB Sync

SemanticSpacetime.synchronize_nptrs! — Function
synchronize_nptrs!(sst::SSTConnection, store::MemoryStore)

Sync in-memory node pointer counters with the database by reading the maximum CPtr for each size class channel.

SemanticSpacetime.cache_node! — Function
cache_node!(n::Node)

Cache a node in the module-level node directory. Idempotent — does not overwrite an existing entry.