Skip to main content

Filters and Sorting

All of the "listing" functions available in Satcat SDK support a powerful filtering and sorting API to enable retrieval of a specific set of results. These functions begin with the phrase list_, such as list_conjunctions, list_screenings, etc.

One or more filters can be specified; if there are multiple filters, only results which match all of the filters will be returned.

Filter Fields​

Filters can be applied to any field on the model returned by a list_ function. For example, the function:

    def list_screenings(
        ...
    ) -> Collection[models.Screening]:

returns a Collection of the Screening model. Any field of the Screening model, such as conjunctions_count or created_at, can be used as the field of a filter by passing the field's name as a string as the "field" parameter.

Filter Format​

Each filter is specified as a python dict (dictionary), with the following fields accepted:

  • "field": The field on the model to consider for filtering. For example, on the Conjunction model, the field "collision_probability" could be used.
  • "value": The query value with which to apply the operator "op" to the "field"
  • "op" (optional; by default, "eq"): The operator with which to apply the filter. This can be any one of the following:
    • "is_null": return results whose value for the field is is null; if this operator is used, the "value" may be omitted and will be ignored
    • "is_not_null": return results whose value for the field is is not null; if this operator is used, the "value" may be omitted and will be ignored
    • "eq": return results whose value for the field is equal to the "value" specified
    • "ne": return results whose value for the field is not equal to the "value" specified
    • "gt": return results whose value for the field is greater than the "value" specified
    • "lt": return results whose value for the field is less than the "value" specified
    • "ge": return results whose value for the field is greater than or equal to the "value" specified
    • "le": return results whose value for the field is less than or equal to the "value" specified
    • "like": return results whose value for the field matches the specified "value" using a "like" condition (case sensitive); the % character may be used as a wildcard
    • "ilike": return results whose value for the field matches the specified "value" using a "like" condition (case insensitive); the % character may be used as a wildcard

Filter Examples​

Retrieve the conjunctions from a screening whose Probability of Collision is greater than or equal to 5e-10:

cdms = client.screening.list_conjunctions(
    screening_id,
    filters=[
        {"field": "collision_probability", "op": "ge", "value": 5e-10},
    ]
)

Retrieve the conjunctions from a screening whose Probability of Collision is null and whose Miss Distance is less then 1 kilometer:

cdms = client.screening.list_conjunctions(
    screening_id,
    filters=[
        {"field": "collision_probability", "op": "is_null"},
        {"field": "miss_distance_km", "op": "le", "value": 1.0},
    ]
)

Retrieve screenings whose status is SUCCESS:

cdms = client.screening.list_screenings(
    filters=[
        {"field": "status", "op": "eq", "value": "SUCCESS"},
    ]
)

Sorting​

Listing functions can also return the results sorted by any field on the model. This can be accomplished using the sort_field and sort_direction parameters. For example:

Retrieve screenings sorted by created_at in ascending order:

cdms = client.screening.list_screenings(
    sort_field="created_at",
    sort_direction="asc"
)

Retrieve the conjunctions from a screening sorted by Probability of Collision descending:

cdms = client.screening.list_conjunctions(
    screening_id,
    sort_field="collision_probability",
    sort_direction="desc"
)

Sorting and Filtering Together​

Of course, sorting and filtering can be used in the same request. For example:

Retrieve the conjunctions from a screening whose Probability of Collision is greater than or equal to 5e-10, sorted by Probability of Collision descending:

cdms = client.screening.list_conjunctions(
    screening_id,
    filters=[
        {"field": "collision_probability", "op": "ge", "value": 5e-10},
    ],
    sort_field="collision_probability",
    sort_direction="desc"
)