Skip to content

Build your first dataset

A dataset in tdfs4ds is a denormalised view that joins selected feature versions together for a given entity. It is always a view — never a table — so it stays consistent with the underlying temporal features.

1 · Discover what is available

from tdfs4ds.feature_store.feature_query_retrieval import (
    get_list_entity,
    get_available_features,
    get_feature_versions,
)

get_list_entity()                          # list every entity in the active DATA_DOMAIN
get_available_features(entity_id=['CUSTOMER_ID'])

2 · Resolve feature versions

build_dataset needs {feature_name: process_uuid} — one entry per feature. Always go through get_feature_versions; never construct the dict by hand:

selected_features = get_feature_versions(
    entity_name = 'CUSTOMER_ID',
    features    = ['nb_transactions', 'total_amount', 'avg_amount'],
)
# selected_features == {'nb_transactions': '550e...', 'total_amount': '551a...', ...}

If two processes register the same feature name, get_feature_versions picks the most recent. To freeze a specific version, set tdfs4ds.FEATURE_STORE_TIME first.

3 · Build the view

dataset = tdfs4ds.build_dataset(
    entity_id         = ['CUSTOMER_ID'],
    selected_features = selected_features,
    view_name         = 'DS_CUSTOMER_SPEND',
    comment           = 'Customer spending features, current state',
)

dataset.shape

build_dataset creates DS_CUSTOMER_SPEND as a Teradata view, registers it in the dataset catalog, and returns a teradataml DataFrame you can query immediately.

4 · Reuse without rebuilding

The view is now permanent — reattach to it in any future session:

dataset = tdml.DataFrame(tdml.in_schema(tdfs4ds.SCHEMA, 'DS_CUSTOMER_SPEND'))

Inspect before you build

Use return_query=True to see the generated DDL without creating the view or touching the dataset catalog:

sql = tdfs4ds.build_dataset(
    entity_id         = ['CUSTOMER_ID'],
    selected_features = selected_features,
    view_name         = 'DS_CUSTOMER_SPEND',
    return_query      = True,
)
print(sql)

Grouped query strategy

Pass grouped=True to collapse features from the same source table into a single MAX(CASE WHEN) … GROUP BY sub-query instead of one sub-query per feature. Useful for wide feature sets (20+ features from the same table):

dataset = tdfs4ds.build_dataset(
    entity_id         = ['CUSTOMER_ID'],
    selected_features = selected_features,
    view_name         = 'DS_CUSTOMER_SPEND',
    grouped           = True,
)

Point-in-time snapshots

Set FEATURE_STORE_TIME before calling build_dataset to materialise a historical view. Both grouped=False (default) and grouped=True work with time travel:

tdfs4ds.FEATURE_STORE_TIME = '2024-01-01 00:00:00'

dataset_january = tdfs4ds.build_dataset(
    entity_id         = ['CUSTOMER_ID'],
    selected_features = selected_features,
    view_name         = 'DS_CUSTOMER_SPEND_2024_01_01',
)

tdfs4ds.FEATURE_STORE_TIME = None    # back to current state

What's next