Skip to main content

Attribute ranking

This page covers attribute ranking queries for ranking attribute values instead of items. For query fundamentals, see Query Basics.

An attribute ranking query returns the best attribute values for a given user. Instead of ranking items, this ranks attribute values like categories, genres, brands, or tags.

Common applications include:

  • Personalized category carousels ("Top categories for you")
  • Navigation that adapts to user preferences
  • Surfacing relevant filters or facets

Attribute ranking is particularly useful for building category pages and faceted filtering interfaces. Once you've identified the best categories for a user, you can use those categories in filtered queries to show personalized items within each category. See Faceted filtering and category pages for examples of combining attribute ranking with item ranking.

Rank attributes for user​

Prerequisites​

  1. An engine with item data containing the attribute you want to rank
  2. A user_id to personalize for

Query example​

Use the rank_attributes query type to find the best attribute values for a user. Note: ShapedQL support for attribute ranking is not currently available, so JSON format is required.

from shaped import RankAttributesQueryBuilder

# Create an attribute ranking query
query = (
    RankAttributesQueryBuilder()
    .for_attribute('category')  # The attribute to rank (e.g., 'brand', 'category', 'tag')
    .for_user('$user_id')      # User ID to personalize for
    .with_embedding('content_embedding')  # Embedding to use for ranking
    .with_limit(5)             # Number of top attributes to return
    .build()
)

# Example usage with client
# response = client.rank_attributes(
#     query=query,
#     parameters={
#         'user_id': '12345'
#     }
# )
# 
# # Access top categories
# top_categories = [attr['value'] for attr in response['attributes']]

Using attribute ranking with category pages​

After ranking attributes (e.g., categories) for a user, you can use those ranked attributes to build personalized category pages. The attribute ranking tells you which categories are most relevant to the user, and then you can query items within those categories using value models for fine-grained ranking.

For example, if attribute ranking returns "Electronics" as the top category for a user, you can then query items in that category with personalized scoring:

from shaped import RankQueryBuilder, ColumnOrder

# After getting top_category from attribute ranking
top_category = "Electronics"  # From attribute ranking response

# Create a query for items in the top category
query = (
    RankQueryBuilder()
    .from_entity('item')
    .retrieve(
        ColumnOrder(
            columns=['_derived_popular_rank ASC'],
            limit=1000,
            where=f"category = '{top_category}'"
        )
    )
    .score(
        value_model='0.6 * click_through_rate + 0.4 * conversion_rate',
        input_user_id='$user_id',
        input_interactions_item_ids='$interaction_item_ids'
    )
    .limit(20)
    .build()
)

# Example usage with client
# response = client.rank(
#     query=query,
#     parameters={
#         'user_id': 'user123'
#     }
# )

This two-step approach (attribute ranking → filtered item ranking) enables you to build personalized navigation and category pages that adapt to each user's preferences. Value models allow you to fine-tune the ranking within each category using ensembles, item attributes, and other signals.