tdfs4ds.feature_store.placement

tdfs4ds.feature_store.placement

Where a feature is stored: FS_FEATURE_PLACEMENT and the table tag (0.3.3.30).

By default every feature of one (data domain, entity, value type, primary index, partitioning) lives in the same FS_T_* table, whichever process computes it. That name is recomputed by register_features whenever it registers a feature (a new one, or one whose type changed) and written over the catalog row, so editing FEATURE_TABLE by hand moves no data and is undone by the next registration. A placement is therefore recorded, and the naming rule follows it:

``get_feature_store_table_name(..., table_tag='SALES')``  ->  ``FS_T_<hash>__SALES``

The tag is appended to the historical name, never substituted for any part of it: value type, primary index and partitioning stay encoded as before.

Storage

FS_FEATURE_PLACEMENT (valid time, PRIMARY INDEX (DATA_DOMAIN, ENTITY_NAME, FEATURE_NAME)): one row per feature triplet with its TABLE_TAG. The triplet is known before the FEATURE_ID exists, so a new process can start in its own table.

The table is optional, like FS_PROCESS_OPTIONS: created at setup() and by connect() when missing, a failed CREATE is one warning remembered for the store, and a store without the table (or without a row) behaves exactly as before - one cached existence check per store, no other statement.

PLACEMENT_NAME module-attribute

PLACEMENT_NAME = 'FS_FEATURE_PLACEMENT'

TAG_MAX module-attribute

TAG_MAX = 64

_TAG_RE module-attribute

_TAG_RE = compile('^[A-Za-z][A-Za-z0-9_]*$')

_STATE module-attribute

_STATE: dict = {}

_WARNED module-attribute

_WARNED: set = set()

sql_literal

sql_literal(value)

Escape value for use inside a single-quoted SQL string literal.

For the DBC probes and catalog predicates that compare a name as data (WHERE DatabaseName = '…'). The caller supplies the surrounding quotes.

validate_tag

validate_tag(tag) -> str

The tag as stored (upper case). Raises ValueError for anything that is not a plain identifier of at most 64 characters: it becomes part of a table name.

_table_name

_table_name() -> str

_qualified_table

_qualified_table() -> str

_key

_key() -> Optional[str]

reset_state

reset_state() -> None

Forget what was learnt about the table (tests, setup(), connect()).

_warn_once

_warn_once(key: str, message: str, *args) -> None

_execute

_execute(sql: str)

placement_ddl

placement_ddl() -> str

placement_creation

placement_creation(existing: Optional[Iterable[str]] = None) -> bool

Create FS_FEATURE_PLACEMENT when missing. Never raises.

existing is the lower-cased object set connect() read from DBC: a table found there costs no CREATE. Returns whether the table is usable.

available

available() -> bool

Whether FS_FEATURE_PLACEMENT exists in the primary store (checked once per store).

entity_name_of

entity_name_of(entity) -> str

The ENTITY_NAME of the catalog for an entity: its columns, sorted, comma-joined.

read_tags_sql

read_tags_sql(data_domain, entity_name) -> str

read_all_sql

read_all_sql() -> str

upsert_sql

upsert_sql(data_domain, entity_name, feature_name, table_tag) -> str

Record (or change) the placement of one feature. Every column is named.

delete_sql

delete_sql(data_domain, entity_name, feature_name, purge: bool = True) -> str

read_tags

read_tags(data_domain, entity) -> Dict[str, str]

{FEATURE_NAME upper-cased: TABLE_TAG} of one (data domain, entity).

Fail-open: no table, no row or an unreadable table is an empty dict, which is every feature in its historical table. The table is checked once per store, so a store that never used placements pays one cached query and nothing else.

read_all

read_all() -> List[dict]

Every current placement: [{"data_domain", "entity", "feature", "tag", "since"}].

tag_of

tag_of(tags: Dict[str, str], feature_name) -> Optional[str]

The tag of a feature in a :func:read_tags result (case-insensitive), or None.

record_placements

record_placements(data_domain, entity, feature_names, table_tag, *, create: bool = True) -> int

Write the placement of feature_names (one statement per feature). Returns the count.

Raises RuntimeError when the table does not exist and cannot be created: a tag that is not recorded would be forgotten by the next run.

prepare_storage_tag

prepare_storage_tag(entity_id, feature_names, table_tag) -> Optional[str]

Record the placement of a new process's features. Returns None when done, else the reason it cannot be (the caller logs it and registers nothing).

A feature already placed under another tag, or already stored in a table that does not carry this tag, is refused: placing it now would send its next values to a new table and leave its history behind. relocate_features moves a feature with its history.

get_feature_placement

get_feature_placement() -> List[dict]

The current placements: [{"data_domain", "entity", "feature", "tag", "since"}]. Empty when the store has no FS_FEATURE_PLACEMENT table or no row.