Defining indexable properties

When you create a search index, a corresponding webhook is set up using the configuration you specified in the search index wizard. When a content item of one of your specified content types is published, created or updated, the webhook will be triggered and a request will be sent to the search API to update your index.

The webhook is all set up for you, so the only changes you should need to make are to the custom payload. The custom payload is used to define the body of the request that gets sent to the search API, which generates the record that is created in your search index. You can use the custom payload to include the properties that you need to implement your search functionality.

info

Amplience search is powered by Algolia and uses JSON to model records. To find out more about how search records are structured, see the Algolia guide to formatting and structuring your data.

On this page we'll explain how you can update the custom payload to include all the properties that you need to facilitate search, display, filtering or relevance. You can also transform data to achieve the results you need, for example converting a date into a UNIX timestamp to make it sortable.

The default custom payload

info

The custom payload is specified in handlebars format and is used to generate JSON output.

When you first create an index using the wizard, the custom payload will look something like the following:

{{#withDeliveryContentItem contentItemId=payload.id account="amplience" stagingEnvironment="kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io"}}
{
  "name": "{{_meta.deliveryKey}}",
  "schema": "{{_meta.schema}}",
  "deliveryKey": "{{_meta.deliveryKey}}",
  "deliveryId": "{{_meta.deliveryId}}"
}
{{/withDeliveryContentItem}}

This will include just the properties of the _meta section of the content type. In some cases this information will be all you need to include in your search index and you will be able to use the deliveryKey or deliveryID to retrieve the full content item.

An example payload body generated from a content item of the blog content type and the default custom payload is shown below. In this example the content item does not have a delivery key and you would use the deliveryID to retrieve the full item.

{
  "name": "Blog post",
  "schema": "https://schema-examples.com/blogpost",
  "deliveryKey": "",
  "deliveryId": "863eafde-68c6-4427-88f1-3a27b7eb9834"
}

An example search record created using the default payload shown in the image below.

Updating the custom payload

In most cases you will need to update your custom payload to include any additional properties that you require to facilitate search.

Your payload should include all the fields used in your search configuration (searchableAttributes, attributesForFaceting and customRanking) together with any other fields you need to use for display purposes to build your front end. For the blog post content type this might include the image URL.

To view the custom payload, you need to edit the indexing webhook for your search index. Choose "Search indexes" from the "Development" menu, view your search index and then open the Webhooks tab.

Scroll to the "payload" section in "Settings" to view or edit the custom payload.

Output all properties

For testing purposes, or if your content type schema contains only a few properties, you can create search records from all the properties in a content type. Update the custom payload to {{{JSONstringify this}}} as shown below:

{{#withDeliveryContentItem contentItemId=payload.rootContentItem.id account="ampproduct" stagingEnvironment="kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io" snapshotId=payload.id}}
{{{JSONstringify this}}}
{{/withDeliveryContentItem}}

Algolia recommends that, for performance reasons, the maximum size of a record should not exceed 5KB. We recommend that you refine the the custom payload to optimize the size of the record created in Algolia by including only those properties that you want to be used for your search.

Optimizing your properties

In the custom payload for the blog post content type, shown in the example below, we might want to index the title, description, author names, tags, date, readTime and the content itself so that all these fields are available to your search. In this example we are using some of our supported handlebars helpers to transform the data, and to pick out the parts we need.

Leaving the opening and closing expressions for the withDeliveryContentItem helper in place, edit the default custom payload as follows:

{{#withDeliveryContentItem contentItemId=payload.rootContentItem.id account="ampproduct" stagingEnvironment="kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io" snapshotId=payload.id}}
{
  "title": "{{{title}}}",
  "description": "{{{description}}}",
  "deliveryKey": "{{{_meta.deliveryKey}}}",
  "authors": [
  {{#each authors}}{{#if @index}},{{/if}}
    {
      "name":"{{{name}}}"
    }
  {{/each}}
  ],
  "tags": {{{JSONstringify tags}}},
  "date": "{{{this.date}}}",
  "readTime": {{{readTime}}},
  "dateAsTimeStamp": {{{moment date format="X"}}},
  "content": [
  {{#each content}}
    {{#if text}}
        {{#if @index}},{{/if}}
        {{{JSONstringify text}}}
    {{/if}}
  {{/each}}
  ],
  "imagePath":"{{{image.image.endpoint}}}/{{{image.image.name}}}"
}
{{/withDeliveryContentItem}}

An example of a webhook with an updated custom payload is shown in the image below.

With the updated custom payload, when a blog content item is published, only properties included in the custom payload (together with the objectID) are included in the index.

After updating your custom payload, if you have changed the names of any attributes, or added new ones, you may need to update your search settings. If you aren't using Dynamic Content search, then see the Algolia dashboard for these settings.

For more detail on refining your search index, see our guide to refining your search index.

Related pages

Search index overview

Search index configuration

A guide to refining your search index