List Query Filters

The model_list query field generated for each model supports building arbitrarily complex filters with the filter argument.

The filter argument takes a list of lists of filter item structures. Each filter item in a list is combined with AND. Each list of filter items is combined with OR. As a shortcut, GraphQL will wrap a single item in the two lists implicitly.

Each filter item has the following keys:

  • path, a column name on the model being queried, or a dotted path that can access columns through one or more relationships from the initial model.

  • op, an operator name, which is dependant on the column’s type. See the next section for the default operators.

  • not, an optional boolean to negate the filter. For example, the eq op can be turned into not eq without needing to define a separate operator.

  • value, the value to filter on. In simple cases, this will be a single value, but some operators like eq support a list of values as a shortcut to specifying multiple filter items. It can be arbitrary JSON data to support anything custom operators might use.

Operators

Different filter operations are available depending on the type of the column. The filters.type_ops data structure maps SQLAlchemy types to operation names to functions that apply the operation.

  • String

    • eq, exact equality. Accepts a single value or list.

    • like, case-insensitive partial match. Accepts a single value or list. SQL wildcard characters are escaped.

  • Integer, Float, DateTime

    • eq, exact equality. Accepts a single value or list.

    • lt, less than a single value.

    • le, less than or equal to a single value.

    • ge, greater than or equal to a single value.

    • gt, greater than a single value.

  • Boolean

    • eq, true or false.

  • DateTime

    • eq, exact equality. Accepts a single value or list.

Custom Operators

You can add operators for other types, or add to the operators for an existing type, by modifying the filter.type_ops structure. An operator function takes the SQLAlchemy column being filtered, and the list of values (will be a list even if a single value was given), and should return a SQLAlchemy expression that can be used with WHERE.