Searching

Craft includes a system-wide search index used for finding elements via keywords. Search is supported wherever you see this field in the control panel:

Search Bar

Anything you type into this bar is also a valid query when searching from code:

Twig
GraphQL
PHP

{% set results = craft.entries()
  .search('foo')
  .all() %}

# Supported Syntaxes

Craft supports the following syntax wherever you happen to search from:

Searching for…	will find elements…
`salty`	with any attribute or field containing “salty”.
`salty dog`	with any single attribute or field containing both “salty” and “dog”.
`salty OR dog`	with attributes or fields containing either “salty” or “dog” (or both).
`salty -dog`	with any single attribute or field containing “salty” but not “dog”.
`"salty dog"`	with any single attribute or field containing the exact phrase “salty dog”.
`body:salty`	where the `body` field contains “salty”.
`body:salty body:dog`	where the `body` field contains both “salty” and “dog”.
`body:salty OR body:dog`	where the `body` field contains either “salty” or “dog”.
`body:salty -body:dog`	where the `body` field contains “salty” but not “dog”.
`body:"salty dog"`	where the `body` field contains the exact phrase “salty dog”.
`body::salty`	where the `body` field is set to “salty” and nothing more.
`body::"salty dog"`	where the `body` field is set to “salty dog” and nothing more.

If you are not seeing the expected results, make sure your field is set up for indexing and that the index has been rebuilt to reflect those changes.

Searches are tokenized into terms for matching and scoring. Without any special modifiers (quotes, operators, or attributes), a query is assumed to be a single term, meaning all words must be present within the same attribute to match.

For example, the query salty dog matches elements with both words in the same attribute or field, but not elements with salty in one field and dog in another. The order of individual words is not enforced, unless the term appears in quotes.

When a query is tokenized into multiple terms, Craft treats them as through they were joined by an implicit AND operator.

# Wildcard Syntax

You can use a wildcard character (*) to modify search behavior:

Searching for…	will find elements…
`*ty`	containing a word that ends with “ty”.
`alt`	containing a word that contains “alt”.
`body:*ty`	where the `body` field contains a word that ends with “ty”.
`body:alt`	where the `body` field contains a word that contains “alt”.
`body::salty*`	where the `body` field begins with “salty”.
`body::*dog`	where the `body` field ends with “dog”.
`body:*`	where the `body` field contains any value.
`-body:*`	where the `body` field is empty.

Use the defaultSearchTermOptions config setting to adjust default search behavior.

# Searching for Specific Element Attributes

Assets, categories, entries, users, and tags each support their own set of additional attributes to search against:

Element	Additional Search Attributes
Assets	`filename` `extension` `kind`
Categories	`title` `slug`
Entries	`title` `slug`
Users	`username` `firstname` `lastname` `fullname` (firstname + lastname) `email`
Tags	`title`

Searching is a great way to quickly find content by keywords—but the most reliable way to directly query against attributes and custom fields is via the element type’s query parameters.

# Element-Specific Attribute Search Examples

If you wanted to search only for Assets that are images, it would look like this in the control panel:

The same search from your code:

Twig
GraphQL
PHP

{% set images = craft.assets()
  .search('kind:image')
  .all() %}

Querying elements by specific attribute or field values is more efficient when using dedicated methods. The above is equivalent to:

{% set images = craft.assets()
  .kind('image')
  .all() %}

This can still be combined with keyword search, and will often support more explicit and flexible arguments.

If you were to search for Users with email addresses ending in @craftcms.com, it would look like this in the control panel:

The same search from your code:

Twig
GraphQL
PHP

{% set users = craft.users()
  .search('email:@craftcms.com')
  .all() %}

As with the first example, this query could be simplified with the native .email() query param:

{% set team = craft.users()
  .email('*@craftcms.com')
  .all() %}

Clicking the icon inside the right edge of the search field opens a filter HUD:

You can add any number of conditions to further limit search results by those criteria.

# Development

craft.assets(), craft.entries(), craft.tags(), and craft.users() support a search parameter you can use to filter their elements by a given search query.

Queries don’t have to be static, though—suppose you wanted to let users define keywords:

Twig
PHP

{# Get the user’s search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}

{# Fetch entries that match the search query #}
{% set results = craft.entries()
  .search(searchQuery)
  .all() %}

See our Search Form (opens new window) article for a complete example of listing dynamic search results.

When using the search param, each returned element will be have its searchScore attribute populated with a value representing how well the query matched.

Passing user input to the search param is generally safe, but may allow discovery or enumeration of otherwise hidden field values. For instance, a savvy user might supply a query like myPrivateNotesField:"*" to test whether a field exists or has a specific value. Carefully auditing which if your fields are indexed will help prevent unwanted disclosure.

# Ordering Results by Score

Pass the special 'score' value to order results from best-match to worst-match:

Twig
GraphQL
PHP

{% set results = craft.entries()
  .search('foo')
  .orderBy('score')
  .all() %}

Keep in mind that unlike most other columns, the implicit order for score is descending. If you need to invert the order for any reason, explicitly pass score ASC, or use the inReverse() method.

# Scoring Algorithm

Craft uses its own algorithm to score search results, which takes into consideration each “term” from the query and the complete text of a matched attribute.

All scores start at zero.
Scores for an element are totaled across rows.
Rows are scored against individual terms, using a weight of 1.
- Explicit “exact attribute” matches (terms using double-colons ::) do not contribute to scores, as every result is a known match, already;
- A base score is determined by how many times a term appears in a row’s keywords;
- Base scores are divided by the number of keywords in a row;
- Regular matches are given a 50x multiplier;
- Partial-word matches get a 10x multiplier;
- Coincidental exact matches are given a 100x multiplier;
- Matches for the title attribute are given an additional 5x multiplier;
Rows are scored against term groups (using the OR operator), wherein the weight of each term is divided by the number of terms in the group. Otherwise, scores are calculated the same as individual terms.
A row’s total score is the sum of its individual term and grouped term scores.

For example, if we had two entries titled “Salty Dog” and “Greyhound” (both of which mention the Greyhound in a custom field), a search for “greyhound” would be scored like this:

Title + Content	Scores	Rounded Total
Salty Dog A salty dog is a cocktail of gin, or vodka, and grapefruit juice, served in a highball glass with a salted rim. The salt is the only difference between a salty dog and a greyhound. Source (opens new window)	Body: 1 match in 35 words, 50x multiplier	1
Greyhound A greyhound is a cocktail consisting of grapefruit juice and gin mixed and served over ice. If the rim of the glass has been salted, the drink is instead called a salty dog. Source (opens new window)	Title: 1 match in 1 word, 5x title multiplier, 100x exact match multiplier Body: 1 match in 33 words, 50x multiplier	502

This is an extreme example—but it shows how quickly exact or near-exact matches can rise to the top of searches. As an exercise, try scoring a search for “salt” against the above content!

# Configuring Custom Fields for Search

Each element type makes basic details, called searchable attributes, available as search keywords. It’s common to search for entries by title, for example, or for users by their name or email address. (We just looked at these in the Searching for Specific Element Attributes table.)

You can configure any custom field to make its content available for search by enabling Use this field’s values as search keywords:

Searchable Checkbox

Indexes are only updated once an element with the field is saved. If you have a large amount of content and users (admin or otherwise) rely heavily on search, consider resaving the elements to populate the index.

For Matrix fields, the top-level Use this field’s values as search keywords setting determines whether any sub-fields will factor into results for the parent—individual fields must also opt-in to indexing for any keywords to be bubbled up.

For relational fields like Assets, Categories, and Entries, the setting determines whether titles of related elements should factor into search results.

# Multi-Instance Fields

When a field is marked as searchable, keywords for all instances of that field on an element are combined into a single index, and their handles are treated as aliases. For example, a plain text field added to a field layout multiple times (with, say, handles summary and byline), Craft does not distinguish which field instance the keywords came from—this means that searching against specific element attributes may produce unexpected results:

Searching for summary:daisy may return entries that included the name Daisy in the byline;
Searching for byline:rose may return entries that mention the flower rose in their summary;

If your application relies on distinct keywords, create individual fields.

# Indexing Criteria

Any time an indexable attribute or field on an element is updated (as indicated by Craft’s change-tracking feature, which powers drafts and revisions), an “Updating search indexes” job is pushed into the queue. Prior versions generate an indexing job whenever an element with any searchable attributes or fields is saved, regardless of whether or not those specific attributes changed.

The eligible properties differ for each element type, the field layout a given element uses, and which of the underlying fields are flagged as searchable.

# Searching Nested Elements

In Craft 5, entry queries return nested elements, by default. To search only for entries that belong to a section (those that are not owned by another entry), use the .section() param:

{% set results = craft.entries()
  .section(['news', 'resources'])
  .search(terms)
  .orderBy('score')
  .all() %}

If you want entries in any section, and would prefer to not maintain a list of specific sections (or excluded sections, with .section(['not', 'home', 'suppliers'])) in your template, pass an asterisk 5.2.0+ (*):

{% set results = craft.entries()
  .section('*')
  .search(terms)
  .orderBy('score')
  .all() %}

# Rebuilding Your Search Indexes

Craft does its best to keep its search indexes as up-to-date as possible, but there are a couple things that might render portions of them inaccurate. If you suspect your search indexes are out of date, you can have Craft rebuild them by bulk-resaving entries with the resave/entries command and including the --update-search-index flag:

php craft resave/entries --update-search-index

You can specify which entries should be resaved with the --section and --type options, among others. Run craft help resave/entries to see all supported options, or craft help resave for a list of commands for resaving other element types.

# Extending Search

You can modify both the indexing and scoring of results, programmatically.

# Customizing the Index

Craft generates keywords for element attributes and custom fields based on its understanding of their data types. Each element and field type also have an opportunity to customize keywords: Assets index their filename, extension, and kind attributes; relational fields load the attached elements and concatenate their titles.

Keywords can come in virtually any form, because Craft normalizes (opens new window) them before adding them to the index. You can supplant or augment keywords (or index additional attributes—real or virtual) by listening to specific search events.

Do not modify records in the searchindex table, directly. Rows are cleared and rebuilt every time an element is saved, so changes made outside of the normal indexing process will be lost.

# Different Keywords

To replace keywords for an existing attribute or field (or prevent something from being indexed, entirely), listen for the craft\services\Search::EVENT_BEFORE_INDEX_KEYWORDS (opens new window) event:

use yii\base\Event;
use craft\services\Search;
use craft\events\IndexKeywordsEvent;
use craft\helpers\StringHelper;

Event::on(
    Search::class,
    Search::EVENT_BEFORE_INDEX_KEYWORDS,
    function(IndexKeywordsEvent $e) {
        // Element being indexed:
        $element = $e->element;

        // Current attribute name:
        $attribute = $e->attribute;

        // Field ID, if indexing a custom field:
        $fieldId = $e->fieldId;

        // Keywords that will be indexed:
        $keywords = $e->keywords;

        // Overwrite the keywords (say, to remove common typos)...
        $e->keywords = StringHelper::replaceAll($e->keywords, ['speling', 'wirds', 'typox'], '', false);

        // ...or outright prevent something from being added to the index:
        if (StringHelper::contains($e->keywords, 'naughty words', false)) {
            $e->isValid = false;
        }
    }
);

At this point, $e->keywords is a space-separated list of terms, ready to be inserted into the index.

# Additional Attributes

Adding searchable attributes is done via the craft\base\Element::EVENT_REGISTER_SEARCHABLE_ATTRIBUTES (opens new window) and craft\base\Element::EVENT_DEFINE_KEYWORDS (opens new window) events:

use yii\base\Event;
use craft\elements\Entry;
use craft\events\DefineAttributeKeywordsEvent;
use craft\events\RegisterElementSearchableAttributesEvent;

Event::on(
    Entry::class,
    Entry::EVENT_REGISTER_SEARCHABLE_ATTRIBUTES,
    function(RegisterElementSearchableAttributesEvent $e) {
      // Add a new `author` search attribute:
      $e->attributes[] = 'author';
    }
);

Event::on(
    Entry::class,
    Entry::EVENT_DEFINE_KEYWORDS,
    function (DefineAttributeKeywordsEvent $e) {
        if ($e->attribute === 'author') {
            // Let Craft know that we’ve been able to set custom keywords:
            $e->handled = true;

            // You can set almost anything as keywords, and let Craft figure out how to normalize it...
            $e->keywords = $e->sender->getAuthor();

            // ...or do something more explicit:
            if ($author = $e->sender->getAuthor()) {
                $e->keywords = $author->getFullName();
            }
        }
    }
);

Your custom search attributes don’t have to exist on an element to be indexed! As long as you handle the generation of keywords, Craft will treat them the same as any other attribute or custom field.

# Altering Scores

To alter the search score assigned by Craft, listen for the craft\services\Search::EVENT_AFTER_SEARCH (opens new window) event from a plugin or module:

Basics
Example A
Example B

use yii\base\Event;
use craft\events\SearchEvent;
use craft\helpers\StringHelper;
use craft\services\Search;

Event::on(
    Search::class,
    Search::EVENT_AFTER_SEARCH,
    function(SearchEvent $e) {
        // Original ElementQuery instance:
        $elementQuery = $e->elementQuery;

        // SearchQuery instance, with parsed tokens:
        $query = $e->query;

        // Site(s) the search was performed in:
        $siteId = $e->siteId;

        // Raw index matches (there may be multiple rows per element):
        $results = $e->results;

        // Corresponding element score totals, indexed by element ID:
        $scores = $e->scores;
    }
);

Keep in mind that element IDs may not be stable between environments, so you may need to look it up (with an Element Query) or store it as an environment variable!

Searching

# Supported Syntaxes

# Wildcard Syntax

# Searching for Specific Element Attributes

# Element-Specific Attribute Search Examples

# Search Filters

# Development

# Ordering Results by Score

# Scoring Algorithm

# Configuring Custom Fields for Search

# Multi-Instance Fields

# Indexing Criteria

# Searching Nested Elements

# Rebuilding Your Search Indexes

# Extending Search

# Customizing the Index

# Different Keywords

# Additional Attributes

# Altering Scores

Was this page helpful?