Performance Tips

API Request Planning

Please plan your API requests according to the following guidelines (ordered by importance):

1. Avoid sequential API requests wherever you can.
2. Use Reference Expansion instead of parallel or sequential requests (nowadays, network roundtrip time is more crucial than the number of bytes transferred).
3. Do parallel requests. All the commercetools Platform SDKs support these and most good generic HTTP clients, too. You will need to plan ahead concerning by which identifiers to query, because you need them in the client request or session data to do parallel requests.
4. Avoid Reference Expansion if you do not necessarily need it (takes time platform-internally). Better not include "expand" Parameters in your request defaults, but add them on a case-by-case basis.

In any case, if you have use cases where the commercetools Platform's querying and reference expansion facilities force you into sequential requests, please post a suggestion on the Support Portal so that we can polish the API to avoid such cases.

Querying and Showing Data

• For a user-facing application, always go through the Product Projections endpoint. Use the Products endpoint only to implement administration, import/export etc. The API responses will be only half as large because the projections do only contain the current or the staged version of the data (depending on how you set the staged parameter), whereas the Products endpoint always returns the current and the staged version as full copies.
• Use the Product Projection Search endpoint wherever you can (even for fetching single products by some ID). Internally, the Product Projection Search endpoint is based on a different technology stack that delivers faster response times due to its read-only nature.
• When querying objects:
  • Try to set a sensible limit to the number of objects returned where you can. This depends on the cost of the query and on the size of the objects retrieved. As a rule of thumb, start with a small value and increase it in small steps until performance starts to drop off.
  • Deactivate the field total when you are not interested in the total number of results matching the query. Refer to PagedQueryResult for more details.
  • Avoid expensive query predicate patterns and understand the indexing behavior. This and specific tips are documented in the Query Predicate Documentation
• When doing bulk downloads, we recommend using the "process" implementation of our JavaScript SDK "base" service, which implements best practice defaults and patterns. Feel free to implement a similar pattern in your preferred stack.

Search

Indexing

When you create, update, or delete a product, it needs to be indexed before the change is available in the product projection search endpoint, which happens after a delay. This delay is not the same for all updates. Products with many variants, locales, prices, or searchable attributes take more time to get indexed than others, and thus, have a longer delay.

Additionally, when changing the configuration of your project that affects the products (for example, adding locales, currencies, countries, customer groups, or adding attributes to a product type), it will recreate the index for all products. Any following changes are put on hold until the process is completed and then applied later.

In the following list, you can find some thresholds below which a project should have a good indexing performance. Exceeding any of these values does not render the search unusable, but it may require the solution implementation to carefully design the frequency and timing of configuration changes that affect products. In that regard, we recommend you to apply all the configuration changes together before continuing with updating your products. This way, you optimize the effort for recreating the index of your project.

• one million products per project
• three million variants per project
• 15 locales per project
• 100 channels per project
• 20 suggestion keywords per product

Keep in mind that these values represent recommendations that you keep under control and not limits that the commercetools Platform imposes.

Filtering, faceting and sorting

• Consider reducing the number of faceting attributes on the search request if you want to decrease the response time.
• When possible, use filter.query filters to reduce the number of items to be faceted and/or sorted, as larger collections cause faceting and sorting to take proportionally longer.
• Use the filter by category subtree functionality whenever you want to retrieve products assigned to a specified category plus its subcategories.

Matching Variants

For each search request you can enable the marked-matching-variants functionality that leads to marking those variants within the returned products which are matching the search criteria.

As matching variants can be complex to calculate, this feature is deactivated by default.

Since this feature may have an impact on the search performance, we let you control for which requests you want to enable it and when you don't need it.

Response size

Fetching a large amount of data from the product projection search endpoint results in longer response times. We recommend targeting response sizes of less than 1 MB, but we are aware this can sometimes be difficult. Here are some hints that may help you optimize your queries:

• For multi-language projects, use localeProjection parameter to limit the number of locales present in the search response.
• Consider setting up stores and using storeProjection in the search query to reduce the number of locales and prices in the response.
• To reduce the number of products returned, and therefore, the response size, try using lower limit values in the search query.

Modifying Data

Multiple Update Actions:

• It is possible to add a large number of update actions into one update request as long as they change the same Object (for example Update Product.
• If you want to publish the updated product right away, you can include the respective publish update action into the list of update actions. It must be the last action on the list though.

Bear in mind that all update actions in one update request are treated as one transaction. That means that the whole list of update actions will fail as soon as one update action in the list fails. Thus, please think carefully about which update actions you'll put into the list of actions and which actions you better spread across different update requests.

Caching Parts of the Model

The commercetools Platform has been built for stateless frontend implementations, it is meant to pass every user request without caching in the frontend implementation. We recommend you to really do this until you have serious and specific performance problems. You may waste a large amount of time debugging cache staleness and its invalidation you probably not get paid for.

Nevertheless, many UI scenarios aren't doable without caching certain parts of the commercetools Platform data. This refers for example to the page header, especially category-driven menu trees and metadata like product types, channels, etc.

• Although you could query the whole category tree every time, it makes sense to cache the menu as a final menu object across users. We suggest to auto-refresh it very often to avoid inconsistencies, for example, every five seconds or so.
• Concerning User and Cart data, it depends on how much information is directly visible in the UIs initial state. In most cases, the information can be stored in an encrypted User Cookie (or a classic stateful server-side session) and the full User and/or Cart Object is pulled from the commercetools Platform on demand.

A notable exception to the general recommendation to avoid caching is that in some development frameworks (esp. in the content management system space) caching is built into the basic assumptions on a low level; In these cases it's not worth fighting against the framework's assumptions.

Import / Export / Sync Integrations

Most real-world projects have some kind of (or a lot of) backend system integrations. In addition to the general advice above, these kinds of sync jobs can be implemented better by reading out the change events from the Messages API endpoint. Instead of having to bulk download everything from the commercetools Platform over and over again to push changes into another system, you can create a job that polls the messages, remembers the "last message ID" (for example, in a CustomObject). This way your system integrations can provide "near-time" updates and both yours and the commercetools Platform load is much lower.
To be on the safe side you can do full sync additionally every now and then.

Whether you can also do this pattern for information that is synced into the commercetools Platform depends on the capabilities of the other involved systems. As mentioned above, the JavaScript SDK provides mature helpers for bulk operations.

GraphQL

Fetch only the fields that you need. This will result in smaller payloads, better for the network and the serialization/deserialization process.
Use <fieldName>Ref fields where the expanded resource is not needed.

Avoid typed product attributes and typed custom fields that adds a performance overhead, use the raw ones instead.

Optimize your queries towards low Query complexity.