For searching in repositories we are using searchCriteriaInterface but i noticed sometimes we are using SearchCriteriaBuilder as well.

In which case we should use searchCriteriaBuilder? What's the use of searchResult? When should we use it?

Any help would be appreciated.

  • Have you got an idea & difference? Commented May 2, 2019 at 9:28
  • Hi Chirag, Thanks for your answer. I appreciate your help. Things you mentioned i already know. I wanted to know when should we use searchCriteriaBuilder and When should we use SearchCriteriaInterface? Commented May 2, 2019 at 12:06
  • 1
    As i explain we use SearchCriteriaInterface to get search collection using getList(SearchCriteria $searchCriteria) function. and we build specific search criteria using searchCriteriaBuilder and this specific search is pass to getList() function to get search reasult. Commented May 2, 2019 at 12:48
  • 1
    Thank you Chirag! Commented May 31, 2021 at 18:44

1 Answer 1


As per my understanding, I will give an explanation about SearchCriteria, Search result, searchCriteriaBuilder in below.

Search Criteria:

A Search Criteria is an implementation of the SearchCriteriaInterface class that allows you to build custom requests with different conditions.

Repositories use this class to retrieve entities based on matching criteria.

  • Filter: The Filter class is the smallest part of the Search Criteria. It allows you to add a custom field, value, and condition type to the criteria.
  • Filter Group: The FilterGroup class acts like a collection of Filters that apply one or more criteria to a search.

The boolean OR statement joins Filters inside a single Filter Group.

The boolean AND statement join Filter Groups inside a Search Criteria.

  • Sorting: To apply to sort to the Search Criteria, use the SortOrder class.
  • Pagination: The setPageSize function paginates the Search Criteria by limiting the number of entities it retrieves:

Search Result:

The getList(SearchCriteria $searchCriteria) method defined in your repository should return a Search Result object. This object is an instance of a class that implements the interface [SearchResultInterface][1]

Search Result objects hold the Search Criteria object and the retrieved entities along with information about the total count of found entities regardless of any limitations set in the criteria.

The search engine determines the maximum number of results that a query can return. For SQL searches, the maximum is the value of the PHP_INT_MAX environment variable. For Elasticsearch, the value is defined in the Elasticsearch/etc/di.xml file. The default is 10000.

SearchCriteriaInterface: Magento\Framework\Api\SearchCriteria

We use searchCriteriaInterface For searching in repositories. for example, we use public function getList(\Magento\Framework\Api\SearchCriteriaInterface $criteria) to model repositories. using searchCriteriaInterface we can use existing search function like setPageSize , getPageSize , getSortOrders , setSortOrders etc..

But when we need to create some extended search then we are using Magento\Framework\Api\SearchCriteriaBuilder using ->create() function.

Using this Create() function we can create searchCriteria Let's take an example of orderRepository :

$searchCriteria = $this->searchCriteriaBuilder
                        'status', $orderStatus, 'eq'
                    'created_at', $date->format('Y-m-d 00:00:00'), 'gteq'
                    'created_at', $date->format('Y-m-d 23:59:59'), 'lteq'

            $orderCollection[] = $this->orderRepository-

In the above example, we apply a filter to search results collection with Orderstatus & Created date.

$this->orderRepository->getList($searchCriteria); call interface(Magento\Sales\Api\OrderRepositoryInterface) method public function getList(\Magento\Framework\Api\SearchCriteriaInterface $searchCriteria); so it will return result our searchCriteria what we have build in above example.

Basically, there are two SearchCriteriaBuilder

  • Magento\Framework\Api\Search\SearchCriteriaBuilder
  • Magento\Framework\Api\SearchCriteriaBuilder

Actually, They build different objects. The Magento\Framework\Api\Search\SearchCriteria which extends the former and it has two additional methods which is below :

 * @return string
public function getRequestName();

 * @param string $requestName
 * @return $this
public function setRequestName($requestName);

This request name is used by UI components to identify the search request. the interfaces in API/Search are meant for actual searches by the user, while the common API/SearchResults and API/SearchCriteria interfaces are used for any repositories.

Here I explain a little bit what I know. It should have may more explanation.

I hope it helps! Thanks.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.