Typesense

Get the API credentials from your Typesense app

To connect Prepr to Typesense, you need a valid API key to create Typesense collections and index documents in collections. Typesense uses these credentials to identify your Prepr application and control access to the Typesense API.

There are two options to install Typesense, either with Typesense Cloud (opens in a new tab) or Self-hosting (opens in a new tab). If you choose to do self-hosting, make sure the host is public for Prepr to have access.

Once Typesense is installed, generate the API key according to the instructions in the Typesense installation docs. You'll need the Admin API key, Host, Protocol and Port when setting up the Typesense integration in Prepr.

Connect Prepr to Typesense

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

1. Go to Settings → Integrations and choose Typesense. Click the Activate button.

2. In the Typesense app page, enter your Typesense credentials from the previous step.

3. Select the models you want to sync to Typesense and map them to each Typesense collection. You can specify the existing collections you already have in your Typesense app, or you can provide new names from within Prepr. In the latter case, the collections with the relevant names will be created automatically once the data is synced to Typesense. Read more about the Typesense collections (opens in a new tab).

4. Click Save to confirm the settings.

That's it. You’ve connected Prepr to Typesense. From now on, Prepr will automatically keep syncing your content items to Typesense for indexing.

When a new content item is published, a new document is added to the related collection in Typesense. Any changes to the published content item result in updating the corresponding Typesense document. Once the content item is unpublished, the Typesense document will be deleted.

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.

Indexed field types

Before sending your content item data to Typesense, Prepr automatically transforms it into a JSON format (opens in a new tab) that Typesense recognizes. Once data is prepared and synced, the corresponding documents are added to the Typesense collection you specified above.

The following table shows indexed Prepr field types and the corresponding Typesense field types (opens in a new tab).

Configure your Typesense setup

The sections below show you how to set up your Typesense configuration for Prepr. This configuration improves search results in your web app, enhances ranking, supports searches for related content and a multi-language environment. Some of the steps below require you to configure facet fields in Typesense.

Enable auto-schema detection

You need to set up the .* wildcard as an auto field type (opens in a new tab) to enable auto-schema detection. This ensures that any unspecified fields in your documents are automatically detected and typed correctly. This step is essential for handling dynamic document structures in your Prepr schema.

To enable auto-schema detection, add the followings fields to your schema:

{
    "name": "YOUR_COLLECTION_NAME",
    "fields": [
        {
            "name": ".*",
            "type": "auto"
        }
    ]
}

Enable search on related content items

Include the associateIDs field as a facet field in your Typesense schema for related content items. This field is used to identify relationships between content items in Prepr. If a related content item is updated in Prepr, the corresponding record in Typesense can also be updated seamlessly. In this case, add the following fields to your schema:

{
    "name": "YOUR_COLLECTION_NAME",
    "fields": [
        {
            "name": "associateIDs",
            "type": "string[]",
            "facet": true
        }
    ]
}

Group related records to avoid duplicate results

Set up the distinctID field as a facet field to group related records, ensuring that search results only show unique entries. This avoids duplicate results for content with similar attributes. Add or verify the presence of the field in your schema like in the JSON below:

{
    "name": "YOUR_COLLECTION_NAME",
    "fields": [
        {
            "name": "distinctID",
            "type": "string",
            "facet": true
        }
    ]
}

Enable language code support

If you have localized content in Prepr, then it's important to enable the language code support to get accurate search results. Configure the locale field as a facet field to allow for locale-based filtering in your search results like in the JSON below.

{
    "name": "YOUR_COLLECTION_NAME",
    "fields": [
        {
            "name": "locale",
            "type": "string",
            "facet": true
        }
    ]
}

Example configuration

Collection configuration

To use the schema configuration example below, replace the name value YOUR_COLLECTION_NAME with the name of your Typesense collection or Prepr model, such as Article, Blogpost, or Product.

{
    "name": "YOUR_COLLECTION_NAME",
    "fields": [
        {
            "name": ".*",
            "type": "auto"
        },
        {
            "name": "associateIDs",
            "type": "string[]",
            "facet": true
        },
        {
            "name": "locale",
            "type": "string",
            "facet": true
        },
        {
            "name": "distinctID",
            "type": "string",
            "facet": true
        }
    ]
}

Search configuration

Check out a complete example of a Typesense search configuration below.

{
    "q": "search term",
    "query_by": "_body*,title,work_title",
    "facet_by": "locale",
    "filter_by": "locale:=en-US",
    "sort_by": "_level:asc,_text_match:desc",
    "distinct_by": "distinctID"
}

Connect your front end to Typesense

Now that your Prepr data is indexed with Typesense, you’re ready to implement Typesense in your web app.

Follow the Typesense instructions to install a client (opens in a new tab) for your programming language. After setting up the client, you can initialize and connect it to Typesense (opens in a new tab).

For examples on how to search records in your collections, check out the Searching for books (opens in a new tab) doc.

Also, check out how to build a search UI with Typesense (opens in a new tab).

Well done! You've reached the last step to enable the Typesense integration with Prepr content. After some time in production, you'll have content in Prepr and might make some changes to the Prepr schema. In that case, check out the next step to learn how to sync existing content and schema updates.

Sync existing content and schema updates to Typesense

The steps above allow you to index all new content created after enabling the Typesense integration. If you need to index any content you already have, or after a schema update, you need to run the sync action manually.

To sync content items to Typesense manually, you must call the given Prepr endpoint and specify a model ID, which you can find under Schema → Model → → Copy Model ID.

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

The following API request will sync content items to Typesense:

GET: https://api.eu1.prepr.io/publications/typesense/sync

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