Entities

This page introduces entities, how and why they can be used.

For most use cases, entities are not needed for Vertex AI Search for retail. However, retailers who serve multiple brands or regions from a single product catalog can get better results if they use entities.

Overview

Setting up multiple entities in your project is a way to take into consideration different behavior and preferences of shoppers who are in different regions or countries or who shop at differently branded sites that belong to your enterprise.

Example use case: two countries

A retailer, Example Organization, has a web presence in both the US and Canada.

Example Organization wants to serve browse and search results and autocomplete suggestions that take into account differences between the shoppers in the two countries. And so, Example Organization designates two entities: org_us and org_ca.

User events are tagged with an entity value, depending on which website the shopper visited (.com or ca). When a shopper makes a search request, the entity value is included in the request.

The two countries have important but different holidays in July. With entities set up, when shoppers search the Example Organization site for July, American shoppers are served Fourth of July themed items first and Canadian shoppers receive items themed for Canada Day.

Similarly, recommendations for Canadian shoppers are more likely to show Canada Day items than Fourth of July items.

Example use case: an acquisition

Enterprise Example Organization recently acquired Startup Example Organization. The catalogs have been combined but the Startup brand and website is being kept because it has a loyal following.

The enterprise creates an entity, startup, to tag user events originating from the Startup site. This allows the search, browse, autocomplete, and recommendation suggestions that are served to the Startup site to take into account the preferences of the Startup site's shoppers.

Multiple projects or multiple entities?

When you set up Vertex AI Search for retail, you can use different projects or different entities in the same project to get different suggestions for your different shopper populations.

For some applications, separate projects are required. For other applications, setting up entities is the better solution.

Use entities when you have:

• A fully or partially shared catalog between the entities

• One or more of the following:

  • Multiple brands in the same country or language area—for example, you have your original brand and an acquired brand, google_home and nest.

  • Multiple regions in the same country—for example, enterprise_east and enterprise_west.

  • One brand but in multiple countries with the same language—for example, brand_us and brand_ca.

Use separate projects instead of entities when you have:

• Catalogs that cannot be combined or catalogs that, if combined, have little or no overlap.

• Entities that require different languages. Only one language is allowed per project.

User events and entities

To take advantage of the entities feature, add the entity field to your user events.

• For search and autocomplete: include the entity field in user events of type search.

  Including the entity field in other user event types can be helpful for troubleshooting but does not affect the quality of the search or autocomplete responses.

• For recommendations: include the entity field in as many types of user event as you can.

Typically, it takes 30 to 90 days of user event data before the entity feature returns optimal suggestions.

If an entity is missing from a request, the request makes no assumption about the entity in the result. You'll get an average result that is based on user events with and without the entity specified.

Search and entities

To get search or browse results that take into account the entity:

1. Include the entity field in your search user events (eventType="search"). For an example, see the complete object example for the Search user event.

2. Add the entity field to your search request. For information about how to make search requests, see Get search results.

Autocomplete and entities

To get autocomplete results that take into account the entity:

• Follow the instructions in Auto-learning dataset and Suggestion filtered by entity.

Recommendations and entities

After you have added the entity field to your user events, no further action is required to take advantage of entities for recommendations. This is because the entity value is part of the user event, which, in turn, is included in the call to the predict method.