lce_service.entity_helpers module

lce_service.entity_helpers.get_id_from_entity_name(dbc: silo_cursor, name: str | None, entity_type: str, table: str, column_mapping: Dict[str, str], entity_type_plural: str | None = None) → int | None

Retrieve the entity ID for a given entity name, exactly or using fuzzy matching.

An entity whose name matches exactly is returned. Otherwise the name is matched approximately, see get_id_from_fuzzy_name.

Parameters:

  • dbc – A silo_cursor instance used to execute the database query and fetch entity data from the master database. Must be properly configured and connected to the database before calling this function.

  • name – The name of the entity to look up. Must be a non-empty string between 1 and 64 characters. Leading and trailing whitespace will be stripped during processing. Can be None, which will raise a ValueError.

  • entity_type – The type of entity being looked up (e.g., “Dynamic Application”, “PowerPack”). Used in error messages for context and user feedback. This should be a human-readable entity type name.

  • table – The database table to query for entities, including schema prefix if applicable (e.g., “master.`dynamic_app`”). The table must contain columns specified in the column_mapping parameter.

  • column_mapping – Dictionary mapping API field names to database column names. Must contain at least ‘id’ and ‘name’ keys that map to the corresponding database columns for entity ID and name fields.

  • entity_type_plural – The plural of entity_type, used in error messages. Defaults to entity_type followed by an “s”.

Returns:

The integer ID of the entity matching exactly, or of the best fuzzy match if a confident match is found.

Raises:

  • ValueError – When the name parameter is None, empty, not a string, or is longer than 64 characters.

  • MissingResourceError – When no entity matches confidently, see get_id_from_fuzzy_name.

  • DatabaseExecutionError – Raised when the database query execution fails for any reason (connection issues, invalid table/column names, syntax errors, etc.), as propagated from the underlying get_fields_from_table function.

lce_service.entity_helpers.get_id_from_fuzzy_name(dbc: silo_cursor, name: str | None, entity_type: str, table: str, column_mapping: Dict[str, str], entity_type_plural: str | None = None) → int | None

Retrieve the entity ID for a given entity name using fuzzy matching.

Queries the database to fetch entity records and performs fuzzy matching against the provided name to find the best match. Uses scoring thresholds and disambiguation logic to ensure accurate entity identification. The function employs a token-based fuzzy matching algorithm to handle minor variations in entity names and provides intelligent disambiguation when multiple similar matches are found. Callers that look up an exact match themselves, e.g. to report every entity sharing the name, use this function rather than get_id_from_entity_name.

The matching algorithm uses the following logic: 1. Validates input name length and format 2. Retrieves all entity names from the specified database table 3. Performs fuzzy matching using token sort ratio scoring 4. Applies a minimum score threshold (FUZZY_MATCHING_MIN_SCORE) to

filter out poor matches

  1. Uses a strong winner rule (FUZZY_MATCHING_CONFIDENT_SCORE_DIFFERENCE+ point difference) to resolve ambiguity

  2. Returns the best match ID or raises appropriate exceptions

Parameters:

  • dbc – A silo_cursor instance used to execute the database query and fetch entity data from the master database.

  • name – The name of the entity to look up, see get_id_from_entity_name.

  • entity_type – The type of entity being looked up, used in error messages.

  • table – The database table to query for entities, including schema prefix.

  • column_mapping – Dictionary mapping API field names to database column names, with at least ‘id’ and ‘name’ keys.

  • entity_type_plural – The plural of entity_type, used in error messages. Defaults to entity_type followed by an “s”.

Returns:

The integer ID of the best matching entity if a confident match is found.

Raises:

  • ValueError – When the name parameter is None, empty, not a string, or is longer than 64 characters.

  • MissingResourceError – When no entities in the database match the provided name above the minimum score threshold (FUZZY_MATCHING_MIN_SCORE), when the closest match falls below the acceptable similarity threshold, or when multiple entities have similar names. Also when multiple entities have similar scores making the match ambiguous (score difference less than FUZZY_MATCHING_CONFIDENT_SCORE_DIFFERENCE points).

  • DatabaseExecutionError – Raised when the database query execution fails, as propagated from the underlying get_fields_from_table function.

lce_service.entity_helpers.get_valid_entities_from_payload(payload: List[Dict[str, Any]] | Dict[str, Any], key: str, entity_name: str, entity_plural: str | None = None) → List[Dict[str, Any]]

Extract the entity dictionaries of a payload from the accepted payload formats.

A payload is a single entity dictionary, a list of them, or a dictionary holding a list of them under key.

Parameters:

  • payload – The payload of the request.

  • key – The key of the list of entities in a dictionary payload (e.g. “event_policies”).

  • entity_name – The name of one entity in error messages (e.g. “Event Policy”).

  • entity_plural – The name of several entities in error messages (e.g. “Event Policies”). Defaults to entity_name followed by an “s”.

Returns:

The entity dictionaries of the payload.

Raises:

ValueError – Raised when the payload is not one of the accepted formats, provides no entities, or holds an item that is not a dictionary.