tessl/pypi-google-cloud-retail
Python client library for Google Cloud Retail API enabling end-to-end personalized recommendation systems
—
Pending
catalog-config.mddocs/
Catalog Configuration
Management of catalog settings, attributes, branches, and completion configurations. The Catalog Service provides comprehensive control over your product catalog structure, search behavior, and data organization.
Capabilities
Catalog Management
Core catalog operations and configuration management for organizing product data.
class CatalogServiceClient:
def list_catalogs(self, request: ListCatalogsRequest) -> ListCatalogsResponse:
"""
Lists all catalogs in a project location.
Args:
request: Contains parent location and pagination parameters
Returns:
ListCatalogsResponse: Available catalogs with pagination support
"""
def update_catalog(self, request: UpdateCatalogRequest) -> Catalog:
"""
Updates catalog configuration and metadata.
Args:
request: Contains catalog updates and field mask
Returns:
Catalog: Updated catalog configuration
"""Branch Management
Management of catalog branches for organizing product data across different environments.
class CatalogServiceClient:
def get_default_branch(self, request: GetDefaultBranchRequest) -> GetDefaultBranchResponse:
"""
Gets the default branch for a catalog.
Args:
request: Contains catalog resource name
Returns:
GetDefaultBranchResponse: Default branch information
"""
def set_default_branch(self, request: SetDefaultBranchRequest) -> None:
"""
Sets the default branch for a catalog.
Args:
request: Contains catalog and branch resource names
"""Attribute Configuration
Management of catalog and product-level attribute configurations for search and filtering.
class CatalogServiceClient:
def get_attributes_config(self, request: GetAttributesConfigRequest) -> AttributesConfig:
"""
Gets the current attributes configuration for a catalog.
Args:
request: Contains attributes config resource name
Returns:
AttributesConfig: Current attribute configuration settings
"""
def update_attributes_config(self, request: UpdateAttributesConfigRequest) -> AttributesConfig:
"""
Updates the attributes configuration for a catalog.
Args:
request: Contains attributes config updates and field mask
Returns:
AttributesConfig: Updated attribute configuration
"""
def add_catalog_attribute(self, request: AddCatalogAttributeRequest) -> AttributesConfig:
"""
Adds a new catalog attribute for search and filtering.
Args:
request: Contains attribute configuration to add
Returns:
AttributesConfig: Updated attributes configuration
"""
def remove_catalog_attribute(self, request: RemoveCatalogAttributeRequest) -> AttributesConfig:
"""
Removes a catalog attribute.
Args:
request: Contains attribute key to remove
Returns:
AttributesConfig: Updated attributes configuration
"""
def replace_catalog_attribute(self, request: ReplaceCatalogAttributeRequest) -> AttributesConfig:
"""
Replaces an existing catalog attribute configuration.
Args:
request: Contains attribute key and new configuration
Returns:
AttributesConfig: Updated attributes configuration
"""Completion Configuration
Management of search query auto-completion settings and data sources.
class CatalogServiceClient:
def get_completion_config(self, request: GetCompletionConfigRequest) -> CompletionConfig:
"""
Gets the completion configuration for a catalog.
Args:
request: Contains completion config resource name
Returns:
CompletionConfig: Current completion configuration settings
"""
def update_completion_config(self, request: UpdateCompletionConfigRequest) -> CompletionConfig:
"""
Updates the completion configuration for a catalog.
Args:
request: Contains completion config updates and field mask
Returns:
CompletionConfig: Updated completion configuration
"""Async Client
Asynchronous client for catalog service operations, providing the same functionality as CatalogServiceClient with async/await support.
class CatalogServiceAsyncClient:
async def list_catalogs(self, request: ListCatalogsRequest) -> ListCatalogsResponse:
"""
Asynchronously lists all catalogs in a project location.
Args:
request: Contains parent location and pagination parameters
Returns:
ListCatalogsResponse: Available catalogs with pagination support
"""
async def update_catalog(self, request: UpdateCatalogRequest) -> Catalog:
"""
Asynchronously updates catalog configuration and metadata.
Args:
request: Contains catalog updates and field mask
Returns:
Catalog: Updated catalog configuration
"""
async def get_completion_config(self, request: GetCompletionConfigRequest) -> CompletionConfig:
"""
Asynchronously gets the completion configuration for a catalog.
Args:
request: Contains completion config resource name
Returns:
CompletionConfig: Current completion configuration settings
"""
async def add_catalog_attribute(self, request: AddCatalogAttributeRequest) -> AttributesConfig:
"""
Asynchronously adds a new catalog attribute for search and filtering.
Args:
request: Contains attribute configuration to add
Returns:
AttributesConfig: Updated attributes configuration
"""
async def get_default_branch(self, request: GetDefaultBranchRequest) -> GetDefaultBranchResponse:
"""
Asynchronously gets the default branch for a catalog.
Args:
request: Contains catalog resource name
Returns:
GetDefaultBranchResponse: Default branch information
"""
async def set_default_branch(self, request: SetDefaultBranchRequest) -> None:
"""
Asynchronously sets the default branch for a catalog.
Args:
request: Contains catalog and branch resource names
"""
async def get_attributes_config(self, request: GetAttributesConfigRequest) -> AttributesConfig:
"""
Asynchronously gets the current attributes configuration for a catalog.
Args:
request: Contains attributes config resource name
Returns:
AttributesConfig: Current attribute configuration settings
"""
async def update_attributes_config(self, request: UpdateAttributesConfigRequest) -> AttributesConfig:
"""
Asynchronously updates the attributes configuration for a catalog.
Args:
request: Contains attributes config updates and field mask
Returns:
AttributesConfig: Updated attribute configuration
"""
async def remove_catalog_attribute(self, request: RemoveCatalogAttributeRequest) -> AttributesConfig:
"""
Asynchronously removes a catalog attribute.
Args:
request: Contains attribute key to remove
Returns:
AttributesConfig: Updated attributes configuration
"""
async def replace_catalog_attribute(self, request: ReplaceCatalogAttributeRequest) -> AttributesConfig:
"""
Asynchronously replaces an existing catalog attribute configuration.
Args:
request: Contains attribute key and new configuration
Returns:
AttributesConfig: Updated attributes configuration
"""
async def update_completion_config(self, request: UpdateCompletionConfigRequest) -> CompletionConfig:
"""
Asynchronously updates the completion configuration for a catalog.
Args:
request: Contains completion config updates and field mask
Returns:
CompletionConfig: Updated completion configuration
"""Data Types
Catalog
Core catalog entity containing configuration and metadata for product organization.
class Catalog:
name: str # Catalog resource name (read-only)
display_name: str # Human-readable catalog name
product_level_config: ProductLevelConfig # Product-level configuration settings
merchant_center_linking_config: MerchantCenterLinkingConfig # Merchant Center integrationProduct Level Configuration
Configuration settings that apply to all products in the catalog.
class ProductLevelConfig:
ingestion_product_type: str # Expected product type for ingestion
merchant_center_product_id_field: str # Field mapping for Merchant Center product IDsAttributes Configuration
Comprehensive attribute configuration for search, filtering, and faceting capabilities.
class AttributesConfig:
name: str # Attributes config resource name (read-only)
catalog_attributes: Dict[str, CatalogAttribute] # Catalog-level attribute configurations
attribute_config_level: AttributeConfigLevel # CATALOG_LEVEL_ATTRIBUTE_CONFIG or PRODUCT_LEVEL_ATTRIBUTE_CONFIG
class CatalogAttribute:
key: str # Attribute key/name (required)
in_use: bool # Whether attribute is currently being used (read-only)
type: AttributeType # UNKNOWN, TEXTUAL, NUMERICAL
indexable_option: CatalogAttributeIndexableOption # Indexing behavior
dynamic_facetable_option: CatalogAttributeDynamicFacetableOption # Dynamic faceting behavior
searchable_option: CatalogAttributeSearchableOption # Search behavior
exact_searchable_option: CatalogAttributeExactSearchableOption # Exact matching behavior
retrievable_option: CatalogAttributeRetrievableOption # Retrieval behavior
class AttributeConfigLevel(Enum):
ATTRIBUTE_CONFIG_LEVEL_UNSPECIFIED = 0
PRODUCT_LEVEL_ATTRIBUTE_CONFIG = 1 # Configured at product level
CATALOG_LEVEL_ATTRIBUTE_CONFIG = 2 # Configured at catalog level
# Attribute Option Enums
class CatalogAttributeIndexableOption(Enum):
INDEXABLE_OPTION_UNSPECIFIED = 0
INDEXABLE_ENABLED = 1 # Attribute values are indexed
INDEXABLE_DISABLED = 2 # Attribute values are not indexed
class CatalogAttributeDynamicFacetableOption(Enum):
DYNAMIC_FACETABLE_OPTION_UNSPECIFIED = 0
DYNAMIC_FACETABLE_ENABLED = 1 # Can be used for dynamic faceting
DYNAMIC_FACETABLE_DISABLED = 2 # Cannot be used for dynamic faceting
class CatalogAttributeSearchableOption(Enum):
SEARCHABLE_OPTION_UNSPECIFIED = 0
SEARCHABLE_ENABLED = 1 # Attribute is searchable
SEARCHABLE_DISABLED = 2 # Attribute is not searchable
class CatalogAttributeExactSearchableOption(Enum):
EXACT_SEARCHABLE_OPTION_UNSPECIFIED = 0
EXACT_SEARCHABLE_ENABLED = 1 # Supports exact matching
EXACT_SEARCHABLE_DISABLED = 2 # Does not support exact matching
class CatalogAttributeRetrievableOption(Enum):
RETRIEVABLE_OPTION_UNSPECIFIED = 0
RETRIEVABLE_ENABLED = 1 # Included in search results
RETRIEVABLE_DISABLED = 2 # Not included in search resultsCompletion Configuration
Settings for search query auto-completion functionality and data sources.
class CompletionConfig:
name: str # Completion config resource name (read-only)
matching_order: str # Order of completion matching
max_suggestions: int # Maximum completion suggestions to return
min_prefix_length: int # Minimum query prefix length for completions
auto_learning: bool # Enable automatic learning from user queries
denylist_input_config: CompletionDataInputConfig # Blocked terms configuration
allowlist_input_config: CompletionDataInputConfig # Allowed terms configuration
last_denylist_import_operation: str # Last denylist import operation (read-only)
last_allowlist_import_operation: str # Last allowlist import operation (read-only)
last_suggestions_import_operation: str # Last suggestions import operation (read-only)
suggestions_input_config: CompletionDataInputConfig # Custom suggestions configuration
class CompletionDataInputConfig:
big_query_source: BigQuerySource # BigQuery data source
# Additional source types can be added hereRequest Types
Comprehensive request configurations for catalog management operations.
class ListCatalogsRequest:
parent: str # Location resource name (required)
page_size: int # Maximum catalogs to return
page_token: str # Token for pagination
class UpdateCatalogRequest:
catalog: Catalog # Catalog with updates (required)
update_mask: FieldMask # Fields to update
class GetDefaultBranchRequest:
catalog: str # Catalog resource name (required)
class SetDefaultBranchRequest:
catalog: str # Catalog resource name (required)
branch_id: str # Branch ID to set as default
note: str # Optional note for the change
force: bool # Force change even if branch has no products
class GetAttributesConfigRequest:
name: str # Attributes config resource name (required)
class UpdateAttributesConfigRequest:
attributes_config: AttributesConfig # Config with updates (required)
update_mask: FieldMask # Fields to update
class AddCatalogAttributeRequest:
attributes_config: str # Attributes config resource name (required)
catalog_attribute: CatalogAttribute # Attribute to add (required)
class RemoveCatalogAttributeRequest:
attributes_config: str # Attributes config resource name (required)
key: str # Attribute key to remove (required)
class ReplaceCatalogAttributeRequest:
attributes_config: str # Attributes config resource name (required)
catalog_attribute: CatalogAttribute # New attribute configuration (required)
update_mask: FieldMask # Fields to update
class GetCompletionConfigRequest:
name: str # Completion config resource name (required)
class UpdateCompletionConfigRequest:
completion_config: CompletionConfig # Config with updates (required)
update_mask: FieldMask # Fields to updateUsage Examples
Catalog Management
from google.cloud import retail
client = retail.CatalogServiceClient()
# List all catalogs in a location
request = retail.ListCatalogsRequest(
parent="projects/my-project/locations/global"
)
response = client.list_catalogs(request=request)
print("Available catalogs:")
for catalog in response.catalogs:
print(f"- {catalog.display_name}")
print(f" Name: {catalog.name}")
print(f" Product Level Config: {catalog.product_level_config}")
# Update catalog configuration
catalog_name = "projects/my-project/locations/global/catalogs/default_catalog"
updated_catalog = retail.Catalog(
name=catalog_name,
display_name="My Updated Catalog",
product_level_config=retail.ProductLevelConfig(
ingestion_product_type="PRIMARY"
)
)
request = retail.UpdateCatalogRequest(
catalog=updated_catalog,
update_mask=field_mask_pb2.FieldMask(paths=["display_name", "product_level_config"])
)
updated = client.update_catalog(request=request)
print(f"Updated catalog: {updated.display_name}")Branch Management
# Get default branch
request = retail.GetDefaultBranchRequest(
catalog="projects/my-project/locations/global/catalogs/default_catalog"
)
response = client.get_default_branch(request=request)
print(f"Default branch: {response.branch}")
print(f"Set time: {response.set_time}")
print(f"Note: {response.note}")
# Set a new default branch
request = retail.SetDefaultBranchRequest(
catalog="projects/my-project/locations/global/catalogs/default_catalog",
branch_id="production_branch",
note="Switching to production branch for live traffic",
force=False
)
client.set_default_branch(request=request)
print("Default branch updated successfully")Attribute Configuration Management
# Get current attributes configuration
request = retail.GetAttributesConfigRequest(
name="projects/my-project/locations/global/catalogs/default_catalog/attributesConfig"
)
attributes_config = client.get_attributes_config(request=request)
print(f"Current attribute config level: {attributes_config.attribute_config_level}")
print(f"Number of configured attributes: {len(attributes_config.catalog_attributes)}")
# Add a new catalog attribute for search and faceting
new_attribute = retail.CatalogAttribute(
key="brand",
type=retail.CatalogAttribute.AttributeType.TEXTUAL,
indexable_option=retail.CatalogAttribute.IndexableOption.INDEXABLE_ENABLED,
dynamic_facetable_option=retail.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_ENABLED,
searchable_option=retail.CatalogAttribute.SearchableOption.SEARCHABLE_ENABLED,
exact_searchable_option=retail.CatalogAttribute.ExactSearchableOption.EXACT_SEARCHABLE_ENABLED,
retrievable_option=retail.CatalogAttribute.RetrievableOption.RETRIEVABLE_ENABLED
)
request = retail.AddCatalogAttributeRequest(
attributes_config="projects/my-project/locations/global/catalogs/default_catalog/attributesConfig",
catalog_attribute=new_attribute
)
updated_config = client.add_catalog_attribute(request=request)
print(f"Added attribute 'brand'. Total attributes: {len(updated_config.catalog_attributes)}")
# Update an existing attribute
existing_attribute = updated_config.catalog_attributes["brand"]
existing_attribute.dynamic_facetable_option = retail.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_DISABLED
request = retail.ReplaceCatalogAttributeRequest(
attributes_config="projects/my-project/locations/global/catalogs/default_catalog/attributesConfig",
catalog_attribute=existing_attribute,
update_mask=field_mask_pb2.FieldMask(paths=["dynamic_facetable_option"])
)
updated_config = client.replace_catalog_attribute(request=request)
print("Updated brand attribute configuration")Completion Configuration
# Get current completion configuration
request = retail.GetCompletionConfigRequest(
name="projects/my-project/locations/global/catalogs/default_catalog/completionConfig"
)
completion_config = client.get_completion_config(request=request)
print(f"Current completion config:")
print(f"- Max suggestions: {completion_config.max_suggestions}")
print(f"- Min prefix length: {completion_config.min_prefix_length}")
print(f"- Auto learning: {completion_config.auto_learning}")
# Update completion configuration
updated_config = retail.CompletionConfig(
name=completion_config.name,
max_suggestions=15,
min_prefix_length=2,
auto_learning=True,
matching_order="order-by-score-desc"
)
request = retail.UpdateCompletionConfigRequest(
completion_config=updated_config,
update_mask=field_mask_pb2.FieldMask(paths=[
"max_suggestions",
"min_prefix_length",
"auto_learning",
"matching_order"
])
)
updated = client.update_completion_config(request=request)
print("Completion configuration updated:")
print(f"- Max suggestions: {updated.max_suggestions}")
print(f"- Min prefix length: {updated.min_prefix_length}")
print(f"- Auto learning: {updated.auto_learning}")Advanced Attribute Configuration
# Configure multiple attributes for a comprehensive product catalog
attributes_to_add = [
retail.CatalogAttribute(
key="color",
type=retail.CatalogAttribute.AttributeType.TEXTUAL,
indexable_option=retail.CatalogAttribute.IndexableOption.INDEXABLE_ENABLED,
dynamic_facetable_option=retail.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_ENABLED,
searchable_option=retail.CatalogAttribute.SearchableOption.SEARCHABLE_ENABLED,
retrievable_option=retail.CatalogAttribute.RetrievableOption.RETRIEVABLE_ENABLED
),
retail.CatalogAttribute(
key="price_range",
type=retail.CatalogAttribute.AttributeType.NUMERICAL,
indexable_option=retail.CatalogAttribute.IndexableOption.INDEXABLE_ENABLED,
dynamic_facetable_option=retail.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_ENABLED,
searchable_option=retail.CatalogAttribute.SearchableOption.SEARCHABLE_DISABLED,
retrievable_option=retail.CatalogAttribute.RetrievableOption.RETRIEVABLE_ENABLED
),
retail.CatalogAttribute(
key="customer_rating",
type=retail.CatalogAttribute.AttributeType.NUMERICAL,
indexable_option=retail.CatalogAttribute.IndexableOption.INDEXABLE_ENABLED,
dynamic_facetable_option=retail.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_ENABLED,
searchable_option=retail.CatalogAttribute.SearchableOption.SEARCHABLE_DISABLED,
retrievable_option=retail.CatalogAttribute.RetrievableOption.RETRIEVABLE_ENABLED
)
]
attributes_config_name = "projects/my-project/locations/global/catalogs/default_catalog/attributesConfig"
# Add each attribute
for attribute in attributes_to_add:
request = retail.AddCatalogAttributeRequest(
attributes_config=attributes_config_name,
catalog_attribute=attribute
)
try:
updated_config = client.add_catalog_attribute(request=request)
print(f"Added attribute: {attribute.key}")
except Exception as e:
print(f"Failed to add attribute {attribute.key}: {e}")
# Get final configuration
final_config = client.get_attributes_config(
request=retail.GetAttributesConfigRequest(name=attributes_config_name)
)
print(f"\nFinal attribute configuration:")
for key, attr in final_config.catalog_attributes.items():
print(f"- {key}: {attr.type}, indexable={attr.indexable_option}, facetable={attr.dynamic_facetable_option}")Completion Data Management
# Configure custom completion suggestions from BigQuery
completion_data_config = retail.CompletionDataInputConfig(
big_query_source=retail.BigQuerySource(
project_id="my-project",
dataset_id="retail_data",
table_id="completion_suggestions",
data_schema="suggestion"
)
)
updated_config = retail.CompletionConfig(
name="projects/my-project/locations/global/catalogs/default_catalog/completionConfig",
suggestions_input_config=completion_data_config,
max_suggestions=20,
min_prefix_length=1,
auto_learning=True
)
request = retail.UpdateCompletionConfigRequest(
completion_config=updated_config,
update_mask=field_mask_pb2.FieldMask(paths=[
"suggestions_input_config",
"max_suggestions",
"min_prefix_length"
])
)
updated = client.update_completion_config(request=request)
print("Updated completion config with custom suggestions from BigQuery")
print(f"Suggestions import operation: {updated.last_suggestions_import_operation}")Install with Tessl CLI
npx tessl i tessl/pypi-google-cloud-retail