Guides & Tutorials

How to implement the Query API on your website

Jesper Weber

Senior Software Engineer at Enterspeed

Thumbnail for blog post: How to implement the Query API on your website

The best way to test a new feature is undoubtably to get your hands dirty and actually USE IT. So that’s what we did. We’ve tested the new Enterspeed Query API on our very own Enterspeed.com site. (And we still think it’s awesome!).

To the surprise of no one, Enterspeed.com is built using Enterspeed. So, in this blog post, we’ll focus on how we updated the blog page to use the new Enterspeed Query API (replacing the previous default approach – a pre-generated list).

To be fair, working with lists, particularly larger ones with pagination or filtering, has not been a well-integrated part of the Enterspeed experience. But that’s changed now with the introduction of the Enterspeed Query API 😊

What is the Enterspeed Query API?

Before we jump into the changes we made on the Enterspeed.com site to incorporate the Query API, let’s just first get an idea of what the Query API is and what it can do.

The Enterspeed Query API is a search index and comes with features like filtering, sorting, pagination, and facets support, making it possible for you to do dynamic requests on your data.

The Query API is currently in public preview and will be fully released later in August 2025. If you want to test it already today, just reach out to us.

As a real Enterspeed feature, the Query API integrates nicely with the schemas and views you already know from Enterspeed, letting you return existing views based on your query.

The Query API introduces two new parts.

First, we have a new type of schema called Index schema. Besides the trigger and properties methods – which you already know from existing schema types – the Index schema also includes an index method that lets you define the fields and their types of the index you want to create.

1/** @type {Enterspeed.IndexSchema} */
2export default {
3  triggers: function(context) {
4    // Example that triggers on 'mySourceEntityType' in 'mySourceGroupAlias', adjust to match your own values
5    // See documentation for triggers here: https://docs.enterspeed.com/reference/js/index-schema/triggers
6    context.triggers('mySourceGroupAlias', ['mySourceEntityType'])
7  },
8  index: {
9    // All fields that should be indexed in the search index
10    // See documentation for index here: https://docs.enterspeed.com/reference/js/index-schema/indexMethod
11    fields: {
12      // Example of a searchable field with type keyword
13      searchableField: { type: "keyword" }
14    }
15  },
16  properties: function (sourceEntity) {
17    // See documentation for properties here: https://docs.enterspeed.com/reference/js/index-schema/properties
18    return {
19      searchableField: sourceEntity.originId
20    }
21  }
22}

The second part is the REST Query API that lets you query the data in your indexes. It lives side-by-side with the existing Delivery API. Together, these two APIs give you a strong and flexible way of loading data from Enterspeed depending on your use case and the type of data.

Enterspeed.com before the Query API

You probably already know this since you’re reading this blog post, but on Enterspeed.com we have a blog page with a list of blog posts.

The blog page and the blog posts used to be controlled by three schemas in Enterspeed.

Schema name	Schema type	Responsibility
Blog	Full	Serving the list of all blog posts as references to the BlogPostListItem schema.
BlogPostListItem	Full	Returning a subset of a single blog post’s information, such as image, title, teaser, date, and category, URL to display a single item in the list.
BlogPost	Full	Returning all blog post data to display the blog post details page.

The schema also contains a reprocess action on the blog schema to make sure the list of blog posts is updated when new blog posts are added on the site.

Since all views in Enterspeed are pre-processed, the standard way to work with lists is by using reprocess actions to update schemas that contain them.

Although this way absolutely works, the solution has a couple of drawbacks if you work with larger lists:

You, as developer, need to remember the reprocess action – and also that reprocessing takes a little extra time for Enterspeed.
Filtering on category is done client side, meaning we’re loading all posts on page load.
The list doesn’t support pagination.

Earlier, when working with larger lists, the recommended approach was to use one of Enterspeed’s built-in Destinations, which can automatically push views to an search index such as Algolia or Elastic Search.

But now, with the introduction of Enterspeed Query API, you can do all of the above (and more!) directly within Enterspeed with no need for any third-party tools.

Enterspeed.com after the Query API

Now, we’ve introduced the Query API and worked through the previous Blog list solution, so let’s go through the changes we made to replace it with the new Query API.

It actually required very little changes in Enterspeed. First off, we introduced a new BlogIndex schema which is our new index with all the blog posts. This schema is a direct replacement of the Blog schema we had before with the pre-processed list. This meant that we deleted the Blog schema afterwards.

Since we’ve deleted the Blog schema with the pre-processed list, we could also go ahead and remove the reprocess action from the BlogPost schema. The BlogIndex is updated as soon as blog posts are added, updated, or deleted, so we no longer need to reprocess the pre-processed list from the Blog schema.

And that’s it, folks. That’s the only changes we needed to make in Enterspeed. Easy right?

Schema name	Schema type	Changes
BlogIndex	Index	Created a new BlogIndex schema.
Blog	Full	Deleted the schema as the list is now dynamic from the BlogIndex.
BlogPostListItem	Full	No changes to the changes to the schema.
BlogPost	Full	Removed the reprocess action as we now longer need to reprocess a pre-processed list. Besides that, no changes to the schema.

If we look at the new BlogIndex schema, it’s really very simple. The trigger and the properties methods in the schema are just as you know them from existing schema types. They define which source entity types the schema should work on and how the source entity should be mapped.

The new index method defines which fields and field types you want in your index – and in our case, we only needed to index two fields. The date field, which we need to sort all the blog posts by descending date, and the category field, which we need for filtering the blog posts by category.

1/** @type {Enterspeed.IndexSchema} */
2  export default {
3  triggers: function(context) {
4    context.triggers('cms', ['blogPost'])
5  },
6  index: {
7    fields: {
8      date: { type: "date" },
9      category: { type: "keyword" }
10    }
11  },
12  properties: function (sourceEntity) {
13    return {
14      date: sourceEntity.properties.publishedOn,
15      category: sourceEntity.properties.category
16    }
17  }
18}

We made no changes to the BlogPostListItem schema. Before, it was referenced from the Blog schema, but as mentioned in the introduction to the Query API, we simply reference the same schema directly from the Query API request.

Let’s have a look at the request:

1{
2    "filters": {
3        "and": [
4            {
5                "field": "category",
6                "operator": "equals",
7                "value": "News & Announcements"
8            }
9        ]
10    },
11    "aliases": ["blogPostListItem"],
12    "sort": [
13        {
14            "field": "date",
15            "direction": "desc"
16        }
17    ],
18    "facets": [
19        {
20            "field": "category"
21        }
22    ],
23    "pagination": {
24        "page": 1,
25        "size": 18
26    }
27}

The filtering, sorting, and pagination is straight forward. The facets are also familiar if you’ve worked with search indexes before. We specified that we want a facet returned based on the category field. This means that besides the list of posts matching the filter, the query will also return a list of all the different categories (including a number of matches). We can use this list to let the users filter the blog post results.

The last field in the query is the aliases field. This field is how we bind indexes and views together in Enterspeed.

In the case above, it means that even though we only have two fields in our index (date and category), the Query API can return all the fields we need for presentation via the blogPostListItem schema.

For each result, it also returns the blogPostListItem view associated with the corresponding source entity. That means that you can have the same index of blog posts or products returning different views depending on what presentation data you need without having to put all data in your index.

To get more info about the Index schemas and the Query API, check out our documentation: