> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Applying contextual affinities

> Learn how to apply contextual affinities with Advanced Personalization.

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

Contextual affinities are attributes that are relevant to your users only in specific contexts.
They ensure that certain preferences are applied only where they make sense, enhancing the relevance and accuracy of personalized search results.

For example, if a user buys white furniture, personalized search results could guide users to other white furniture items.
However, personalized search results for unrelated categories shouldn't be based on the user's color preferences. Preferring white furniture doesn't mean they prefer white hardware tools.

By applying contextual affinities, personalization becomes more precise and effective, providing your users with search results that truly match their interests and needs in the right context.

## Preparing your index

To enable contextual affinities, you can add a new attribute to your <Index /> manually or automate the process with a script.
This attribute stores context-specific details in each of your <Records />,
allowing for more relevant search results based on the user's situation.
The following example adds `hierarchicalAffinities` as a contextual affinity attribute:

```json JSON icon=braces theme={"system"}
[
  {
    "objectID": "0000001",
    "name": "Chair",
    "categories": {
      "lvl0": "Hard Goods",
      "lvl1": "Hard Goods > Desk Chairs",
    },
    "brand": "Nolan",
    "price": 10.99,
    "color": "White",
    "hierarchicalAffinities": ["Hard Goods > Desk Chairs > White"],
  },
  {
    "objectID": "0000002",
    "name": "iPhone 15",
    "categories": {
      "lvl0": "Hard Goods",
      "lvl1": "Hard Goods > Cell Phones",
      "lvl2": "Hard Goods > Cell Phones > Phones & Tablets",
    },
    "brand": "Apple",
    "price": 699.99,
    "color": "Gold",
    "hierarchicalAffinities": ["Hard Goods > Cell Phones > Gold", "Apple > Gold"],
  }
]
```

The first record is tagged with `Hard Goods > Desk Chairs > White`.
This approach ensures that user preferences, such as a liking for white chairs, are taken into account only when recommending desk chairs.

In the second record, the `hierarchicalAffinities` attribute is more flexible.
It categorizes the iPhone 15 under "Hard Goods" and "Cell Phones" specifying its color as "Gold" with `Hard Goods > Cell Phones > Gold` and also includes a brand-specific categorization under `Apple > Gold`.
This approach lets you capture detailed preferences like color and brand affinity within specific contexts.

## Adding a contextual affinity to your configuration

Once the contextual affinity has been added to all records in your index, the next step is to [declare it as a facet](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard).
Then, you can [select it as an affinity](/doc/guides/personalization/advanced-personalization/configure/setup/indices#select-the-attributes-for-affinities) in the Advanced Personalization dashboard [**Configuration**](https://dashboard.algolia.com/advanced-personalization/configuration/indices) page.

Here, you can streamline your configuration by consolidating attributes.
For example, instead of having a separate `color` or `brand` attribute in your setup, you can opt for a `hierarchicalAffinities` attribute which contains context-specific information about color and brand.