Prepare your index structure

To get the best results, set up your existing index’s structure to match the needs of Advanced Personalization. A well-prepared index structure helps this feature deliver personalized search for your website or app.

This feature isn’t available on every plan. Refer to your pricing plan to see if it’s included.

Use categorical attributes

Categorical attributes are attributes with a fixed number of possible string values. Adding such attributes to your index structure sorts your data into clear, smaller buckets. For example:

JSON

[
  {
    "objectID": "ID01",
    "title": "Chair",
    "color": "red",
    "categories": ["Furniture", "Outdoors"]
  },
  {
    "objectID": "ID02",
    "title": "Table",
    "color": "green",
    "categories": ["Furniture", "Outdoors"]
  },
  {
    "objectID": "ID03",
    "title": "Water bottle",
    "color": "blue",
    "categories": ["Outdoors"]
  },
  {
    "objectID": "ID04",
    "title": "Book",
    "color": "red",
    "categories": ["Books"]
  },
  {
    "objectID": "ID05",
    "title": "Headphones",
    "color": "green",
    "categories": ["Electronics"]
  },
  {
    "objectID": "ID06",
    "title": "Phone",
    "color": "blue",
    "categories": ["Electronics"]
  },
  {
    "objectID": "ID07",
    "title": "Television",
    "color": "red",
    "categories": ["Electronics"]
  },
  {
    "objectID": "ID08",
    "title": "Can",
    "color": "green",
    "categories": ["Cooking & Dining", "Kitchenware"]
  },
  {
    "objectID": "ID09",
    "title": "Bowl",
    "color": "blue",
    "categories": ["Cooking & Dining", "Kitchenware"]
  }
]

Good categorical attributes

An attribute like color with a fixed set of values, like red, green, and blue, is a good categorical attribute. It sorts your index into three clear buckets. Other good categorical attributes include gender, brand, and categories.

Bad categorical attributes

Attributes that are unique for each record, such as objectID and title, are poor choices. They don’t group data into buckets. Other poor categorical attributes include description, sku, and price.

Avoid nesting attributes

Aim to organize data within records with a flat structure. Reserve deeper nesting for hierarchical facets. Consider the following example of several nested keys:

JSON

{
  "key1": {
    "key2": {
      "key3": "value"
    }
  }
}

To make it easier for Advanced Personalization to process the index, simplify the attribute-value pair:

JSON

{
  "key1_key2_key3": "value"
}

To optimize performance, Advanced Personalization limits the number of key-value pairs for nested attributes to 50. This limit keeps processing of your nested attributes fast. If you need to exceed these constraints, contact the Algolia support team.

Avoid mixing attribute types

Keep a consistent type for each attribute. This is a key step in preparing your index structure.

JSON

[{ "color": "red" }, { "color": ["red", "blue"] }, { "color": 250000000 }]

Using this index as is would lead to unexpected results. This is because the attribute color can be a string, an array, or an integer. A structure like this often indicates an underlying issue with your data. Ensure a consistent type for your attributes.

JSON

[{ "color": "red" }, { "color": "green" }, { "color": "blue" }]

Avoid mixing attributes from different domains

When preparing your index structure, ensure that attributes are relevant to a single domain. For example, an index for articles shouldn’t contain attributes relevant to product information and vice versa. Language is a common domain that could lead to a mix of attributes within your index.

JSON

[
  {
    "objectID": "MH001",
    "color": "red",
    "title": "Bag"
  },
  {
    "objectID": "MH002",
    "color": "rouge",
    "title": "Sac"
  },
  {
    "objectID": "MH001",
    "color": "blue",
    "title": "Chair"
  }
]

The second record is doesn’t belong in this index because it has French language attributes. Review the index to ensure attributes from different domains aren’t mixed.

JSON

[
  {
    "objectID": "MH001",
    "color": "red",
    "title": "Bag"
  },
  {
    "objectID": "MH002",
    "color": "red",
    "title": "Bag"
  },
  {
    "objectID": "MH001",
    "color": "blue",
    "title": "Chair"
  }
]

How Advanced Personalization validates attributes

Advanced Personalization prioritizes attributes that directly improve personalization, building user profiles on meaningful data. It also filters out attributes based on user interactions.

An attribute-value pair must show significant user interaction. It doesn’t use a fixed benchmark. Instead, it looks for a large number of interactions. If Advanced Personalization randomly picks users from last month for the color:red attribute, it expects some users to have interacted with red products.
Discard attributes with minimal relevance. If an attribute applies to too few products, it’s often filtered out due to a lack of user interactions.
Discard attributes with excessive diversity. For example, Advanced Personalization might filter out an attribute like brand if it finds thousands of distinct brands across millions of products. This happens when no single brand gets enough user interactions to count as “important”.
Discard unusual attribute values. While attributes with many unique values aren’t discarded, Advanced Personalization doesn’t process the unusual values, for example, color:pink_with_brown_dots.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Prepare your index structure

Use categorical attributes

Good categorical attributes

Bad categorical attributes

Avoid nesting attributes

Avoid mixing attribute types

Avoid mixing attributes from different domains

How Advanced Personalization validates attributes

​Use categorical attributes

​Good categorical attributes

​Bad categorical attributes

​Avoid nesting attributes

​Avoid mixing attribute types

​Avoid mixing attributes from different domains

​How Advanced Personalization validates attributes

Use categorical attributes

Good categorical attributes

Bad categorical attributes

Avoid nesting attributes

Avoid mixing attribute types

Avoid mixing attributes from different domains

How Advanced Personalization validates attributes