SearchCriteria

SearchCriteria provides a structured way to build database queries.

SearchCriteria hierarchy:

SearchCriteria
├── FilterGroup[] (AND between groups)
│   └── Filter[] (OR within group)
│       ├── Field
│       ├── Condition Type
│       └── Value
├── SortOrder[]
├── PageSize
└── CurrentPage

Basic SearchCriteria:

use Magento\Framework\Api\SearchCriteriaBuilder;

$searchCriteria = $this->searchCriteriaBuilder->create();

// Get list
$results = $this->postRepository->getList($searchCriteria);

// Process results
foreach ($results->getItems() as $post) {
    echo $post->getTitle();
}

echo 'Total: ' . $results->getTotalCount();

SearchCriteriaBuilder:

$searchCriteria = $this->searchCriteriaBuilder
    ->addFilter('status', 1)
    ->create();

Filters define the WHERE conditions for queries.

Single filter:

$filter = $this->filterBuilder
    ->setField('status')
    ->setConditionType('eq')
    ->setValue(1)
    ->create();

$searchCriteria = $this->searchCriteriaBuilder
    ->addFilter($filter)
    ->create();

Condition types:

'eq'        → = (equal)
'neq'       → != (not equal)
'like'      → LIKE
'finset'    → FIND_IN_SET
'in'        → IN
'nin'       → NOT IN
'gt'        → > (greater than)
'gteq'      → >= (greater than or equal)
'lt'        → < (less than)
'lteq'      → <= (less than or equal)
'null'      → IS NULL
'notnull'   → IS NOT NULL
'between'   → BETWEEN

Multiple filters (OR):

$searchCriteria = $this->searchCriteriaBuilder
    ->addFilter('status', 1)
    ->addFilter('featured', 1)
    ->create();
// WHERE status = 1 OR featured = 1

Multiple filters (AND):

$filterGroup1 = $this->filterGroupBuilder
    ->addFilter($this->filterBuilder->setField('status')->setValue(1)->create())
    ->create();

$filterGroup2 = $this->filterGroupBuilder
    ->addFilter($this->filterBuilder->setField('category_id')->setValue(5)->create())
    ->create();

$searchCriteria = $this->searchCriteriaBuilder
    ->setFilterGroups([$filterGroup1, $filterGroup2])
    ->create();
// WHERE (status = 1) AND (category_id = 5)

Between filter:

$filter = $this->filterBuilder
    ->setField('price')
    ->setConditionType('between')
    ->setValue([10, 100])
    ->create();

Control result ordering and pagination.

Sort order:

$sortOrder = $this->sortOrderBuilder
    ->setField('created_at')
    ->setDirection('DESC')
    ->create();

$searchCriteria = $this->searchCriteriaBuilder
    ->addSortOrder($sortOrder)
    ->create();

Multiple sort orders:

$sortOrder1 = $this->sortOrderBuilder
    ->setField('position')
    ->setDirection('ASC')
    ->create();

$sortOrder2 = $this->sortOrderBuilder
    ->setField('created_at')
    ->setDirection('DESC')
    ->create();

$searchCriteria = $this->searchCriteriaBuilder
    ->addSortOrder($sortOrder1)
    ->addSortOrder($sortOrder2)
    ->create();
// ORDER BY position ASC, created_at DESC

Pagination:

$searchCriteria = $this->searchCriteriaBuilder
    ->setPageSize(20)     // Items per page
    ->setCurrentPage(2)   // Page number
    ->create();

Complete example:

$searchCriteria = $this->searchCriteriaBuilder
    ->addFilter('status', 1)
    ->addSortOrder($this->sortOrderBuilder
        ->setField('created_at')
        ->setDirection('DESC')
        ->create()
    )
    ->setPageSize(20)
    ->setCurrentPage(1)
    ->create();

$results = $this->postRepository->getList($searchCriteria);

SearchCriteria translates to REST API query parameters.

REST API filters:

# Equal
GET /rest/V1/posts?searchCriteria[filterGroups][0][filters][0][field]=status&searchCriteria[filterGroups][0][filters][0][value]=1

# IN
GET /rest/V1/posts?searchCriteria[filterGroups][0][filters][0][field]=status&searchCriteria[filterGroups][0][filters][0][value]=1&searchCriteria[filterGroups][0][filters][0][conditionType]=in

# LIKE
GET /rest/V1/posts?searchCriteria[filterGroups][0][filters][0][field]=title&searchCriteria[filterGroups][0][filters][0][value]=%keyword%&searchCriteria[filterGroups][0][filters][0][conditionType]=like

Sort order via API:

GET /rest/V1/posts?searchCriteria[sortOrders][0][field]=created_at&searchCriteria[sortOrders][0][direction]=DESC

Pagination via API:

GET /rest/V1/posts?searchCriteria[pageSize]=20&searchCriteria[currentPage]=1

PHP to API mapping:

addFilter('status', 1)
→ filterGroups[0][filters][0][field]=status
→ filterGroups[0][filters][0][value]=1

addSortOrder('created_at', 'DESC')
→ sortOrders[0][field]=created_at
→ sortOrders[0][direction]=DESC

setPageSize(20)->setCurrentPage(1)
→ pageSize=20
→ currentPage=1

SearchCriteria parser:

// Parse from API request
$searchCriteria = $this->searchCriteriaBuilder->create();

// From query params
if ($this->request->getParam('searchCriteria')) {
    $searchCriteria = $this->filterMapper->map($this->request->getParam('searchCriteria'));
}