Data model

Every catalog table is provisioned by tdfs4ds.setup() (or by tdfs4ds.connect(create_if_missing=True) if missing). All names use a configurable prefix — defaults are listed below.

Storage tables

Concept	Mutable (hidden)	Public view
Entity registry	inside the feature catalog	FS_V_FEATURE_CATALOG
Feature catalog	FS_FEATURE_CATALOG	FS_V_FEATURE_CATALOG
Process catalog	FS_PROCESS_CATALOG	FS_V_PROCESS_CATALOG
Process feature split	–	FS_V_PROCESS_CATALOG_FEATURE_SPLIT
Dataset catalog	FS_FS_DATASET_CATALOG, _ENTITY, _FEATURES, _BUILD, _WINDOW	FS_V_FS_DATASET_CATALOG, _ENTITY, _FEATURES, _BUILD, _WINDOW (see below)
Data distribution	FS_DATA_DISTRIBUTION	(read directly)
Follow-up (run history)	FS_FOLLOW_UP	(read directly)
FilterManager pool	FS_FILTER_MANAGER	(per-process companion view)

Dataset catalog

DATASET_CATALOG_NAME is FS_DATASET, and the catalog class adds its own FS_ prefix, so the objects are named FS_FS_DATASET_* (tables) and FS_V_FS_DATASET_* (public CURRENT VALIDTIME views). All five tables are VALIDTIME temporal and keyed by DATASET_ID.

Table	Columns	Content
_CATALOG	DATASET_ID, DATASET_NAME, DATASET_DATABASE, DATASET_TYPE, DATASET_VALIDTIME, METADATA	One row per dataset view. DATASET_VALIDTIME is CURRENT VALIDTIME, VALIDTIME AS OF TIMESTAMP '…' or TIME_MANAGER <db>.<view>
_ENTITY	DATASET_ID, ENTITY, ENTITY_TYPE	The dataset's grain: one row per entity column
_FEATURES	DATASET_ID, FEATURE_ID, FEATURE_NAME, FEATURE_TYPE, FEATURE_DATABASE, FEATURE_VIEW	One row per exposed feature column; FEATURE_VIEW is the storage table it reads
_BUILD (0.3.1.216)	DATASET_ID, BUILD_STRATEGY, JOIN_TYPE, TIME_MODE, AS_OF_TIMESTAMP, TIME_MANAGER_DATABASE, TIME_MANAGER_VIEW, TIME_MANAGER_TABLE, SOURCE_DATASET_ID	How the view was built: MULTIJOIN/GROUPED, INNER/FULL OUTER, CURRENT/AS_OF/TIME_MANAGER/HISTORY, and the dataset it was rebuilt from
_WINDOW (0.3.1.226)	DATASET_ID, START_KIND, END_KIND, START_TS, END_TS, DURATION_MONTHS, DURATION_SECONDS, DELAY_MONTHS, DELAY_SECONDS, DURATION_ISO, DELAY_ISO, SLIDING, WINDOW_TEXT	The window of a historical dataset; the view adds WINDOW_START / WINDOW_END, the bounds when queried. Snapshot datasets have no row

_BUILD and _WINDOW are separate tables joined on DATASET_ID, so a catalog created by an older version needs no ALTER, and older tdfs4ds versions keep reading the catalog unchanged. They are added the next time the catalog is opened. They are optional: a user without CREATE rights gets a warning, and datasets keep working. A dataset registered before they existed gets its rows when it is built again, or when the catalog is restored (restore_dataset_catalog, or Maintenance → Dataset catalog in the admin app). Read them with tdfs4ds.get_dataset_build() and tdfs4ds.get_dataset_window().

Documentation tables (set up automatically)

Level	Table	Key	Notes
Process — business logic	FS_PROCESS_DOCUMENTATION_BUSINESS_LOGIC	PROCESS_ID	Markdown
Process — features	FS_PROCESS_DOCUMENTATION_FEATURES	PROCESS_ID, FEATURE_NAME	Column docs
Process — EXPLAIN	FS_PROCESS_DOCUMENTATION_EXPLAIN	PROCESS_ID	Includes USER_SCORE, OPTIMIZATION_SCORE, N_STEPS, N_SPOOL_OBJECTS, raw plan
Business dictionary — objects	FS_BUSINESS_DICTIONARY_OBJECTS	(DATABASE_NAME, OBJECT_NAME)	OBJECT_TYPE ∈ T/V/D
Business dictionary — sections	FS_BUSINESS_DICTIONARY_SECTIONS	(DATABASE_NAME, OBJECT_NAME, SECTION_NAME)	LLM-generated for datasets
Business dictionary — columns	FS_BUSINESS_DICTIONARY_COLUMNS	(DATABASE_NAME, TABLE_NAME, COLUMN_NAME)	One row per column

Feature data tables

For each (entity, feature_type) combination, tdfs4ds creates a temporal table holding the actual feature values:

FS_T_<ENTITY>_<TYPE>          — mutable, write-through
FS_V_<ENTITY>_<TYPE>          — public, CURRENT VALIDTIME view

Example: a BIGINT feature on CUSTOMER_ID lives in FS_T_CustomerID_BIGINT. The MERGE / UPDATE_INSERT path is controlled by tdfs4ds.STORE_FEATURE.

How everything connects

       upload_features()
              │
              ▼
   ┌──────────────────────┐
   │  Feature engineering │   →  REPLACE VIEW {SCHEMA}.{VIEW_NAME}
   │       view (SQL)     │
   └──────────┬───────────┘
              │
              ▼
   ┌──────────────────────┐
   │   Process catalog    │   →  PROCESS_ID (uuid), VIEW_NAME, ENTITY_NAME, FEATURES
   └──────────┬───────────┘
              │
              ▼
   ┌──────────────────────┐
   │  Feature catalog     │   →  FEATURE_NAME, ENTITY_NAME, FEATURE_TABLE, PROCESS_ID
   └──────────┬───────────┘
              │
              ▼
   ┌──────────────────────┐
   │  FS_T_<ENT>_<TYPE>   │   →  Feature values, temporal
   └──────────┬───────────┘
              │
              ▼
   ┌──────────────────────┐
   │  build_dataset()     │   →  DS_<NAME> view joining selected feature versions
   └──────────────────────┘

Configurable names

Every table name is a module global so you can rename to fit a corporate convention before setup():

tdfs4ds.FEATURE_CATALOG_NAME = 'MYCO_FEATURE_CATALOG'
tdfs4ds.PROCESS_CATALOG_NAME = 'MYCO_PROCESS_CATALOG'
# ... then
tdfs4ds.setup()

See tdfs4ds/__init__.py for the full list of name constants.