Core Concepts

Storage profiles

Choose row, log, searchable, and archive-oriented table behavior for agent-native workloads.

Overview

Storage profiles are table-level physical-behavior hints. They tell Synapsor how a table is expected to behave for hot lookups, stable reference data, append-heavy history, audit evidence, searchable knowledge, or colder archive/reporting data.

Physical layout in the current single-node engine is explicit: hot_state, reference_data, append_log, and audit_log are tuple/row-oriented profiles; searchable_knowledge is the hybrid profile with tuple rows plus lexical/vector-style side indexes; columnar_archive is the column-oriented archive profile.

Profiles are not authorization rules and they do not make a table part of an evidence bundle by themselves. Evidence is selected by agent contexts, capability plans, hybrid searches, and explicit evidence mappings.

Hosted V2 remains single-node beta software. Storage profiles help developers express intent inside the current engine; they are not serverless storage classes, HA promises, or compliance guarantees.

Profile chooser

Pick the profile that matches how the table changes and how agents will use it.

Current state

hot_state for active workflow rows
reference_data for stable dimensions
Best for point lookups and frequent updates

History

append_log for event streams
audit_log for evidence, approvals, replay, and decisions
Best for traceability and retention

Search and archive

searchable_knowledge for policy/docs/memory chunks
columnar_archive for closed history and reporting
Best for retrieval or cold scans

Physical layout map

Use tuple profiles for live mutable state and history, the hybrid profile for searchable text/memory, and columnar_archive for cold reporting data.

Tuple / row profiles

hot_state: active mutable workflow rows, sessions, current tickets, current expenses
reference_data: stable dimensions such as tenants, employees, products, policies by id
append_log: event streams, turn logs, card transactions, usage events
audit_log: evidence, approvals, replay records, proposal events, settlement history

Hybrid profile

searchable_knowledge: tuple rows plus hybrid retrieval indexes
Use lexical_index for text matching and vector_index for embedding/vector-style retrieval
Use filter_keys and zone_map for tenant, topic, role, status, region, or effective-date filters
Best for policy chunks, governed memory facts, docs, and guardrail text

Column profile

columnar_archive: column-oriented closed history and reporting snapshots
COMPACT TABLE ... INTO COLUMNAR moves eligible older history into a denser layout
ARCHIVE / EXPORT / RESTORE ARCHIVE handle colder lifecycle operations
Do not use columnar_archive for frequently updated hot workflow state

Developer notes

Use hot_state for rows that represent what is true right now.
Use audit_log for evidence, approvals, proposal events, and replayable decision history.
Use searchable_knowledge for policy chunks, memory facts, docs, and guardrail text used by hybrid search.
Use columnar_archive for closed history that is kept mostly for reporting or retention.
Remember the physical mapping: tuple/row profiles for hot_state/reference_data/append_log/audit_log, hybrid profile for searchable_knowledge, and column profile for columnar_archive.

Table DDL

SQL

-- hot_state is for current workflow rows that are updated and read frequently.
CREATE TABLE tickets (
  id VARCHAR PRIMARY KEY,                    -- app-domain ticket id
  tenant_id VARCHAR NOT NULL,                -- tenant scope used by session filters
  status VARCHAR NOT NULL,                   -- mutable workflow state
  body VARCHAR                               -- current ticket text
) WITH PROFILE hot_state;                    -- row layout for active mutable rows

-- searchable_knowledge is for policy/docs/memory rows used by HYBRID search.
CREATE TABLE policy_chunks (
  chunk_id VARCHAR PRIMARY KEY,              -- app/domain chunk id
  tenant_id VARCHAR,                         -- used by FILTER tenant scope
  topic VARCHAR,                             -- optional retrieval filter
  body VARCHAR                               -- text searched by hybrid index
) WITH (
  profile = 'searchable_knowledge',          -- hybrid-search optimized profile
  lexical_index = 'body',                    -- keyword/lexical source column
  vector_index = 'body',                     -- vector-style source column
  filter_keys = 'tenant_id,topic'            -- common filter columns
);

-- audit_log is for evidence, proposal, approval, and replay records.
CREATE TABLE evidence_hits (
  id VARCHAR PRIMARY KEY,                    -- evidence/audit row id
  tenant_id VARCHAR,                         -- tenant scope
  created_at VARCHAR,                        -- timestamp string for retention/zone map
  payload VARCHAR                            -- audit payload or serialized metadata
) WITH (
  profile = 'audit_log',                     -- append-heavy audit layout
  compact_after = '1 day',                   -- compaction target
  hot_window = '7 days',                     -- fast-access window target
  retention = '90 days',                     -- retention target
  legal_hold = false,                        -- set true to pin retention
  zone_map = 'tenant_id,created_at'          -- pruning columns
);

Examples

text

auto
hot_state
reference_data
append_log
audit_log
searchable_knowledge
columnar_archive