Query Filtering Capabilities

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_oracle_wms/_utilities/filtering.py
• tests/unit/test_filtering.py
• src/flext_oracle_wms/README.md
• examples/03_complete_functionality_showcase.py
• examples/01_basic_usage.py

The Query Filtering Capabilities in the flext-oracle-wms library provide an enterprise-grade engine for narrowing, sorting, and validating data retrieved from Oracle Warehouse Management System (WMS) Cloud. This module is designed to handle high-volume data processing by allowing developers to apply complex criteria including range filters, case-insensitive matching, and nested attribute traversal.

The filtering system acts as a utility layer within the FlextOracleWmsClient, ensuring that query parameters are validated against safety limits (such as maximum condition counts) before being applied to record sets. This prevents performance degradation and ensures compliance with Oracle WMS API constraints.

Sources: src/flext_oracle_wms/README.md:38, src/flext_oracle_wms/_utilities/filtering.py:12-30

Architecture and Core Components

The filtering architecture centers around the FlextOracleWmsUtilitiesFiltering.Filter class. It employs a functional composition approach to validate and apply filters to sequences of records.

Logic Flow for Record Filtering

The diagram below illustrates how a record set is processed through the filter engine, from validation to final output.

The engine validates that the total number of conditions does not exceed the MAX_FILTER_CONDITIONS (defaulting to 50) to ensure system stability.
Sources: src/flext_oracle_wms/_utilities/filtering.py:27-50, tests/unit/test_filtering.py:40-60

Filter Operators and Comparison Logic

The system supports a wide range of operators, supporting both simple scalar equality and complex range or membership checks.

Supported Operators

Operator	Type	Description
eq	Equality	Standard equality; supports case-insensitive strings.
ne	Not Equal	Returns true if values do not match.
in	Membership	Checks if a value exists within a provided list.
contains	String Search	Partial string matching within a field.
gt / lt	Comparison	Greater than / Less than (Numeric and String).
gte / lte	Comparison	Inclusive range boundaries.

Sources: src/flext_oracle_wms/_utilities/filtering.py:170-215, tests/unit/test_filtering.py:270-350

Advanced Data Access (Nested Traversal)

The engine includes a _get_nested_value utility that allows filtering based on attributes in nested dictionaries using dot notation (e.g., company.address.city). It also provides a fallback mechanism that checks for flat underscore-joined keys (e.g., company_address_city) if the nested path is not found in the original structure.

# Example of nested value access logic
def _get_nested_value(self, record, field):
    keys = field.split(".")
    current = record
    for key in keys:
        if isinstance(current, dict):
            current = current.get(key)
        else:
            break
    # ... fallback to flat keys if necessary

Sources: src/flext_oracle_wms/_utilities/filtering.py:217-250, tests/unit/test_filtering.py:430-460

Sorting and Pagination Support

The filtering module provides built-in support for ordering results based on dynamic field paths. Sorting is performed using the sort_records method, which handles None values and different data types gracefully.

Comparison and Sorting Process

Usage Examples

Basic Entity Filtering

In a standard workflow, the client uses these utilities to filter data retrieved from specific WMS entities.

# Example from showcase: Filtering company records
client.get_entity_data(
    entity_name="company",
    limit=3,
    filters={"active": "Y"} # Simple equality filter
)

Sources: examples/03_complete_functionality_showcase.py:130-140

Complex Range Queries

The library provides convenience methods for ID range filtering, which is common in high-volume synchronization tasks.

# Filtering records between ID 1 and 3 inclusive
result = FlextOracleWmsUtilitiesFiltering.Filter.filter_by_id_range(
    records=sample_records,
    id_field="id",
    min_id=1,
    max_id=3
)

Sources: src/flext_oracle_wms/_utilities/filtering.py:77-95, tests/unit/test_filtering.py:380-405

Validation and Limits

The filtering engine enforces strict validation rules to maintain performance:

1. Condition Count: Total conditions (including items in IN lists) cannot exceed 50.
2. Type Safety: The engine utilizes pydantic-core adapters (specifically float_adapter) to ensure numeric comparisons are performed on valid numbers.
3. Case Sensitivity: Configurable at the engine level; defaults to case-insensitive for user convenience.

Sources: src/flext_oracle_wms/_utilities/filtering.py:35-45, src/flext_oracle_wms/_utilities/filtering.py:280-300, tests/unit/test_filtering.py:55-70

Conclusion

The Query Filtering Capabilities of flext-oracle-wms provide a robust, type-safe mechanism for managing Oracle WMS data. By centralizing comparison logic and enforcing validation limits, the system ensures that data operations are both flexible for the developer and safe for the enterprise environment.