Multi-column search¶

OR filters let you search across multiple columns with a single search term — ideal for powering a table search input in your frontend.

Query Parameters¶

Use search and search_fields to search across columns with OR logic:

GET /heroes/?search=john&search_fields=name,secret_name,email

This generates: WHERE name ILIKE '%john%' OR secret_name ILIKE '%john%' OR email ILIKE '%john%'

A search with several words is split into tokens by default (search_mode=token), and every token has to match at least one field: ?search=john smith&search_fields=first_name,last_name finds "John Smith" even though no single column contains "john smith". Use search_mode=phrase to match the whole string as one value.

Combine with regular AND filters:

GET /heroes/?search=john&search_fields=name,email&field=deleted&operator=eq&value=false

This generates: WHERE (name ILIKE '%john%' OR email ILIKE '%john%') AND deleted = false

Programmatic API¶

Use CommonFilters.multi_field_search() for server-side search:

from fastapi_fsp import CommonFilters

@app.get("/heroes/")
def read_heroes(session: Session = Depends(get_session), fsp: FSPManager = Depends(FSPManager)):
    or_groups = CommonFilters.multi_field_search(
        fields=["name", "secret_name"],
        term="john",
        match_type="contains",  # or "starts_with", "ends_with"
    )
    fsp.with_or_filters(or_groups)
    return fsp.generate_response(select(Hero), session)

Or build OR groups with the FilterBuilder:

from fastapi_fsp import FilterBuilder

or_group = (
    FilterBuilder()
    .where("name").contains("john")
    .where("email").contains("john")
    .build_or_group()
)
fsp.with_or_filters([or_group])

Or create OrFilterGroup objects directly:

from fastapi_fsp import OrFilterGroup, Filter, FilterOperator

group = OrFilterGroup(filters=[
    Filter(field="name", operator=FilterOperator.CONTAINS, value="john"),
    Filter(field="email", operator=FilterOperator.CONTAINS, value="john"),
])
fsp.with_or_filters([group])

Response¶

When OR filters are active, they appear in the response meta:

{
  "meta": {
    "or_filters": [
      {
        "filters": [
          {"field": "name", "operator": "contains", "value": "john"},
          {"field": "email", "operator": "contains", "value": "john"}
        ]
      }
    ]
  }
}

For faster search on PostgreSQL, see search backends.