Skip to content

Search Kit - Query Building with APIv4

Entities

Any APIv4 entity can be made available to Search Kit. Even nontraditional entities that do not correspond to a SQL table will work as long as they have a get action.

Searchability

Whether an entity appears in Search Kit depends on the @searchable annotation at the top of the API entity class (if not present the entity defaults to "secondary"):

  • @searchable primary: Appears at top of main entity list in Search Kit.
  • @searchable secondary (default): Appears in "Other" section at bottom of entity list.
  • @searchable bridge: Does not appear in entity list but Search Kit will use it to join other entities together.
  • @searchable none: Does not appear anywhere in Search Kit.

Joins

Search Kit automatically builds a list of entities that can be joined, based on foreign-keys from the schema. When the user selects a join in the admin UI, the criteria for linking those entities is invisibly added.

Option Lists

APIv4 supports a syntax for resolving option lists based on suffixes, for example selecting activity_type_id:label will return "Meeting" instead of the id 1. The Search Kit UI invisibly adds the :label suffix to every field with an option list so that results are returned formatted for display.

The SearchDisplay::run API

SearchDisplay results are loaded indirectly via the SearchDisplay::run API. This gives Search Kit more control of the permission model, and the chance to add filters.