The representation of a filter in Ash.

Ash filters are stored as nested Ash.Query.BooleanExpression{} and %Ash.Query.Not{} structs, terminating in an operator or a function struct. An expression is simply a boolean operator and the left and right hand side of that operator.

filter-templates

Filter Templates

Filter templates are simplified fielter statements (they only support atom keys), that have substitutions in them. Currently, the substitutions are {:_actor, :field_or_path} and {:_actor, :_primary_key}

You can pass a filter template to build_filter_from_template/2 with an actor, and it will return the new result

Additionally, you can ask if the filter template contains an actor reference via template_references_actor?/1

writing-a-filter

Writing a filter

built-in-predicates

Built In Predicates

• is_nil
• ==
• !=
• in
• <
• >
• <=
• >=
• has
• &&
• ||
• <>
• /
• -
• *
• +
• equals (alias for ==)
• not_equals (alias for !=)
• gt (alias for >)
• lt (alias for <)
• gte (alias for >=)
• lte (alias for <=)
• eq (alias for ==)
• not_eq (alias for !=)
• less_than (alias for <)
• greater_than (alias for >)
• less_than_or_equal (alias for <=)
• greater_than_or_equal (alias for >=)
• and (alias for &&)
• or (alias for ||)
• concat (alias for <>)
• div (alias for /)
• minus (alias for -)
• times (alias for *)
• plus (alias for +)

booleanexpression-syntax

BooleanExpression syntax

The expression syntax ultimately just builds the keyword list style filter, but with lots of conveniences that would be very annoying to do manually.

Examples

Ash.Query.filter(resource, name == "Zardoz")
Ash.Query.filter(resource, first_name == "Zar" and last_name == "Doz")
Ash.Query.filter(resource, first_name == "Zar" and last_name in ["Doz", "Daz"] and high_score > 10)
Ash.Query.filter(resource, first_name == "Zar" or last_name == "Doz" or (high_score > 10 and high_score < -10))

keyword-list-syntax

Keyword list syntax

A filter is a nested keyword list (with some exceptions, like true for everything and false for nothing).

The key is the "predicate" (or "condition") and the value is the parameter. You can use and and or to create nested filters. Data layers can expose custom predicates. Eventually, you will be able to define your own custom predicates, which will be a mechanism for you to attach complex filters supported by the data layer to your queries.

Important In a given keyword list, all predicates are considered to be "ands". So [or: [first_name: "Tom", last_name: "Bombadil"]] doesn't mean 'First name == "tom" or last_name == "bombadil"'. To say that, you want to provide a list of filters, like so: [or: [[first_name: "Tom"], [last_name: "Bombadil"]]]

Some example filters:

Ash.Query.filter(resource, [name: "Zardoz"]))
Ash.Query.filter(resource, [first_name: "Zar", last_name: "Doz"])
Ash.Query.filter(resource, [first_name: "Zar", last_name: [in: ["Doz", "Daz"]], high_score: [greater_than: 10]])
Ash.Query.filter(resource, [or: [
  [first_name: "Zar"],
  [last_name: "Doz"],
  [or: [
    [high_score: [greater_than: 10]]],
    [high_score: [less_than: -10]]
  ]
]])

other-formats

Other formats

Maps are also accepted, as are maps with string keys. Technically, a list of [{"string_key", value}] would also work. If you are using a map with string keys, it is likely that you are parsing input. It is important to note that, before passing a filter supplied from an external source directly to Ash.Query.filter/2, you should first call Ash.Filter.parse_input/2 (or Ash.Filter.parse_input/4 if your query has aggregates/calculations in it). This ensures that the filter only uses public attributes, relationships, aggregates and calculations. You may additionally wish to pass in the query context, in the case that you have calculations that use the provided context.