Search indexes

Our search index feature makes it easy to create and manage an index for your Dynamic Content data. All you need to do is specify the content types to include in the index, and then specify the actions in Dynamic Content that are used to update the index, and you've got a search index ready for you to query using search APIs to use to build your front end search experience.


About the search APIs

Dynamic Content search is powered by Algolia. Indexes are created in an Algolia account managed by Amplience and can only be managed using the search indexes features. You will not have direct access to Algolia's dashboard or write access to the index using the Algolia APIs. You will have read access to Algolia's search APIs so you can query content and use their SDKs to build your search UI.

Viewing your search indexes

To create, view or edit a search index go to the Development home page or choose "Search indexes" from the Development menu.

If you would like to make use of the search index feature, please contact your Customer Success Manager.

To view your search indexes, choose Search indexes from the development home page or choose Search Indexes from the Development menu
To view your search indexes, choose Search indexes from the development home page or choose Search Indexes from the Development menu

The search index screen will be initially empty. Click "Create index" to launch the index wizard.

Your search index page will initially be empty
Your search index page will initially be empty

If you want to view an existing index, just double click its entry in the index list or choose "View" from its contextual menu. You can also choose to delete an index.

You can view an index by double clicking its entry in the list or choosing view its contextual menu
You can view an index by double clicking its entry in the list or choosing view its contextual menu

Creating an index with the wizard

The search index wizard is used to set up an index and configure the webhook that sends a request to the search API to update the index when triggered by a specified action in Dynamic Content.

First give your index a name and choose the content type that you want to use to populate the index. You can only specify a single content type using the wizard, but you can add additional content types later. In this example we'll use the blog post content type.

Using the wizard, give your search index a name and choose which content type you want to associate with the index
Using the wizard, give your search index a name and choose which content type you want to associate with the index

In the "Choose environment" step, choose whether you want to index production or staging content. This setting is used to determine the webhook that is used to trigger writing to the index. For production content the webhook trigger will be "content item- snapshot published" and your index will be updated when a content item of your specified content type is published in Dynamic Content.

For staging content, "content item- created" and "content item- updated" are used as the triggers and your index will be updated when a content item of the specified content type is created or updated. You'll usually create a staging index if you want to include your search in visualizations or previews.

Choose whether you want to use the index for production or staging content
Choose whether you want to use the index for production or staging content

To go back to a previous step, click the circle above the step title. So if you're in Step 3 and want to change the content type initially used for the search index, click the circle above Step 2 to go back.

When you've finished the configuration, click the "Save and complete" button to create the index. The index will be created in Algolia and a webhook will be set up in Dynamic Content.

For more information about what's set up for you when you create a search index, take a look at Search integration guide Part 1 which explains how to set up customizable webhooks to connect Dynamic Content with the Algolia API. The steps shown in the guide are already done for you when you create a search index using the wizard.

The Browse tab

When the index is first created, it will be empty and so you need to populate it. In this example we're indexing production content, so to add an item to the index we need to go to the Content Library, by clicking "Add records", and publish a content item created from the content type that we configured the index to use.

Populate your search index by publishing, creating or updating content items, depending on whether you are working with production or staged content
Populate your search index by publishing, creating or updating content items, depending on whether you are working with production or staged content

In this example, when a content item created from the blog post content type is published, an entry will be added to the search index.

For a production index, publishing a content item created from one of your specified content types will generate a request to add this item to your index
For a production index, publishing a content item created from one of your specified content types will generate a request to add this item to your index

You can go back to the Browse tab to view the record that has been added to the search index. Notice that by default, all of the properties of the blog post content type are included.

You can view the newly created record from the Browse tab
You can view the newly created record from the Browse tab

You can use the browse tab to help you decide which properties should be searchable and to refine the index so that it only includes those properties that you need for your search.

The Configure tab

The current configuration for your search index is displayed when you click the "configure" tab. Initially this will contain the default index settings, but you can edit it to meet your requirements. For example, you will usually want to define searchable attributes, to limit your search to specific attributes and specify the order of relevance. Other settings you may want to configure include custom ranking and facets.

We've included snippets to make it easier to add the most common settings, but you can edit the configuration for settings not found in the snippets.

The current configuration for your search index is shown when you select the configure tab
The current configuration for your search index is shown when you select the configure tab

The search configuration explains the most commonly updated settings in more detail, and information about all of the settings can be found in the Algolia documentation.

Updating the configuration

To update the configuration, you can include just the updated setting(s) or edit the existing settings directly.

Searchable attributes

In the example below, we are including a searchableAttributes setting and specifying the properties of our content type that we want to be searchable. For the blog post content type we want title and description to be searchable, so we'll add the following setting.

{
  "searchableAttributes": [
    "title",
    "description"
  ]
}

To add this setting, choose "Searchable attributes" from the "Add snippet" menu. A snippet will be added including some default values.

The searchableAttributes snippet
The searchableAttributes snippet

Edit the snippet to include your own properties and click the "Save" button at the top of the window.

The searchableAttributes settings
The searchableAttributes settings

The configuration will be updated to include the new setting (1 in the image below).

The configuration is updated to include searchable attributes
The configuration is updated to include searchable attributes

Now when we go back to the browse window and search for some text, only the properties that we specified as searchable will be included in the search.

Only the specified attributes are included in a search
Only the specified attributes are included in a search
Facets

Facets allow users to refine their search using a set of defined categories. Any facets that you've included in your search settings will be shown in the browse tab.

If you've defined a facet as searchable, a search box is included, allowing you to search within the facet itself, this is particularly useful if a facet can have a lot of possible values, such as tags.

In the example attributesForFaceting setting shown below, the tags property is defined as a searchable facet, while authors.name is a standard facet. Note that these properties should be included in your custom payload.

{
  "attributesForFaceting": [
   "searchable(tags)",
   "authors.name"
  ]
}

To add facets to your search settings, choose "Facets" from the "Add snippet" menu. You can edit the settings directly if you need to update an existing value.

The attributes for faceting snippet
The attributes for faceting snippet

Update the snippet with your faceting attributes and click "Save".

Update the snippet to include your own attrbutes
Update the snippet to include your own attrbutes

When you go back to the "Browse" tab, the facets are now displayed (if you have populated the faceted properties).

Facets are displayed in the browse tab
Facets are displayed in the browse tab

Browse and configure is an iterative process, so you can go back and forth between the tabs updating your searchable attributes and facets until it is set up to meet your requirements.

The webhook tab

When you create an 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, depending on whether you are working with production or staged content, the webhook will be triggered and a request will be sent to the search API to update your index.

Note that a webhook is created for each content type that you have added to an index. For each content type, an archive webhook is also created. This is triggered when a content item created from the content type is archived. See the archive webhook later in this section for more details.

To view the webhook, click the webhook name or choose 'Open indexing webhook" from its menu.

A webhook is created for each content type associated with an index
A webhook is created for each content type associated with an index

The webhook is all set up for you, so the only changes you should need to make are to the custom payload- to allow you to refine the properties that are included in your index.

The webhook is set up for you, but you can change settings such as the custom payload
The webhook is set up for you, but you can change settings such as the custom payload

Refining your index

The webhook custom payload is used to define the body of the request that gets sent to the search API. When you first create an index using the wizard, the custom payload will look something like the following:

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

This will include all of the properties of the content type in the webhook request, so all of these properties will be added to your search index.

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. 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.

If you are using Content Delivery 2 and want to retrieve a content item using its delivery key, then you can also include the delivery key in the custom payload.

For example, 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. For the blog post content, you might choose to include just an excerpt to prevent your record from becoming too large.

Replace "myAccountId" with your Amplience account name and "vseURL" with the virtual staging domain from your hub.


{
  {{#withDeliveryContentItem contentItemId=payload.rootContentItem.id account="myAccountId" stagingEnvironment="myVseUrl" 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.

Updating the custom payload to include only those properties that you want to include in your index
Updating the custom payload to include only those properties that you want to include in your index

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.

Only those properties included in the custom payload are added to the index
Only those properties included in the custom payload are added to 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.

The archive webhook

The archive webhook is used to send an API request to remove a record from the index when the corresponding content item is archived from the Content Library in Dynamic Content. You can view the archiving webhook by choosing "Open archiving webhook" from the menu in the webhook tab.

The method used in the webhook is DELETE (1 in the image below) and is only triggered when a content item of the specified content type is archived. The webhook filters are set up to ensure that the webhook only triggers when payload.status is equal to "ARCHIVED". You don't need to configure the webhook because it's already set up for you.

The archive webhook is setup for you when a content type is added to the index. It's triggered when a content item is archived in Dynamic Content and will remove the corresponding record from the search index
The archive webhook is setup for you when a content type is added to the index. It's triggered when a content item is archived in Dynamic Content and will remove the corresponding record from the search index

If you do not wish to remove records from the index when the corresponding content item is archived, you can open the archiving webhook and set its status to inactive. To make the webhook inactive, choose "Open archiving webhook" from the menu in the webhook tab and change the status to inactive (1 in the image below).

If you don't want to remove records when a content item is archived, you can set the archive webhook to inactive
If you don't want to remove records when a content item is archived, you can set the archive webhook to inactive

Keys

The keys that developers will need to build your search front end, the application ID and search API key, are shown in the keys tab. You'll use these with the search API to build your queries.

The application ID and search API keys are shown in the keys tab
The application ID and search API keys are shown in the keys tab

Adding a content type

When you've created an index, you can add a content type to it by choosing the "Add content type" button, as shown in the image below.

Once an index is set up, you can add additional content types to it
Once an index is set up, you can add additional content types to it

A list of the available content types will be shown, excluding any that have already been added to the index. In this example we'll add the Image content type.

Click "Save and continue" when you've chosen the content type to add.

Choosing a content type to add to the index
Choosing a content type to add to the index

The content type will be added to the index and the index will be updated using the trigger you previously specified, either when a content item of one of your specified types is published, or, if you're indexing staging content, when an item is created or updated.

A webhook is created for each content type you add to the index. This makes it easier for you to edit the webhook configuration for each content type.

Once a content type has been added to a search index, it cannot be removed.

A webhook is created for the content type you just added
A webhook is created for the content type you just added

Clearing an index

Clearing an index will remove all the records and cannot be undone, so we've included an extra verification step. To clear an index, choose "Clear index" from the "Save" menu at the top right of the screen. A dialog will be displayed asking you to enter the text "CLEAR"- note that this is case sensitive. When you click the "Clear" button all records will be removed from the index.

You must verify that you really want to clear an index
You must verify that you really want to clear an index

Retrieving content

We recommend including only those properties in your search index that you need for your search and retrieving the content item from Dynamic Content when you need it, such as when the user clicks on an entry in your search list.

The objectID in your search index is the content item id and you can use this to retrieve the content using the Content Delivery API or Content Delivery 2 API. If you're using Content Delivery 2, you may also want to include the delivery key in your index so you can use it to retrieve content.

A guide to refining your search index

Search integration guide Part 1

Content Delivery 2 API

Delivery keys

Content Delivery API

Webhooks

Customizable webhooks

results matching ""

    No results matching ""