Skip to main content

Filter and search use cases

The filter API lets you list, sort and filter your content. You can list all the content created from a specified content type, specify the sort order of your results, and filter the content using one or more custom properties.

The main features of the filter API include:

  • Listing all content created from a single content type, such as all the blog posts on your site
  • Sorting content using properties in your content type schema. Using the blog post example, you could sort all blogs by category, by read time or date.
  • Filter by content type and one or more properties. So you could retrieve all products in a particular category, or all blogs on a chosen topic with a ranking of 5.
  • Manage multiple pages of responses. If you get a lot of results, then you can easily request the next page of responses.
  • Set the format used for the response using the same parameters used when you retrieve content by id or delivery key.
  • The filter API is also designed to make it easier to consume hierarchies in your code. You can list all the children of a hierarchy node. This allows you to traverse a hierarchy by going through each of the content items returned in the response to find their child nodes.

With the filter API and Amplience Search, you have two ways of querying your content and which method you use depends on a number of factors. The filter API is optimized to filter on one or more properties that you define in your content type schema. The content is pre-filtered, so retrieving filtered content is fast and the API is easy to use.

In many cases the filter API will meet your requirements and it has the advantage of not requiring you to build a search index and write your own search code. However, using the filter API does have some restrictions and in the following cases you might want to consider using a search index instead.

Scenarios where search may be a better option
Link copied!

  • Natural language search. There are some cases where you need to support natural language search. The filter API matches on exact values, so for any more complex searches you will need to use a search index.
  • Faceting. If you want to display facets and counts in the user interface to give your end users the ability to refine the list of results, you will need search. An example might be if you’re tagging items dynamically, using linked content.
  • Complex queries. The filter API only supports "AND" queries, where you filter on the values of multiple properties. If you need to query content using more complex queries, then you need to use a search index instead.
  • Filtering using an array. The filter API does not currently support arrays, so if you're filtering using the value of an array property, then search is a better choice.
  • Filtering on linked content. The filter API only supports properties that are part of the schema itself and not any other content items linked to it. Search is a better choice if you need to query values in linked content.
  • List and filter on multiple content types. With the exception of hierarchies, you cannot use the filter API to list and filter content across multiple content types. In this case search may meet your needs better.
  • Anything that exceeds the limits. You can define 5 filter paths and 3 sorts using the filter API, but if that's not enough, then using a search index may be a way around these limits.

Example use cases
Link copied!

Here are just a few examples of the many use cases for list, sort and filter using the filter API.

  • Blog

A simple use case for blogs is to list all blogs, filter by catgeory and sort by date, or some user defined ranking.

  • Book shop

To implement a book shop example you could use the filter API to filter content by author, by genre or even by ISBN number. You could also choose to sort the items by publication date.

  • Navigation menu

A site navigation menu could combine the features of the filter API and hierarchies. Each node would represent an entry in the site menu and the filter API can be used to get all nodes, list all children of a parent node and sort by a user defined field such as priority.

  • Gig listing

To manage a list of gigs you could filter by band or by city. You also might want to structure the content in a hierarchy and can then use the filter API to traverse the hierarchy.

  • Enhanced product content

Another use case is to add relevant content, such as additional editorial content, into a product details page filtered by SKU, brand or category.

Using the filter API

Hierarchies