Shopware 6

Search Criteria

Overview

https://developer.shopware.com/docs/guides/integrations-api/general-concepts/search-criteria Generally, we refer to the endpoints that use the POST method and receive the criteria as a JSON object as search criteria. It takes the same arguments as a DAL criteria. Some endpoints expect more parameters than specified here; these differ from one endpoint to another, so they are not specified here.

A typical search criteria looks like this:

{
  "limit": 10,
  "associations": {
    "manufacturer": {},
    "propertyIds": {},
    "cover": {},
    "options": {
      "associations": {
        "productOptions": {},
        "group": {}
      }
    }
  },
  "includes": {
    "product": [
      "calculatedPrice",
      "cover",
      "id",
      "translated",
      "seoUrls",
      "manufacturer",
      "propertyIds",
      "options"
    ],
    "product_media": [
      "media"
    ],
    "media": [
      "thumbnails",
      "width",
      "height",
      "url"
    ],
    "calculated_price": [
      "unitPrice",
      "quantity"
    ]
  }
}

In the following, we will go through different parameters that criteria can be assembled from.

Parameter	Usage
associations	Allows loading additional data to the standard data of an entity (similar to a SQL Join).
includes	Restricts the output to the defined fields, reducing the response payload.
ids	Limits the search to a specific list of record IDs.
total-count-mode	Defines how the total number of search hits should be determined (exact, no total, or next page check).
page	Defines the starting page for the search result (1-indexed).
limit	Defines the maximum number of entries to be returned.
filter	Allows filtering the result and aggregations using various filter types.
post-filter	Allows filtering the result but not the aggregations.
query	Enables determining a weighted ranking (_score) for the search result.
term	Enables a simple text search on all records based on their data model weighting.
sort	Defines the sorting of the search result, including field, order, natural sorting, and type.
aggregations	Specify aggregations (e.g., average price, counts) to be computed on-the-fly.
grouping	Allows grouping records by specified fields (e.g., one product per manufacturer).

includes (apiAlias)

The includes parameter allows you to restrict the returned fields.

• Transfer only what you need reduces response payload.

• Easier to consume for client applications.

• When debugging, the response is smaller, and you can concentrate on the essential fields.

Example:

{
  "includes": {
    "product": ["id", "name"]
  }
}

Response:

{
  "total": 120,
  "data": [
    {
      "name": "Synergistic Rubber Fish Soda",
      "id": "012cd563cf8e4f0384eed93b5201cc98",
      "apiAlias": "product"
    },
    {
      "name": "Mediocre Plastic Ticket Lift",
      "id": "075fb241b769444bb72431f797fd5776",
      "apiAlias": "product"
    }
  ]
}

All response types come with an apiAlias field which you can use to identify the type in your includes field. If you only want a category id, add: "category": ["id"]. For entities, this is the entity name: product, product_manufacturer, order_line_item, ... For other non-entity types like a listing result or a line item, check the full response. This pattern applies not only to simple fields but also to associations.

ids

If you want to perform a simple lookup using just the ids of records, you can pass a list of those using the ids field:

{
  "ids": [
    "012cd563cf8e4f0384eed93b5201cc98",
    "075fb241b769444bb72431f797fd5776",
    "090fcc2099794771935acf814e3fdb24"
  ]
}

total-count-mode

The total-count-mode parameter can be used to define whether the total number of hits should be determined for the search query. This parameter supports the following values:

• 0 [default] - No total is determined.

  • Advantage: Most performant because MySQL does not need to run SQL_CALC_FOUND_ROWS.

  • Purpose: Use if pagination is not required.

• 1 - An exact total is determined.

  • Purpose: Use if paginating with exact page numbers.

  • Disadvantage: Performance intensive; uses SQL_CALC_FOUND_ROWS.

• 2 - It is determined whether there is a next page.

  • Advantage: Good performance, same as 0.

  • Purpose: Useful for infinite scrolling to know if there is a next page.

Example:

{
  "total-count-mode": 1
}

page & limit

The page and limit parameters control pagination. The page parameter is 1-indexed.

{
  "page": 1,
  "limit": 5
}

filter

The filter parameter allows you to filter the result and aggregations using many filters and parameters. The filter types are equivalent to the filters available for the DAL.

Filters Reference:

Name	Notes
equals	Exact match for the given value
equalsAny	At least one exact match for a value of the given list
contains	Before and after wildcard search for the given value
range	For range compatible fields like numbers or dates
not	Allows to negate a filter
multi	Allows to combine different filters
prefix	Before wildcard search for the given value
suffix	After wildcard search for the given value

Equals

The equals filter checks fields for an exact value. Example SQL: WHERE stock = 10.

PHP Criteria

$criteria = new Criteria();
$criteria->addFilter(new EqualsFilter('stock', 10));

API Criteria

EqualsAny

The equalsAny filter allows matching any value from a list. Example SQL: WHERE productNumber IN (...).

PHP Criteria

$criteria = new Criteria();
$criteria->addFilter(
  new EqualsAnyFilter('productNumber', [
    '3fed029475fa4d4585f3a119886e0eb1',
    '77d26d011d914c3aa2c197c81241a45b'
  ])
);

API Criteria

Contains

The contains filter performs a wildcard search. Example SQL: WHERE name LIKE '%Lightweight%'.

PHP Criteria

$criteria = new Criteria();
$criteria->addFilter(new ContainsFilter('name', 'Lightweight'));

API Criteria

Range

The range filter supports numeric or date ranges. Parameters: gte, lte, gt, lt. Example SQL: WHERE stock >= 20 AND stock <= 30.

PHP Criteria

$criteria = new Criteria();
$criteria->addFilter(
  new RangeFilter('stock', [
    RangeFilter::GTE => 20,
    RangeFilter::LTE => 30
  ])
);

API Criteria

Not

The not filter is a container to negate filters. The operator (or or and) defines how queries inside are combined. Example SQL: WHERE !(stock = 1 OR availableStock = 1) AND active = 1.

PHP Criteria

$criteria = new Criteria();
$criteria->addFilter(new EqualsFilter('active', true));
$criteria->addFilter(
  new NotFilter(
    NotFilter::CONNECTION_OR,
    [
      new EqualsFilter('stock', 1),
      new EqualsFilter('availableStock', 10)
    ]
  )
);

API Criteria

Multi

The multi filter is a container to combine filters with a logical operator (or or and). Example SQL: WHERE (stock = 1 OR availableStock = 1) AND active = 1.

PHP Criteria

$criteria = new Criteria();
$criteria->addFilter(
  new MultiFilter(
    MultiFilter::CONNECTION_OR,
    [
      new EqualsFilter('stock', 1),
      new EqualsFilter('availableStock', 10)
    ]
  )
);
$criteria->addFilter(new EqualsFilter('active', true));

API Criteria

Prefix

The prefix filter checks that the field starts with a value. Example SQL: WHERE name LIKE 'Lightweight%'.

PHP Criteria

$criteria = new Criteria();
$criteria->addFilter(new PrefixFilter('name', 'Lightweight'));

API Criteria

Suffix

The suffix filter checks that the field ends with a value. Example SQL: WHERE name LIKE '%Lightweight'.

PHP Criteria

$criteria = new Criteria();
$criteria->addFilter(new SuffixFilter('name', 'Lightweight'));

API Criteria

When you are filtering for nested values — for example, filtering orders by their transaction state (order.transactions.stateMachineState) — make sure to fetch those in your associations field first.

Example nested associations and filter:

{
  "associations": {
    "transactions": {
      "associations": {
        "stateMachineState": {}
      }
    }
  },
  "filter": [
    {
      "type": "multi",
      "operator": "and",
      "queries": [
        {
          "type": "multi",
          "operator": "or",
          "queries": [
            {
              "type": "equals",
              "field": "transactions.stateMachineState.technicalName",
              "value": "paid"
            },
            {
              "type": "equals",
              "field": "transactions.stateMachineState.technicalName",
              "value": "open"
            }
          ]
        },
        {
          "type": "equals",
          "field": "customFields.exportedFlag",
          "value": null
        }
      ]
    }
  ]
}

post-filter

Works the same as filter; however, post-filter does not apply to aggregations. This is useful when you want aggregations (facets) to be computed on a broader set but display results filtered without an extra request.

query

Use query to create a weighted search that returns a _score for each entity. Any filter type can be used for the query. A score must be defined for each query; the sum of matching queries results in the total _score.

Example:

{
  "query": [
    {
      "score": 500,
      "query": { "type": "contains", "field": "name", "value": "Bronze" }
    },
    {
      "score": 500,
      "query": { "type": "equals", "field": "active", "value": true }
    },
    {
      "score": 100,
      "query": {
        "type": "equals",
        "field": "manufacturerId",
        "value": "db3c17b1e572432eb4a4c881b6f9d68f"
      }
    }
  ]
}

Resulting _score is appended to each resulting record in extensions.search:

{
  "total": 5,
  "data": [
    {
      "manufacturerId": "db3c17b1e572432eb4a4c881b6f9d68f",
      "name": "Awesome Bronze Krill Kream",
      "extensions": { "search": { "_score": "1100" } },
      "id": "0acc3aa5c45a492c9a2adb8844cb7adc",
      "apiAlias": "product"
    },
    {
      "manufacturerId": "d0c0daa910d94b3c8b03c2bef6acb9b8",
      "name": "Synergistic Bronze New Tab",
      "extensions": { "search": { "_score": "1000" } },
      "id": "72858576ac634f209b7ad61db15b7cc3",
      "apiAlias": "product"
    },
    {
      "manufacturerId": "3b5f9d51803849c68bb72360debd3da0",
      "name": "Fantastic Paper Zamox",
      "extensions": { "search": { "_score": "500" } },
      "id": "18d2b4225ea34b17a6099108da159e7f",
      "apiAlias": "product"
    }
  ]
}

term

Using term, the server performs a text search on all records based on their data model and weighting defined with the SearchRanking flag.

Don't use term together with query.

Example:

{
  "term": "Awesome Bronze"
}

Results are formatted the same as for the query parameter.

sort

The sort parameter controls sorting. Several sort entries can be provided.

• field: field used for sorting.

• order: sort direction (ASC or DESC).

• naturalSorting: enables natural sorting algorithm.

• type: allows divergent sorting behavior. Valid value shown below:

  • count: Sort by the count of associations via the given field. SQL: ORDER BY COUNT({field}) {order}

Example:

{
  "limit": 5,
  "sort": [
    { "field": "name", "order": "ASC", "naturalSorting": true },
    { "field": "active", "order": "DESC" },
    { "field": "products.id", "order": "DESC", "type": "count" }
  ]
}

count sorting behavior

Example request payload that includes a count aggregation.

This count type was introduced with Shopware 6.4.12.0 and is not available in prior versions.

{
  "limit": 3,
  "includes": { "product": ["id"] },
  "sort": [
    { "field": "categories.id", "order": "DESC", "type": "count" }
  ],
  "aggregations": [
    {
      "name": "product-id",
      "type": "terms",
      "field": "id",
      "limit": 3,
      "sort": { "field": "_count", "order": "DESC" },
      "aggregation": {
        "name": "category-count",
        "type": "count",
        "field": "product.categories.id"
      }
    }
  ]
}

In response, the order of the product elements equals the order of the aggregated buckets:

{
  "total": 3,
  "aggregations": {
    "product-id": {
      "buckets": [
        { "key": "f977f6a845a54b0381cbaf322f53b63e", "count": 5 },
        { "key": "8d0ee52433df44b78a6f7827180049d9", "count": 4 },
        { "key": "003a9df163474b28bc8a000243549547", "count": 3 }
      ]
    }
  },
  "elements": [
    { "id": "f977f6a845a54b0381cbaf322f53b63e" },
    { "id": "8d0ee52433df44b78a6f7827180049d9" },
    { "id": "003a9df163474b28bc8a000243549547" }
  ]
}

aggregations

The aggregations parameter can determine metadata for a search query (statistics, facets). Aggregation types are equivalent to the DAL aggregations.

Reference: resources/references/core-reference/dal-reference/aggregations-reference.md

Example — average price:

{
  "limit": 1,
  "includes": { "product": ["id", "name"] },
  "aggregations": [
    {
      "name": "average-price",
      "type": "avg",
      "field": "price"
    }
  ]
}

grouping

The grouping parameter allows grouping results over fields. Use cases:

• Fetch one product per manufacturer.

• Fetch one order per day and customer.

Example:

{
  "limit": 5,
  "grouping": ["active"]
}