tdfs4ds.feature_store.feature_query_retrieval¶

tdfs4ds.feature_store.feature_query_retrieval ¶

quote_ident ¶

quote_ident(name, force=False)

Return name as a Teradata identifier, quoting it only if required.

Idempotent: an already-quoted name is returned unchanged rather than being wrapped a second time. Embedded quotes are escaped as "".

Parameters¶

name : str The raw object/database name. force : bool, default False Quote even when the name does not need it. Use only at the few sites that have always emitted unconditional quotes and whose exact output is already baked into persisted DDL (see feature_store/feature_query_retrieval.py) — elsewhere forcing would change the SQL of existing stores for no reason.

qualified ¶

qualified(database, object_name, force=False)

Build db.obj with each part quoted only as needed.

qualified('TDB', 'FS_X') == 'TDB.FS_X' (unchanged for ordinary names); qualified('SVC@CORP', 'FS_X') == '"SVC@CORP".FS_X'. An empty/None database yields the bare object name, so unqualified callers keep working.

force=True quotes both parts unconditionally — only for the sites that have always emitted quotes and whose exact text is already persisted (dataset view DDL, returned volatile-table names).

split_qualified ¶

split_qualified(name)

Split db.obj into (database, object), both de-quoted.

Quote-aware, so a dot inside a quoted part does not split the name: split_qualified('"DEINF.CARLOSN"."FS_X"') == ('DEINF.CARLOSN', 'FS_X'). The naive rsplit('.', 1) this replaces returns ('"DEINF.CARLOSN"', '"FS_X"') only by luck and ('"DEINF', 'CARLOSN"."FS_X"') in the split('.') variant.

An unqualified name returns ('', name).

list_features ¶

list_features()

Retrieves and returns a list of features from a feature store as a DataFrame.

This function constructs a SQL query to fetch all features from a specific catalog view within a schema. The query uses the schema and catalog name configured in the tdfs4ds module. The function executes the query and returns the result as a DataFrame.

Returns:

Type	Description
	tdml.DataFrame: A DataFrame containing the list of features from the feature store.

Notes

The function relies on the tdfs4ds module for configuration, including the SCHEMA and FEATURE_CATALOG_NAME_VIEW settings.
The tdml.DataFrame is used to execute the query and retrieve the data.
This function does not include temporal logic or filtering. It assumes the default behavior of querying the current valid state of the feature catalog.
Cross-store federation (v0.3.1.148): when read-only stores are attached (tdfs4ds.SCHEMA_READONLY), returns a UNION ALL across the primary + read-only stores' feature-catalog views (with a FEATURE_STORE provenance column); otherwise byte-identical to the single-store read.

current_catalog_rows_sql ¶

current_catalog_rows_sql()

The feature catalog view, restricted to the rows valid now by a plain predicate (no temporal qualifier, which DataFrame.from_query cannot carry).

generate_uuid_from_string ¶

generate_uuid_from_string(seed_string: str) -> str

get_feature_store_table_name ¶

get_feature_store_table_name(entity_id, feature_type, data_domain=None, primary_index=None, partitioning='', table_tag=None)

Constructs names for a database table and a corresponding view within a feature store, using the provided entity attributes, feature type, optional data domain, primary index, and partitioning information.

This function generates names that are intended for organizing and accessing features in a structured manner within a feature store. The naming convention integrates various elements, including a prefix (indicating tables or views), the specified data domain (or a default one), and aspects of the entity ID, ensuring uniqueness and clarity in the schema.

entity_id (dict, list, str, int): The identifier(s) for the entity. This can be:
- a dictionary with keys representing entity attributes,
- a list of attributes, or
- a single attribute (string or integer). The function constructs the base part of the table and view names differently based on the type of entity_id.
feature_type (str): Specifies the type of feature, contributing to the naming to indicate the kind of data stored.
data_domain (str, optional): The categorization under which the table and view will be organized. If not provided, a default value from tdfs4ds.DATA_DOMAIN is used.
primary_index (list, optional): Specifies the primary index attributes. If not provided, it defaults to the attributes derived from entity_id. This influences the order and inclusion of entity attributes in the name.
partitioning (str, optional): A string containing attributes used for partitioning, separated by spaces or commas. This affects how the name indicates the data partitioning strategy.
table_tag (str, optional): A placement tag (see tdfs4ds.feature_store.placement). Without it the names are exactly the historical ones; with it __<TAG> is appended, so the features placed under that tag live in a table of their own (same value type, same primary index and partitioning).

Returns: - tuple: Contains two strings; the first is the table name, and the second is the view name. These are constructed based on the input parameters to fit within a feature store's schema.

Example: - For entity_id={'customer_id': 123}, feature_type='purchase_history', data_domain='retail', primary_index=['customer_id'], and partitioning='year, month', this function would generate names like 'FS_T_retail_CUSTOMER_ID__YEAR_MONTH__PURCHASE_HISTORY' and 'FS_V_retail_CUSTOMER_ID__YEAR_MONTH__PURCHASE_HISTORY'.

Note: - Assumes the presence of a tdfs4ds module with a DATA_DOMAIN constant for default data domain usage. - Designed for flexibility in entity ID specification, supporting simple IDs, attribute lists, or attribute key dictionaries.

get_available_features ¶

get_available_features(entity_id, display_details=False)

Retrieves the names of available features for a given entity ID from a feature store.

This function constructs and executes a SQL query to select feature names from a specific catalog within a schema for a given entity ID, optionally using a specific valid time if set in tdfs4ds.FEATURE_STORE_TIME. The function supports querying features as of a certain timestamp or the current valid time if no timestamp is specified. It also provides an option to display detailed information about the features.

Parameters:

Name	Type	Description	Default
`entity_id`	`str, list, or dict`	The ID of the entity for which to retrieve available features. This can be a single ID (str), a list of IDs, or a dictionary of IDs where keys are entity names and values are their corresponding IDs.	required
`display_details`	`bool`	If True, prints detailed information about all features in the catalog. Defaults to False.	`False`

Returns:

Name	Type	Description
`list`		A list of feature names available for the specified entity ID.

Note

tdfs4ds is assumed to be a configuration module or object containing settings for the feature store, including FEATURE_STORE_TIME, SCHEMA, FEATURE_CATALOG_NAME, DATA_DOMAIN, and DEBUG_MODE.
The entity ID(s) are used to filter the features specific to the entity. If entity_id is a dictionary, the keys are considered as entity names, and their values are IDs. If it's a list, it's assumed to be a list of entity names or IDs. For a single string, it is treated as a single entity name or ID.
FEATURE_STORE_TIME is used to determine the temporal context for querying the feature data. If it is None, the query defaults to the current valid time.
If DEBUG_MODE is enabled in tdfs4ds, the constructed query is printed to the console.
The function uses tdml.DataFrame.from_query to execute the SQL query and to_pandas to convert the result into a pandas DataFrame for further processing.

get_list_entity ¶

get_list_entity(domain=None)

Retrieve a list of unique entity names from a specified data domain.

This function executes a database query to extract distinct entity names from a feature catalog, filtered by the provided data domain. If no domain is specified, it defaults to a predefined data domain.

domain (str, optional): The data domain to filter the entity names. Defaults to None, in which case a predefined domain is used.

Returns: DataFrame: A pandas-like DataFrame containing the unique entity names.

get_list_features ¶

get_list_features(entity_name, domain=None)

Retrieve a list of feature names associated with a specific entity or entities from a given data domain.

This function constructs and executes a database query to extract feature names for the specified entity or entities from a feature catalog, filtered by the provided data domain. If no domain is specified, it defaults to a predefined data domain.

entity_name (str or list): The name of the entity or a list of entity names to fetch features for. domain (str, optional): The data domain to filter the feature names. Defaults to None, where a predefined domain is used.

Returns: DataFrame: A pandas-like DataFrame containing the feature names associated with the given entity or entities.

get_feature_versions ¶

get_feature_versions(entity_name, features, domain=None)

Retrieve version identifiers for one or more features belonging to a given entity.

The function queries the underlying metadata tables to find the process (i.e., feature‑version) records that match the supplied entity and feature names. It returns a mapping from each requested feature name to either:

None – if no matching rows were found.
A single UUID string – if exactly one matching row exists for the feature.
A list of dictionaries – if more than one matching row is found; each dictionary contains: process_id – the UUID of the process that produced the version, process_view_name – the human‑readable view name associated with that process.

Parameters¶

entity_name : str | list[str] The name (or names) of the entity whose features we are querying. If a single string is supplied it is treated as a singleton list.

str | list[str]

One or more feature names to look up. Accepts a single string or an iterable of strings; if a single string is provided it is wrapped in a list internally.

str, optional

The data‑domain partition to filter on. If omitted the default tdfs4ds.DATA_DOMAIN constant is used.

Returns¶

dict[str, str | None | list[dict]] A dictionary keyed by feature name. Each value is either: * None – no records were found for that feature. * str – a single UUID string when exactly one row matched. * list[dict] – multiple matches; each dict has keys process_id and process_view_name.

Notes¶

The query joins the feature catalog view with the process catalog (specifically the “feature split” view) on data domain, entity ID, and feature name.
SQL string literals are escaped by doubling single quotes; this is a lightweight escape that suffices for the current use‑case.
The function preserves insertion order of features in the returned dictionary (Python 3.7+ guarantees dict order).
When tdfs4ds.DEBUG_MODE is true, the generated SQL statement is printed to stdout – useful for troubleshooting.

Example¶

get_feature_versions('user', ['age', 'income'])

get_entity_tables ¶

get_entity_tables(entity_id, data_domain=None)

Retrieves a list of table names associated with a given entity ID or IDs from a feature catalog within a specific data domain.

This function constructs and executes an SQL query to select distinct table names from a feature catalog that match the given entity ID(s) and data domain. If the data domain is not specified, it defaults to the system's default data domain. The entity ID can be a single string or a list of strings. If DEBUG_MODE is enabled in the system, the function prints the SQL query before execution.

Parameters: - entity_id (str or list of str): The ID or IDs of the entities for which to retrieve table names. - data_domain (str, optional): The data domain within which to search for the entity IDs. Defaults to the system's default data domain if None.

Returns: - list of str: A list of unique table names (in the format 'FEATURE_DATABASE.FEATURE_TABLE') associated with the given entity ID(s) within the specified data domain.

Exceptions: - If the SQL query execution fails, the function attempts to retrieve the table names by converting the query results into a pandas DataFrame and then extracting the table names from it.

Note: - This function depends on the external modules tdfs4ds and tdml for database schema details, default configurations, and SQL execution.

get_feature_store_content ¶

get_feature_store_content(entity_id, data_domain=None, convert_to_date=False, time_manager=None, condition='<=')

Retrieves content from a feature store for a given entity ID or IDs within a specified data domain, with options to convert datetime columns to dates, filter data based on a time management table, and apply a specific condition for the filter.

This function first retrieves a list of table names associated with the given entity ID(s) in the specified data domain using the get_entity_tables function. It then constructs SQL queries to select distinct records from these tables, focusing on the 'ValidStart' column and the entity ID(s). If convert_to_date is True, it converts 'ValidStart' datetime values to date values in the queries. Additionally, if a time_manager object is provided, the function filters records in each table to include only those where 'ValidStart' meets the specified condition (e.g., before, on, or after) relative to the business date specified in the time_manager's table. The condition for comparison is specified by the condition parameter.

Parameters: - entity_id (str or list of str): The ID or IDs of the entities for which to retrieve content. - data_domain (str, optional): The data domain within which to search for the entity IDs. Defaults to the system's default data domain if None. - convert_to_date (bool, optional): Flag indicating whether to convert 'ValidStart' datetime values to date values. Defaults to False. - time_manager (object, optional): An object that specifies the schema and table name of a time management table to filter records based on business date. The object should have schema_name and table_name attributes, as well as a data_type indicating the type of data (e.g., date, datetime). - condition (str, optional): A string specifying the condition to apply to the 'ValidStart' column when filtering records based on the business date from the time management table. Defaults to '<='.

Returns: - DataFrame: A DataFrame containing the retrieved content, with the 'ValidStart' column and the entity ID(s) from each table in the feature store that matches the criteria, optionally filtered by business date and specific condition.

Note: - If DEBUG_MODE is enabled in the system, the function prints the constructed SQL query before execution. - This function leverages the tdml module for executing the SQL query and returning the results as a DataFrame. - The function adapts its behavior based on the presence and specifications of the time_manager object and the condition parameter to provide flexible data retrieval options.

get_feature_location ¶

get_feature_location(entity_id, selected_features)

Retrieve the location of selected features for given entity IDs.

Parameters: entity_id (list, dict, or str): The entity IDs for which feature locations are needed. Can be a list, dictionary, or string. selected_features (dict): A dictionary of selected features with their versions.

Returns: DataFrame: A pandas DataFrame containing the feature locations.

write_where_clause_filter ¶

write_where_clause_filter(filtermanager, filter_conditions, list_entity_id, filter_alias='FILTER', table_alias='A')

Constructs a SQL WHERE clause based on filter criteria.

This function generates a SQL WHERE clause for filtering records in a database. The filter_conditions parameter is a dictionary containing key-value pairs, where each key corresponds to a column name in filtermanager.col_names, and each value is an entity ID or filter value. The clause is constructed using aliases for the table and filter provided through filter_alias and table_alias.

Parameters:

Name	Type	Description	Default
`filtermanager`	`object`	An object that contains a `col_names` attribute, which is a list of valid column names used for validation against the keys in the `filter` dictionary.	required
`filter_conditions`	`dict`	A dictionary where keys represent column names that must match `filtermanager.col_names`, and values represent entity IDs or specific filter values.	required
`list_entity_id`	`list`	A list of entity IDs used to validate or restrict values in the filter dictionary.	required
`filter_alias`	`str`	The alias used for the filter table in the SQL query. Defaults to 'FILTER'.	`'FILTER'`
`table_alias`	`str`	The alias used for the main table in the SQL query. Defaults to 'A'.	`'A'`

Returns:

Name	Type	Description
`str`		A SQL WHERE clause string that joins each column and entity ID in `filter` using the format `<filter_alias>.<column> = <table_alias>.<value>` with 'AND' operators.

Raises:

Type	Description
`ValueError`	If any key in `filter` is not found in `filtermanager.col_names` or if any value in `filter` is not in `list_entity_id`.

Example

filtermanager.col_names = ['column1', 'column2'] filter_conditions = {'column1': 'entity_id1', 'column2': 'entity_id2'} list_entity_id = ['entity_id1', 'entity_id2'] write_where_clause_filter(filtermanager, filter_conditions, list_entity_id) 'FILTER.column1=A.entity_id1 AND FILTER.column2=A.entity_id2'

get_available_entity_id_records ¶

get_available_entity_id_records(entity_id, selected_features, other=None, time_column=None, filtermanager=None, filter_conditions=None)

Generate a SQL query to retrieve records for available entity IDs based on selected features.

Parameters: entity_id (list, dict, or str): The entity IDs for which records are needed. Can be a list, dictionary, or string. selected_features (dict): A dictionary of selected features with their versions. other (optional): An additional DataFrame object for more complex queries. Defaults to None. time_column (str, optional): The name of the time column to use for temporal conditions. Defaults to None.

tuple: A tuple containing: - str: A SQL query string to retrieve records for available entity IDs. - dict: A dictionary of the list of features and their locations.