Algolia

Get the API credentials from your Algolia app

To connect Prepr to Algolia, you need an Application ID  and a valid API key  with the following ACL permissions:

• settings: Used to verify if the index exists before performing operations.
• editSettings: Used to edit the index before performing operations.
• addObject: Used to add new records to your Algolia index.
• deleteObject: Used to delete outdated or incorrect records in the Algolia index.
• search: Used to find related records that also need to be updated in the Algolia index.

For more details, check out Rights and restrictions  in Algolia docs. Algolia uses these credentials to identify your Prepr application and control access to Algolia’s API.

To get the credentials, navigate to the API Keys  section in your Algolia app settings.

Connect Prepr to Algolia

Now that you have the required credentials, you can set up the Algolia integration in Prepr as follows:

1. Click the icon and choose the Integrations option to open the integrations page.

2. Hover over the Algolia card and click the Activate button.

   If you do not have access to the Algolia integration yet, click Request activation to contact our Sales team.

3. In the New Algolia app page, enter the Algolia credentials you got in the previous step.

   

Define Algolia search indexes

You’ve set up a basic connection to Algolia, but before you can sync any content to Algolia for indexing, you need to define at least one search index:

1. Go to the Search indexes section and click the + Add search index link to define the model and fields to be used for indexing.

2. Enter a name for the index that easily identifies what Algolia needs to index, for example: post. This name will be used to identify indexes in Algolia. Check out the Algolia index naming guide  to avoid problematic names. Read more to understand how Algolia indexing works .

3. Then, select a model to be included in Algolia searches.

4. Add a well-defined query to the GraphQL query section.

   Tip

   For the GraphQL query box, you can simply copy the GraphQL query you’ve set up for that model in your front-end and update it according to the guidelines below.

   To create a valid query and ensure the Algolia index is performant and relevant, follow these query guidelines:

   • Return a single item: The query needs to return a single content item. For example, query BlogPost and not BlogPosts. In other words, there should be no items array wrapper.

   • Include required filters: Add the locale and id arguments to the query.

   • Include relevant fields only: Only include fields that are searchable, filterable, or strictly required for rendering your search results UI (such as image URLs for search box thumbnails). Avoid system or presentational fields like background_color. You can use the mapping table below to help you decide which fields to include in your Algolia index query based on their types and intended search functionality.

     GraphQL Type	Examples
     String	Include fields users search by, like title and description. Don’t include presentational fields like background_color.
     Boolean	Include indicators used for filtering search results, such as premium_content or is_featured. Don’t include system fields like is_external_link.
     Float	Include for numerical filtering or sorting, such as product price or review_rating.
     Integer	Include for sorting or filtering, such as word_count or inventory_stock.
     Asset	In the asset object, include fields users search by, like caption or properties required for your search UI, for example, url to render search thumbnails for an SEO OG image or product images.
     Tag	Typically, you would include the body of the tag field.
     Date and time	You can include fields like an event_date for instance.

   • Strip comments: Make sure there are no comment lines (lines starting with #).

See an example of a valid query below with the required locale and id arguments.

query Query($locale: String!,$id: String) {
  BlogPost(locale: $locale, id: $id) {
      title
      cover {
        caption
      }
      description
      author {
        name
      }
      category
      elements {
        ... on ImageText {
          description
          title
        }
      }
      video {
        description
        name
        caption
      }
      keywords {
        body
        _id
      }
  }
}

6. If your query doesn’t match the expected format, for example, if there’s no id or locale argument, you’ll see a validation error below the query.

   

7. To have more control over syncing content to Algolia, you can disable the Auto sync option per model.

   If Auto sync is enabled for a model, Prepr will automatically keep syncing related content items to Algolia for indexing. This means, when a new content item for this model is published, one or more records will be created in Algolia. And any changes to the published content item result in updating the corresponding Algolia records. Once the content item is unpublished, the Algolia records will be removed. So you can be sure your data is always-in-sync, and that the most up-to-date content is available to your web app visitors.

8. Click Save to confirm the settings.

That’s it. You’ve connected Prepr and successfully added search indexes to Algolia.

Before sending your content item data to Algolia, Prepr automatically transforms it into a JSON format  that Algolia recognizes. Once data is prepared and synced, the corresponding records are created and stored in an Algolia index you specified.

Trigger content sync to Algolia

To sync content items to Algolia directly, first create a new access token with REST API scopes content_items and content_items_publish and bind a user to this token under Settings → Access tokens.

To sync content manually, call the given Prepr endpoint below and specify a model ID.

Get a mode ID by going to Schema → Model → → Copy Model ID.

Content items are synced in batches, and the overall time depends on the number of content items you have.

The following API request will sync content items to Algolia:

GET: https://mutation.prepr.io/publications/algolia/sync

{
   "model": {
       "id": "YOUR_MODEL_ID"
   }
}

Test setup directly in Algolia

Once your Prepr content is synced to Algolia for indexing, you can test the Search directly in Algolia.

1. Log in to the Algolia Dashboard and go to Search in the left sidebar.
2. In the Index page, enter example search keywords and check the results.

You can then see which entries are returned first in the search and if they match your expected test results.

To improve search results and performance, make sure to set up Algolia searchable attributes  for the searchable fields, such as the title and body.

To fine-tune the search results set up attributes for custom ranking .

Connect your front end to Algolia

Now that your Prepr data is indexed with Algolia, and you’re happy with the test results, you’re ready to implement Algolia in your web app.

Follow the Algolia instructions to set up the API client  for your programming language. After setting up the API client, you can initialize and connect it to Algolia.

Also, check out how to build a search UI with Algolia .

Add aliases to your index query

Update the search index query to fetch a content item multiple times using aliases for each record you want to create.

In this example, the blog post is being split up. The dynamic content (content) object is split up into the main post and testimonial, and the seo component is also queried separately. This results in three Algolia records per content item instead of one.

    query ($locale: String!,$id: String) {
        post: BlogPost (locale: $locale, id: $id) { 
            title
            excerpt
            content { 
                __typename
                ... on Text {
                    body
                    text
                }
                ... on Assets {
                    items {
                        name
                        description
                    }
                }
            }
        }
 
        testimonial: BlogPost (locale: $locale, id: $id) { 
            content { 
                __typename
                ... on Quote {
                    body
                }            
            }
        }
 
        seo: BlogPost (locale: $locale, id: $id) { 
            seo { 
                meta_title
                meta_description
            }
        }
    }

Add _id attribute to group records

Now that your query results in multiple Algolia records per content item, you need to make sure that Algolia groups these records for the same web page.

Do this by setting up the _id attribute for grouping records  in Algolia. _id is the ID of each content item, and prevents multiple search results for the same page.

1. Log in to your Algolia account, and navigate to Search in the sidebar.
2. Select your index at the top.
3. Click the Configuration tab.
4. Scroll down, click the Deduplication and Grouping side menu.
5. Important: Change the setting of Distinct to true or 1.
6. Type content_item_id to Attribute for Distinct and press enter.
7. Click the Review and Save Settings button to save your changes.