Configuring Search Engine Personalized Boosts¶

The Search Configuration API allows you to programmatically manage personalized boosts for your Hello Retail search engine using GraphQL. This enables you to dynamically adjust how search results are ranked based on user behavior and Product Intelligence data.

Prerequisites¶

To use this API, you need: - Your search algorithm ID (found in your Hello Retail dashboard) - A valid API key (see how to generate one) - Access to the GraphQL endpoint

GraphQL Endpoint¶

https://core.helloretail.com/graphql?apiKey=YOUR_API_KEY

Schema Definition¶

Mutation¶

mutation updateSearchAlgorithmPersonalization(
  $personalization: SearchPersonalizationInput!
): SearchPersonalization!

Input Types¶

input SearchPersonalizationInput {
  algorithmId: ID!
  personalizedFields: [PersonalizationFieldInput!]!
}

input PersonalizationFieldInput {
  field: String!
  boostValue: Int!
}

Response Types¶

type SearchPersonalization {
  allowedFields: [String!]!
  availableFields: [String!]!
  personalizedFields: [PersonalizationField!]!
}

type PersonalizationField {
  field: String!
  boostValue: Int!
}

Available Personalization Fields¶

Common Product Intelligence fields you can use for personalization:

Field	Description
`product.pi.budgetZone`	Budget-based personalization based on user's purchasing behavior
`product.pi.productCluster`	Product cluster affinity based on user's browsing patterns
`product.pi.brandAffinity`	Brand preference based on user's interaction history
`product.pi.categoryAffinity`	Category preference based on user's browsing behavior
`product.pi.colorAffinity`	Color preference based on user's product views
`product.pi.sizeAffinity`	Size preference for fashion/apparel sites

Boost Values¶

Range: 1-10 (integer values only)
Default: 0 (no boost)
Recommendation: Start with lower values (1-3) and gradually increase based on results

Example Requests¶

Basic GraphQL Request¶

mutation UpdateSearchPersonalization {
  updateSearchAlgorithmPersonalization(
    personalization: {
      algorithmId: "1234"
      personalizedFields: [
        {
          field: "product.pi.budgetZone"
          boostValue: 5
        }
        {
          field: "product.pi.productCluster"
          boostValue: 3
        }
      ]
    }
  ) {
    allowedFields
    availableFields
    personalizedFields {
      field
      boostValue
    }
  }
}

Using Variables¶

mutation UpdateSearchPersonalization(
  $algorithmId: ID!
  $personalizedFields: [PersonalizationFieldInput!]!
) {
  updateSearchAlgorithmPersonalization(
    personalization: {
      algorithmId: $algorithmId
      personalizedFields: $personalizedFields
    }
  ) {
    allowedFields
    availableFields
    personalizedFields {
      field
      boostValue
    }
  }
}

With variables:

{
  "algorithmId": "1234",
  "personalizedFields": [
    {
      "field": "product.pi.budgetZone",
      "boostValue": 5
    },
    {
      "field": "product.pi.productCluster",
      "boostValue": 3
    }
  ]
}

Implementation Examples¶

JavaScript (Fetch API)¶

const updateSearchPersonalization = async (algorithmId, personalizedFields) => {
  const apiKey = 'YOUR_API_KEY';
  const endpoint = `https://core.helloretail.com/graphql?apiKey=${apiKey}`;

  const query = `
    mutation UpdateSearchPersonalization(
      $algorithmId: ID!
      $personalizedFields: [PersonalizationFieldInput!]!
    ) {
      updateSearchAlgorithmPersonalization(
        personalization: {
          algorithmId: $algorithmId
          personalizedFields: $personalizedFields
        }
      ) {
        allowedFields
        availableFields
        personalizedFields {
          field
          boostValue
        }
      }
    }
  `;

  const variables = {
    algorithmId: algorithmId,
    personalizedFields: personalizedFields
  };

  try {
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        query: query,
        variables: variables
      })
    });

    const data = await response.json();

    if (data.errors) {
      console.error('GraphQL errors:', data.errors);
      throw new Error('Failed to update personalization');
    }

    return data.data.updateSearchAlgorithmPersonalization;
  } catch (error) {
    console.error('Error updating search personalization:', error);
    throw error;
  }
};

// Usage example
const updatePersonalization = async () => {
  try {
    const result = await updateSearchPersonalization('1234', [
      { field: 'product.pi.budgetZone', boostValue: 5 },
      { field: 'product.pi.productCluster', boostValue: 3 },
      { field: 'product.pi.brandAffinity', boostValue: 2 }
    ]);

    console.log('Updated personalization:', result);
    console.log('Available fields:', result.availableFields);
    console.log('Current personalized fields:', result.personalizedFields);
  } catch (error) {
    console.error('Failed to update:', error);
  }
};

cURL Example¶

curl -X POST https://core.helloretail.com/graphql?apiKey=YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation UpdateSearchPersonalization($algorithmId: ID!, $personalizedFields: [PersonalizationFieldInput!]!) { updateSearchAlgorithmPersonalization(personalization: {algorithmId: $algorithmId, personalizedFields: $personalizedFields}) { allowedFields availableFields personalizedFields { field boostValue } } }",
    "variables": {
      "algorithmId": "1234",
      "personalizedFields": [
        {
          "field": "product.pi.budgetZone",
          "boostValue": 5
        },
        {
          "field": "product.pi.productCluster",
          "boostValue": 3
        }
      ]
    }
  }'

Response Example¶

A successful response will return:

{
  "data": {
    "updateSearchAlgorithmPersonalization": {
      "allowedFields": [
        "product.pi.budgetZone",
        "product.pi.productCluster",
        "product.pi.brandAffinity",
        "product.pi.categoryAffinity"
      ],
      "availableFields": [
        "product.pi.budgetZone",
        "product.pi.productCluster",
        "product.pi.brandAffinity",
        "product.pi.categoryAffinity",
        "product.pi.colorAffinity",
        "product.pi.sizeAffinity"
      ],
      "personalizedFields": [
        {
          "field": "product.pi.budgetZone",
          "boostValue": 5
        },
        {
          "field": "product.pi.productCluster",
          "boostValue": 3
        }
      ]
    }
  }
}

Best Practices¶

Start with small boost values: Begin with boost values of 1-3 and monitor the impact on search relevance
Use multiple fields: Combine different personalization fields for more nuanced results
Monitor performance: Track search conversion rates and user satisfaction after implementing boosts
Update incrementally: Make small adjustments rather than dramatic changes
Consider user segments: Different boost configurations may work better for different user types

Error Handling¶

Common errors and their solutions:

Error	Cause	Solution
`Invalid algorithm ID`	The provided algorithm ID doesn't exist	Verify the algorithm ID in your Hello Retail dashboard
`Invalid field name`	The personalization field is not available	Check the `availableFields` in the response
`Invalid boost value`	Boost value is outside the allowed range	Use integer values between 1 and 10
`Unauthorized`	Invalid or missing API key	Verify your API key is correct and active

Removing Personalization¶

To remove all personalized boosts, send an empty array:

const removePersonalization = async (algorithmId) => {
  const result = await updateSearchPersonalization(algorithmId, []);
  console.log('Personalization removed');
};

Getting Current Configuration¶

To retrieve the current personalization configuration without making changes, you can use the same mutation with the existing values or implement a separate query (if available in your Hello Retail setup).