Filtering objects inside filter expression configuration fields or vehicle_label field

Within the SWAT API model, some objects support flexible user-defined filtering via "filter expression" within processing pipelines. Examples include processors and vehicle labels. These filtering expressions enable selective object inclusion in processing, employing syntax similar to QuerySet filters. For instance, to include soft-deleted bookings in processing, a booking filter expression can be applied during the process.

{
  "and": [
    {
      "pk__in": [
        <some_booking_id_list>
      ]
    },
    {
      "is_invalidated__exact": true
    }
  ]
}

Most object fields can be used to apply this filtering approach.

Using filters in vehicle_labels field

The same approach can be applied to manage the matching process of labels between vehicles, bookings and nodes.

The booking.vehicle_labels field in the booking object lists vehicle labels of vehicles eligible for delivering the order. In the following example, optimizing orders with this vehicle_labels field ensures that only vehicles with T01, T02, or T03 labels are used to fulfill these orders:

"vehicle_labels": {
        "or": [
          "T01",
          "T02",
          "T03"
        ]
      }

This feature proves beneficial when flexible grouping is needed with established rules for fleets and orders.

or another example,

{"and": 
  [{"or": ["2", "3"]}, {"not": {"and": ["4", "5"]}}]
}

Leveraging relations

Filtering expressions support relations between the objects that can be set using __ syntax. For example, the following booking_filter_expression allows to select bookings that are in prepared state, as well as those that have operations_locations set, which in turn belongs to locations_groups that contain code N10. This is an effective way of doing nested lookups which support both one-to-many and many-to-many relations.

{
   "state__in": [
    "prepared"
  ],
  "pickup_operations_location__group__code__in": [
    "N10"
  ]
}

Data Field Limitations

Filtering directly on arbitrary keys within the data JSON field (e.g., using data__my_key) is typically not supported. This is due to the underlying database schema implementation for these filtering expressions, which relies on standard relational field lookups rather than JSONB path traversals.

Detailed Filtering Syntax

Beyond standard field lookups, the filtering system supports advanced logical operations and references:

• Implicit Logic:

  • Dictionary: Treated as AND. { "A": 1, "B": 2 } means A=1 AND B=2.
  • List: Treated as OR. [ {"A": 1}, {"B": 2} ] means A=1 OR B=2.

• Explicit Logical Operators:

  • ~and: List of conditions that must all be true.
  • ~or: List of conditions where at least one must be true.
  • ~not: Negates the condition.

• Special Prefixes:

  • - (Dash): Use a value without a key content.
  • @ (At symbol): Reference another field on the same object. For example, {"scheduled_ts__gt": "@deadline_ts"} compares the scheduled_ts field against the deadline_ts field of the row.