CiviCRM

Searching

This chapter covers different ways to find information you've stored in CiviCRM. Two of the techniques in this chapter - finding contacts and the "search-action" workflow, described in the second bullet below - are core functions in CiviCRM, so most if not all users will find this chapter helpful.

We will start off with some simple searches and then move on to more advanced techniques. CiviCRM beginners should be familiar with Quick search, Advanced search and the component searches. More advanced users should also look at reports, custom searches and search builder. 

There are three main reasons to search:

  • To find a specific contact: the Quick search box can find contacts by name or email address, and an Advanced search can find contacts by other characteristics.
  • To perform an action on a contact/contacts that meets certain criteria: a common workflow in CiviCRM, called a "search-action", is to find contacts that meet certain criteria and then perform an action on them. For example, you might want to find all contacts in the advisory group in order to invite them to a meeting, find all those whose memberships have recently expired to send a renewal reminder, or find all contacts aged under 25 in a specific location to send them an email about an upcoming event nearby.
  • To do a form of ad-hoc reporting.

For reports, searching is often useful but has limitations. For example, you can't group results by particular criteria, summarise, or easily produce graphs of the results. For more advanced reporting, read about CiviReport in the section Reporting.

Note that when you search for character strings, the search is not case-sensitive. For example, if you search for 'brooklyn', the search will return strings with capitalised letters if the string exists, e.g. 'Brooklyn' or 'BROOKLYN'.

Quick search for contacts

The easiest way to find a specific contact, if you know part of their name or email address, is to use the Quick search box that appears in the navigation menu at the top left of the screen. Contacts that match the phrase you enter will appear in a dropdown list below the box. For example, entering "peter" will find

  • people who's first or last name is Peter
  • people who have Peter appearing as part of their name, e.g. Mary Peterson
  • people who have Peter as part of their email address, e.g. peter@gmail.com   
  • organisations with Peter in their name, e.g. Petersfield Community Centre.

You don't need to type the full name of the person - just the first few letters. The following screenshot shows that two contacts turn up in our database when we search just for "pe".

quicksearch 

Advanced search

Advanced search allows you to search across all the information you have about your contacts. For example, you could find "all contacts in Venezuela" or "all advisory group members". If you specify two or more categories of information, the search displays every contact that matches all the categories. For instance, you can combine the two criteria just mentioned to find "all advisory group members in Venezuela".

The Advanced search screen is accessible from the navigation menu Search > Find Contacts > Advanced Search. On this screen, search criteria are grouped into sections which refer to different types of data that you can search on, such as address data, notes and information from components such as Contributions or Events. Each group of criteria is shown as a gray bar. If you click on a gray bar, it expands to reveal the options within that group. For example, if you want to search for all people in your database from 16 to 18 years old, click on the Demographics bar. It expands, as shown in the following figure, and you can specify the birth date range you are interested in.

AdvSearch

Combining search criteria

Different criteria are combined by "ANDing" them. For example, if you select the tag "major donor" and the country "Mexico", the search will return major donors from Mexico.  The search will not return major donors who are not from Mexico, nor those from Mexico who are not major donors.

Within criteria groups that allow you to check boxes for more than one value, these options are also combined by "ANDing". For example, if you can search for contacts whose Preferred Communication Method is both Email AND SMS.

With fields that allow you to select values from a dropdown list, options are combined by "ORing". For example, you could find contacts that live in Mexico OR the United States by selecting both countries in the country field. 

Display Advanced Search results as... 

Advanced Search returns your results as Contact records by default. However, you may want to get another record type instead. For example, you may want to see all the Contribution records which match your search criteria (while taking advantage of the rich set of search filters available in Advanced Search). Simply select the record type you want from the dropdown in the upper right corner of the Advanced Search form.

Modifying search columns

Advanced searches allow you to use to change the columns displayed in your search results. The default columns are Name, Street Address, City, State, Postal Code, Country, Email and Phone. If you want to display a different set of columns (perhaps to include a custom field or remove a column you don't need), create a Profile with the Search Results option selected. Make sure that the fields in this Profile are set to "Public User Pages and Listings" visibility, and are marked as Results Columns. (For more information about creating Profiles, which are described in detail in the Profiles chapter in the Configuration section.)

The Profile will appear in the Search Views dropdown menu in the upper right corner of the form, as shown below. The following screenshot shows what the menu displays after someone has created a Profile called "Birthday".

Search_prifleFields

Combining this feature with the "Batch Update via Profile" action provides a powerful method of viewing and updating a specific set of fields across a batch of contact records.

Using groups in a search

When using Advanced Search, if you select several groups in the Group list near the top, it will treat the search as an OR search, and return results for contacts who are in any of the groups you select. If you want to find contacts who belong to all of the selected groups, you will need to use Search Builder. 

There is also a very useful built-in custom search, "Include/Exclude Contacts in a Group/Tag", that enables you to find contacts who are in one group but not in another, which you can find by going to Search > Custom Searches in the navigation menu.

Groups_searchIncExc 

Instant view pop-up 

You can see a pop-up box with detailed information for any contact listed in your search results by hovering over the contact icon in the left column, as shown below. You can adjust the fields shown in this "pop-up view" by modifying the fields included in the "Summary Overlay" profile (Administer > Customize > CiviCRM Profile).

Search_summaryOverlay

The "search-action" workflow

After you retrieve your search results, you can perform a number of actions. An Actions box appears above the results. You can select either all records or specific records, then carry out an action with the selected records. Different actions are covered in more detail in the chapter on Everyday Tasks.

Search_resultsactions

Some of the most commonly used actions are Add Contacts to Group, Export Contacts, Map Contacts, and creating and printing Mailing Labels. (To use Map Contacts, you will need to configure Mapping and Geocoding. You can read more about this in the Installation chapter of the Configuration section of this manual).

For example, to send email to a selected  number of contacts, mark the contacts you are interested in and then select Send Email to Contacts in the dropdown list of actions. 

The wildcard (%)

Understanding wildcards greatly expands your search options. A wildcard represents any character (letter, numeral or punctuation mark). In CiviCRM, the wildcard is represented by the % symbol (you may be familiar with other symbols such as * from other applications). It is most easily understood through examples.

Suppose that somebody asked you to find a contact with a first name similar to "Michael", but possible something different such as "Michelle" or "Michał". If you search for "Mich%" you will find all these variations, including a contact who is supposed to be named "Michael" but whose name was misspelled as "Micheal". Wildcards can be used before, after, or even within words. For example, searching on 'Mich%el' will exclude "Michał" and "Micheal" but still find "Michelle" and "Michael".  

This search is not case sensitive. Entering "mi%el" in lowercase will also find contacts with an upper case 'M' in their name.

Component searching

Most CiviCRM components offer a search on the data they maintain, such as Find contributions, Find members, etc. These forms work in a similar way to Advanced search but return rows of the main objects associated with the components, instead of contacts. Find Members returns memberships, Find Participants shows event registrations, Find Contributions returns contributions and so on.

Each component search has its own Action list. See the Component sections for more details.

Search Builder

Advanced search lets you choose from a wide range of criteria, but it has limitations. The main limitation is that the search criteria you enter into different fields are "ANDed" together.

The Search Builder tool provides an alternative for situations when you need to search using OR for some criteria. For example, you can build a search for contacts who are born within a range of dates OR who are female. To do this, access the Search Builder tool and Edit Search Criteria from the navigation menu: Search > Search Builder. 

To AND criteria (which means to find results matching all criteria specified), click Another search field and enter criteria under Include contacts where. To OR criteria (which means to find results matching either one OR the other criterion), enter one criterion in Include contacts where and the other under Also include contacts where

SearchBuilder

Search Builder is intended for advanced users and requires you to use specific formats for your search values. 

Fuzzy Matches

If you want to search on partial names or other incomplete phrases - use the LIKE operator, and use the % symbol before or after your search term. For example, to find contacts whose last name begins with "Gree":
Record Type    Field    Operator    Value
Individuals    Last Name    LIKE    Gree%

Search Builder requires special values when matching on values which are stored as keys in the data. This includes Groups, Tags, States, Countries, yes/no (boolean) fields and multiple-choice custom fields. Specific date formats are also required.

The following list describes what format you need to use to search for specific terms.

Group - The Group ID. Find this integer value by checking the gid= value in the Members link for the group (from Manage Groups)
Tag    - The Tag ID. Find this integer value by checking the id= value in the Edit link from Administer CiviCRM » Tags
State - Either the full state name (e.g. 'California') OR the state_province ID (e.g. 1004). Find the ID by viewing the HTML source for the State select field while editing a contact.
Country - Either the full exact country name as stored in the CiviCRM database (e.g. 'United States') OR the country ID (e.g. 1228). Find the ID by viewing the HTML source for the Country select field while editing a contact.
Dates - Use YYYYMMDD format. Example: Enter August 18, 2006 as 20060818
Yes/No Checkboxes - This covers fields like DO NOT EMAIL, IS DECEASED, etc. Use a 1 for Yes and a 0 for No
Multiple Choice Custom Fields - Use the Option Value you assigned when creating the Multiple Choice selections. This may not be the same as the displayed value - as the Option Label is displayed in select fields and when viewing the contact record.

You can search for matches on multiple Groups, Tags or other ID values using the IN operator. For example, if you want to find contacts who are members of either the Newsletter Subscribers group (Group ID=1) or the Advisory Board group (Group ID=3), you could enter:

Individuals -> Group(s) -> IN -> (1,3)  Remember to Surround your set of values with parentheses, and do NOT use spaces between the comma-separated values.

Just like other searches, you can save your Search Builder search as a Smart Group. For more information on Smart Groups, see the Groups and Tags chapter.

custom search

Custom searches are designed to answer specific questions that can't be easily answered using Advanced Search or Search Builder

Go to Search > Custom Search in the navigation menu and look at the list of available custom searches. These customised searches have been written by members of the CiviCRM community to meet their own needs, and then contributed back to the community to share with others who need the same or similar custom searches. It's worth spending some time exploring these searches as some may be useful to you, and they will give you an idea of the sorts of things that are possible.

A good example is the Include/Exclude Contacts in a Group/Tag.

By combining Include and Exclude options, you can find contacts who are in one group but remove just the group members who fit another criterion. For example, you may want to find all the contacts who are Newsletter Subscribers but exclude members of Advisory Board, perhaps to create a new mailing list to receive a message targeted at the most external circle of your constituents. 


There are many additional custom searches created for various purposes, including a search on aggregate contributions of contacts, a search on contacts within X miles/kilometers of a certain geographical area, and more. Here's a short description of the custom searches available.

Contribution Aggregate: find aggregate totals of contributions from contacts within a range of dates.

Basic Search: search on contacts by contact type, group, and/or tag

Household Name and State: search households in a U.S. state

Postal Mailing: search for contacts in a given group and results display with mailing information. Use this search to batch update contact information, send an email, export contacts, or other actions. 

Proximity Search:search for contacts located within x miles/kilometres of a  specific geographical area.

  1. Go to Search > Custom Searches > Proximity Search
  2. Enter the distance in miles or kilometres.
  3. Enter the country within which you want to search.
  4. Enter any other parameters you wish to give your search.
  5. Click Search.

Contributions made in Year X and not Year Y: search for contributions that have been made in one year but not another; this is useful for following up semi-regular donors and encouraging them to donate more regularly.

  1. Go to Search > Custom Search > Contributions made in Year X and not Year Y
  2. None of the fields are required; you can choose whether to search a specified amount range as well as a time period, and whether you want to exclude minimum or maximum amounts.

Find Contribution Amounts by Tag: search on any tag for contributions within a range of dates.

Event Aggregate: search on event-related payments for a given event and

Price Set Details for Event Participants: get detailed information about which participants opted for which different paid options related to an event. For example, see who paid just the event fee, who paid for the additional workshop, and who paid for dinner.

Find contacts in a specified zip code or postal code range. This is useful for targeted mailings or conducting surveys in a particular geographical area.

  1. Go to Search > Custom Searches > Zip Code Range Search.
  2. Enter the start and end range of the zip or postal codes.
  3. Click Search.

Search for contacts that have been added within a particular time period.

Checking this box allows you to enter multiple sets of values for a given contact.

Custom Group Multiple Values Listing: a special search for custom data best illustrated with the following example:

Checking this box allows you to enter multiple sets of values for a given contact.

EXAMPLE: When creating a set of custom fields used to collectEmployment History - you might have fields for Job Title, Start Date, End Date, and Reason for Leaving. Checking the "multiple records" box allows you to collect information for multiple jobs.

You can also set the maximum number of records which can be recorded per contact. Using the previous example, you might only want data for the three most recent jobs.

CAUTION: The following features are NOT available for custom fields in 'multiple record' custom set:

  • These fields can not be used in Profiles
  • They can not be Imported or Exported
  • If they are included in a report as a display column, only the first set of values are shown.

It is possible to write your own custom searches, but you'll need to be comfortable with MySQL and PHP. See the CiviCRM Developer Guide for more information about how to do this. If you create a custom search that you think could be useful for others, consider contributing it back to the community.

Please note: Documentation is needed for each of the custom searches. If you are developing additional custom searches, please contribute them with accompanying documentation so others will be able to take advantage of the functionality you have added.