Search kit is a new search interface which as of writing (5.36) is
in beta mode. It ships as an extension when you can enable on
the extensions screen in releases from 5.29 onwards. However it has
developed rapidly and we strongly recommend that if you are exploring
it you do so on the latest version of CiviCRM. The functionality
that is in this section is based on CiviCRM 5.36 and may not
be present in earlier versions. It may also change visually.
Search Kit is a new search interface to provide a more intuitive and powerful search than older CiviCRM search tools. Searches can be saved; have any number of unique displays on their own or connected to the dashboard or contact screen; have exposed filters for easy filtering; and even be connected to a Smart Group.
It ships as an extension which you can enable on the Extensions screen from 5.29 onwards. Once enabled it can be found under the menu **Search > Search Kit**.
!!! note
Search kit ships as an extension as part of our strategy of
putting significant functionality leaps into extensions rather than
overhauling existing code. This allows us to demarcate rapidly evolving
code and to keep long-standing code more stable. People can opt into
the extension or not. However it is maintained as part of core against
the specific release it ships with (as it is closely tied to apiv4
functionality).
Search Kit ships as an extension as part of our strategy of
putting significant functionality leaps into extensions rather than
overhauling existing code. This allows us to demarcate rapidly evolving
code and to keep long-standing code more stable. People can opt into
the extension or not. However, it is maintained as part of core against
the specific release it ships with (as it is closely tied to API v4
functionality).
## Search components
There are 3 components to search kit. Depending on what you are doing you
may not use all 3
There are 3 components to Search Kit: search screen, displays and forms. Depending on what you are doing you may not use all 3.
1. The search screen
1. The Search screen (or Compose Search):
this is where the search criteria and available fields are configured
This is where the search criteria and available fields are configured.
2.Search displays
2.Displays
a search can have no search displays or it can have one or multiple.
search displays currently available are table views, list views or smart
groups
Displays are optional. One or more can be added to a saved search. Search displays
currently available are table views, list views, grid views, or smart groups.
3.Search form
3.Forms
in order to add a search form it is necessary to have the form
builder (afform gui) extension that ships with core enabled.
Forms allow a search to be displayed with exposed filters on a custom path, or
in the dashboard or a contact screen. Note that, in order to add a form it is necessary to
enable the _Form Builder_ (Afform GUI) extension that ships with core.
## The search screen
The search screen is reached from the search listing page (Search->Search Kit)
The search screen is reached from the search listing page (**Search > Search Kit**)
The search screen allows you to specify the entity that you wish to start
from, any entities you wish to include, how you want to filter, group
from; any entities you wish to also include; how you want to filter; group
and order the results and which field you wish to display. You are also
able to take actions directly on the results. As of 5.36 most entities
have only limited actions but the update action is much more powerful
than the batch update action in advanced search as it does not have a
hard limit on the rows which can be updated at once.
able to take actions directly on the results, such as: download as a spreadsheet,
tag, add to group, create mailing labels, update multiple contacts, and so on.
(Unlike Advanced Search, Search Kit does not have a hard limit on the rows which can be updated at once.)
When searching the first thing you need to select is the entity you wish
to search for. Commonly used entities are
to search for. Some commonly used entities include:
- Contacts
- Activities
- Contributions
- Recurring contributions
- Events
- Memberships
- Participants
- Grants
However, you will normally use the 'with' field to include more than one entity. Let's say you want to find all donors who made a donation of at least $100 but have never made a campaign contribution.
Use the 'With' field to "chain" entities together. In SQL query language these 'with' entities are Joins.
The following example shows how to find all donors who made a donation of at least $100 but have never made a campaign contribution.
First choose to search for contacts.
First you would choose to search for contacts
Next you would add that the contacts you are looking for MUST have
a contribution of $100 or more.
Next chain Contacts to Contact Contributions with the condition of contributions of $100 or more.
...
...
@@ -79,97 +76,98 @@ contacts with contributions that match the criteria specified when we
add the contributions table. In this case the criteria is total amount
of the contribution is greater than or equal to $100.
At this point it's helpful to see the results so far and at the bottom of the
page you can choose to search and to add fields that help you to sanity
check your result
At this point it's helpful to check the results. At the bottom of the
page click search to see the results thus far. Click Add to add fields that help you to sanity
check your result.
To exclude contacts who have made a campaign contribution we need
to add this second description of contributions in with another 'with'.
In sql language these 'with' entities are joins. To add in a second
set of contributions we choose contributions in the 'with' box
again but scroll down to pick 'Contributions 2'. In this case it is
optional (in fact we want to exclude them) and we filter on
Now we're ready to exclude contacts who have made a campaign contribution. Add a second
entity which shows up as "Contact Contributions 2" under "With". Search Kit automatically numbers
additional entities of the same type so multiple ones can be added in the same search.
In this case we make Contact Contributions 2 option so we can exclude them. We filter on
'Campaign ID' is NOT empty. When adding this field be very careful to select
it from the second contribution table. We also need to select the
opposite criteria to what we want to know about (ie we want to know about
those don't have campaign contributions so we we say with
contributions with campaigns and then filter them out).
opposite criteria to what we want to know about. That is, we want to know about
those _don't_ have campaign contributions so we first include contributions with campaigns and then later filter them out.
To actually exclude them we ALSO need to add
a where clause of 'contribution id is empty'. As with the previous
action we need to scroll down to contribution 2.
To actually exclude them we also need to add
a "Where" clause of Contribution ID "is Empty" to filter out the results of the entire search.
Both the saved search and the search display names are 'my_contributions' in this example.
A few notes about URL filters:
1) The field needs to be exposed in the search (but not necessarily the search display) to be available for filtering.
2) If the field is already filtered (e.g receive date before this week) then the URL filter will further narrow down the results rather than replace the existing filter.
3) When the field has a `:` in it that indicates that the field is a 'pseudoconstant'. The underlying database value is generally
a number which maps to a name and label. In this case the database field `payment_instrument_id` is a number. In some cases we know the number instead, in which case we could use `payment_instrument_id=1` in our URL or `payment_instrument_id:name=Cash`. This variant is more useful for implementers who work with multiple sites.
4) For dates we can use the following formats
-`receive_date=2021-09-23`
-`receive_date=20210923`
-`receive_date=20210923234040` (ie time is 23:40:40)
-`receive_date=20210923234040` (i.e. time is 23:40:40)
-`receive_date=this.month` (See [the list](../searching/relative-date-formats.md))
## Forms
## Search forms
Search forms are forms that can be exposed as web pages
or as dashlets (in future other options will exist). They
can have exposed filters. For example
Search forms enable exposed filters to be added to displays. Search forms (with the display) can be standalone web pages,
dashlets, summary on the Contact Summary Page, or as Email Tokens. For example:
