plexus.utils.identifier_search module

Identifier Search Utilities - High-level functions for finding items by identifier values.

This module provides convenient functions for exact-match identifier searches, building on the low-level Identifier model to provide common use cases.

Key Functions: - find_item_by_identifier: Find a single item by exact identifier value - find_items_by_identifier_type: Find all items with identifiers of a specific type - batch_find_items_by_identifiers: Efficiently find multiple items by identifier values

Performance Characteristics: - All functions use O(1) exact-match GSI lookups, not scans - Account-scoped for security and performance - Efficient batch operations for bulk lookups - No cross-account data leakage

Usage Examples:

from plexus.utils.identifier_search import find_item_by_identifier from plexus.dashboard.api.client import ‘PlexusDashboardClient’

client = ‘PlexusDashboardClient’.for_account(“my-account”)

# Find single item by exact identifier value item = find_item_by_identifier(“CUST-123456”, “my-account”, client) if item:

print(f”Found item: {item.id}”)

# Find all items with “Customer ID” identifiers items = find_items_by_identifier_type(“Customer ID”, “my-account”, client)

# Batch lookup multiple items items_dict = batch_find_items_by_identifiers(

[“CUST-123456”, “ORD-789012”], “my-account”, client

)

plexus.utils.identifier_search.batch_find_items_by_identifiers(identifier_values: List[str], account_id: str, client: PlexusDashboardClient) → Dict[str, Item]

Efficiently find multiple items by their identifier values.

Uses batch lookup for optimal performance when searching for many items.

Args:

identifier_values: List of exact values to search for account_id: Account to search within client: API client

Returns:

Dictionary mapping identifier_value -> Item for found items. Missing identifier values will not appear in the result.

Example:

items_dict = batch_find_items_by_identifiers(

[“CUST-123456”, “ORD-789012”, “TICKET-555”], “account123”, client

)

for value, item in items_dict.items():

print(f”Identifier {value} -> Item {item.id}”)

# Check if specific identifier was found if “CUST-123456” in items_dict:

customer_item = items_dict[“CUST-123456”]

plexus.utils.identifier_search.create_identifiers_for_item(item_id: str, account_id: str, identifiers_data: List[Dict[str, Any]], client: PlexusDashboardClient) → List[Identifier]

Create identifier records for an item from JSON-style data.

Converts from the old JSON format to separate Identifier records. Useful for migration and dual-write scenarios.

Args:

item_id: ID of the item these identifiers belong to account_id: Account ID for data isolation identifiers_data: List of identifier dicts in JSON format:

[{“name”: “Customer ID”, “id”: “CUST-123”, “url”: “…”}]

client: API client

Returns:

List of created Identifier objects (may be empty if all fail)

Example:

# Convert from JSON format to Identifier records json_identifiers = [

{“name”: “Customer ID”, “id”: “CUST-123456”, “url”: “https://…”}, {“name”: “Order ID”, “id”: “ORD-789012”}

]

identifier_records = create_identifiers_for_item(

“item123”, “account123”, json_identifiers, client

)

plexus.utils.identifier_search.find_item_by_identifier(identifier_value: str, account_id: str, client: PlexusDashboardClient) → Item | None

Find an item by exact identifier value within an account.

This is the primary search function for exact-match lookups. Uses O(1) GSI lookup for consistent performance.

Args:

identifier_value: Exact value to search for (e.g., “CUST-123456”) account_id: Account to search within client: API client

Returns:

Item object if found, None if not found

Example:

item = find_item_by_identifier(“CUST-123456”, “account123”, client) if item:

print(f”Found item {item.id} with data: {item.data}”)

plexus.utils.identifier_search.find_item_by_typed_identifier(identifier_name: str, identifier_value: str, account_id: str, client: PlexusDashboardClient) → Item | None

Find an item by identifier name and exact value.

More specific than find_item_by_identifier when you know the identifier type. Useful when the same value might exist for different identifier types.

Args:

identifier_name: Name of identifier type (e.g., “Customer ID”) identifier_value: Exact value to search for (e.g., “123456”) account_id: Account to search within client: API client

Returns:

Item object if found, None if not found

Example:

# Find item with specifically a “Customer ID” of “123456” # (ignoring any “Order ID” or other types with same value) item = find_item_by_typed_identifier(

“Customer ID”, “123456”, “account123”, client

)

plexus.utils.identifier_search.find_items_by_identifier_type(identifier_name: str, account_id: str, client: PlexusDashboardClient, limit: int | None = None) → List[Item]

Find all items that have identifiers of a specific type.

Args:

identifier_name: Name of identifier type (e.g., “Customer ID”, “Order ID”) account_id: Account to search within client: API client limit: Optional limit on number of results

Returns:

List of Item objects that have identifiers of the specified type

Example:

# Find all items with “Customer ID” identifiers items = find_items_by_identifier_type(“Customer ID”, “account123”, client) for item in items:

print(f”Item {item.id} has customer identifier”)

plexus.utils.identifier_search.get_item_identifiers(item_id: str, client: PlexusDashboardClient) → List[Dict[str, Any]]

Get all identifiers for a specific item in a format compatible with the UI.

Returns identifiers in the same format as the deprecated JSON field, ensuring compatibility with existing UI components.

Args:

item_id: ID of the item to get identifiers for client: API client

Returns:

List of identifier dictionaries with ‘name’, ‘id’ (value), and optional ‘url’

Example:

identifiers = get_item_identifiers(“item123”, client) # Returns: [ # {“name”: “Customer ID”, “id”: “CUST-123456”, “url”: “https://…”}, # {“name”: “Order ID”, “id”: “ORD-789012”} # ]