0
# Catalog Configuration
1
2
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.
3
4
## Capabilities
5
6
### Catalog Management
7
8
Core catalog operations and configuration management for organizing product data.
9
10
```python { .api }
11
class CatalogServiceClient:
12
def list_catalogs(self, request: ListCatalogsRequest) -> ListCatalogsResponse:
13
"""
14
Lists all catalogs in a project location.
15
16
Args:
17
request: Contains parent location and pagination parameters
18
19
Returns:
20
ListCatalogsResponse: Available catalogs with pagination support
21
"""
22
23
def update_catalog(self, request: UpdateCatalogRequest) -> Catalog:
24
"""
25
Updates catalog configuration and metadata.
26
27
Args:
28
request: Contains catalog updates and field mask
29
30
Returns:
31
Catalog: Updated catalog configuration
32
"""
33
```
34
35
### Branch Management
36
37
Management of catalog branches for organizing product data across different environments.
38
39
```python { .api }
40
class CatalogServiceClient:
41
def get_default_branch(self, request: GetDefaultBranchRequest) -> GetDefaultBranchResponse:
42
"""
43
Gets the default branch for a catalog.
44
45
Args:
46
request: Contains catalog resource name
47
48
Returns:
49
GetDefaultBranchResponse: Default branch information
50
"""
51
52
def set_default_branch(self, request: SetDefaultBranchRequest) -> None:
53
"""
54
Sets the default branch for a catalog.
55
56
Args:
57
request: Contains catalog and branch resource names
58
"""
59
```
60
61
### Attribute Configuration
62
63
Management of catalog and product-level attribute configurations for search and filtering.
64
65
```python { .api }
66
class CatalogServiceClient:
67
def get_attributes_config(self, request: GetAttributesConfigRequest) -> AttributesConfig:
68
"""
69
Gets the current attributes configuration for a catalog.
70
71
Args:
72
request: Contains attributes config resource name
73
74
Returns:
75
AttributesConfig: Current attribute configuration settings
76
"""
77
78
def update_attributes_config(self, request: UpdateAttributesConfigRequest) -> AttributesConfig:
79
"""
80
Updates the attributes configuration for a catalog.
81
82
Args:
83
request: Contains attributes config updates and field mask
84
85
Returns:
86
AttributesConfig: Updated attribute configuration
87
"""
88
89
def add_catalog_attribute(self, request: AddCatalogAttributeRequest) -> AttributesConfig:
90
"""
91
Adds a new catalog attribute for search and filtering.
92
93
Args:
94
request: Contains attribute configuration to add
95
96
Returns:
97
AttributesConfig: Updated attributes configuration
98
"""
99
100
def remove_catalog_attribute(self, request: RemoveCatalogAttributeRequest) -> AttributesConfig:
101
"""
102
Removes a catalog attribute.
103
104
Args:
105
request: Contains attribute key to remove
106
107
Returns:
108
AttributesConfig: Updated attributes configuration
109
"""
110
111
def replace_catalog_attribute(self, request: ReplaceCatalogAttributeRequest) -> AttributesConfig:
112
"""
113
Replaces an existing catalog attribute configuration.
114
115
Args:
116
request: Contains attribute key and new configuration
117
118
Returns:
119
AttributesConfig: Updated attributes configuration
120
"""
121
```
122
123
### Completion Configuration
124
125
Management of search query auto-completion settings and data sources.
126
127
```python { .api }
128
class CatalogServiceClient:
129
def get_completion_config(self, request: GetCompletionConfigRequest) -> CompletionConfig:
130
"""
131
Gets the completion configuration for a catalog.
132
133
Args:
134
request: Contains completion config resource name
135
136
Returns:
137
CompletionConfig: Current completion configuration settings
138
"""
139
140
def update_completion_config(self, request: UpdateCompletionConfigRequest) -> CompletionConfig:
141
"""
142
Updates the completion configuration for a catalog.
143
144
Args:
145
request: Contains completion config updates and field mask
146
147
Returns:
148
CompletionConfig: Updated completion configuration
149
"""
150
```
151
152
## Async Client
153
154
Asynchronous client for catalog service operations, providing the same functionality as CatalogServiceClient with async/await support.
155
156
```python { .api }
157
class CatalogServiceAsyncClient:
158
async def list_catalogs(self, request: ListCatalogsRequest) -> ListCatalogsResponse:
159
"""
160
Asynchronously lists all catalogs in a project location.
161
162
Args:
163
request: Contains parent location and pagination parameters
164
165
Returns:
166
ListCatalogsResponse: Available catalogs with pagination support
167
"""
168
169
async def update_catalog(self, request: UpdateCatalogRequest) -> Catalog:
170
"""
171
Asynchronously updates catalog configuration and metadata.
172
173
Args:
174
request: Contains catalog updates and field mask
175
176
Returns:
177
Catalog: Updated catalog configuration
178
"""
179
180
async def get_completion_config(self, request: GetCompletionConfigRequest) -> CompletionConfig:
181
"""
182
Asynchronously gets the completion configuration for a catalog.
183
184
Args:
185
request: Contains completion config resource name
186
187
Returns:
188
CompletionConfig: Current completion configuration settings
189
"""
190
191
async def add_catalog_attribute(self, request: AddCatalogAttributeRequest) -> AttributesConfig:
192
"""
193
Asynchronously adds a new catalog attribute for search and filtering.
194
195
Args:
196
request: Contains attribute configuration to add
197
198
Returns:
199
AttributesConfig: Updated attributes configuration
200
"""
201
202
async def get_default_branch(self, request: GetDefaultBranchRequest) -> GetDefaultBranchResponse:
203
"""
204
Asynchronously gets the default branch for a catalog.
205
206
Args:
207
request: Contains catalog resource name
208
209
Returns:
210
GetDefaultBranchResponse: Default branch information
211
"""
212
213
async def set_default_branch(self, request: SetDefaultBranchRequest) -> None:
214
"""
215
Asynchronously sets the default branch for a catalog.
216
217
Args:
218
request: Contains catalog and branch resource names
219
"""
220
221
async def get_attributes_config(self, request: GetAttributesConfigRequest) -> AttributesConfig:
222
"""
223
Asynchronously gets the current attributes configuration for a catalog.
224
225
Args:
226
request: Contains attributes config resource name
227
228
Returns:
229
AttributesConfig: Current attribute configuration settings
230
"""
231
232
async def update_attributes_config(self, request: UpdateAttributesConfigRequest) -> AttributesConfig:
233
"""
234
Asynchronously updates the attributes configuration for a catalog.
235
236
Args:
237
request: Contains attributes config updates and field mask
238
239
Returns:
240
AttributesConfig: Updated attribute configuration
241
"""
242
243
async def remove_catalog_attribute(self, request: RemoveCatalogAttributeRequest) -> AttributesConfig:
244
"""
245
Asynchronously removes a catalog attribute.
246
247
Args:
248
request: Contains attribute key to remove
249
250
Returns:
251
AttributesConfig: Updated attributes configuration
252
"""
253
254
async def replace_catalog_attribute(self, request: ReplaceCatalogAttributeRequest) -> AttributesConfig:
255
"""
256
Asynchronously replaces an existing catalog attribute configuration.
257
258
Args:
259
request: Contains attribute key and new configuration
260
261
Returns:
262
AttributesConfig: Updated attributes configuration
263
"""
264
265
async def update_completion_config(self, request: UpdateCompletionConfigRequest) -> CompletionConfig:
266
"""
267
Asynchronously updates the completion configuration for a catalog.
268
269
Args:
270
request: Contains completion config updates and field mask
271
272
Returns:
273
CompletionConfig: Updated completion configuration
274
"""
275
```
276
277
## Data Types
278
279
### Catalog
280
281
Core catalog entity containing configuration and metadata for product organization.
282
283
```python { .api }
284
class Catalog:
285
name: str # Catalog resource name (read-only)
286
display_name: str # Human-readable catalog name
287
product_level_config: ProductLevelConfig # Product-level configuration settings
288
merchant_center_linking_config: MerchantCenterLinkingConfig # Merchant Center integration
289
```
290
291
### Product Level Configuration
292
293
Configuration settings that apply to all products in the catalog.
294
295
```python { .api }
296
class ProductLevelConfig:
297
ingestion_product_type: str # Expected product type for ingestion
298
merchant_center_product_id_field: str # Field mapping for Merchant Center product IDs
299
```
300
301
### Attributes Configuration
302
303
Comprehensive attribute configuration for search, filtering, and faceting capabilities.
304
305
```python { .api }
306
class AttributesConfig:
307
name: str # Attributes config resource name (read-only)
308
catalog_attributes: Dict[str, CatalogAttribute] # Catalog-level attribute configurations
309
attribute_config_level: AttributeConfigLevel # CATALOG_LEVEL_ATTRIBUTE_CONFIG or PRODUCT_LEVEL_ATTRIBUTE_CONFIG
310
311
class CatalogAttribute:
312
key: str # Attribute key/name (required)
313
in_use: bool # Whether attribute is currently being used (read-only)
314
type: AttributeType # UNKNOWN, TEXTUAL, NUMERICAL
315
indexable_option: CatalogAttributeIndexableOption # Indexing behavior
316
dynamic_facetable_option: CatalogAttributeDynamicFacetableOption # Dynamic faceting behavior
317
searchable_option: CatalogAttributeSearchableOption # Search behavior
318
exact_searchable_option: CatalogAttributeExactSearchableOption # Exact matching behavior
319
retrievable_option: CatalogAttributeRetrievableOption # Retrieval behavior
320
321
class AttributeConfigLevel(Enum):
322
ATTRIBUTE_CONFIG_LEVEL_UNSPECIFIED = 0
323
PRODUCT_LEVEL_ATTRIBUTE_CONFIG = 1 # Configured at product level
324
CATALOG_LEVEL_ATTRIBUTE_CONFIG = 2 # Configured at catalog level
325
326
# Attribute Option Enums
327
class CatalogAttributeIndexableOption(Enum):
328
INDEXABLE_OPTION_UNSPECIFIED = 0
329
INDEXABLE_ENABLED = 1 # Attribute values are indexed
330
INDEXABLE_DISABLED = 2 # Attribute values are not indexed
331
332
class CatalogAttributeDynamicFacetableOption(Enum):
333
DYNAMIC_FACETABLE_OPTION_UNSPECIFIED = 0
334
DYNAMIC_FACETABLE_ENABLED = 1 # Can be used for dynamic faceting
335
DYNAMIC_FACETABLE_DISABLED = 2 # Cannot be used for dynamic faceting
336
337
class CatalogAttributeSearchableOption(Enum):
338
SEARCHABLE_OPTION_UNSPECIFIED = 0
339
SEARCHABLE_ENABLED = 1 # Attribute is searchable
340
SEARCHABLE_DISABLED = 2 # Attribute is not searchable
341
342
class CatalogAttributeExactSearchableOption(Enum):
343
EXACT_SEARCHABLE_OPTION_UNSPECIFIED = 0
344
EXACT_SEARCHABLE_ENABLED = 1 # Supports exact matching
345
EXACT_SEARCHABLE_DISABLED = 2 # Does not support exact matching
346
347
class CatalogAttributeRetrievableOption(Enum):
348
RETRIEVABLE_OPTION_UNSPECIFIED = 0
349
RETRIEVABLE_ENABLED = 1 # Included in search results
350
RETRIEVABLE_DISABLED = 2 # Not included in search results
351
```
352
353
### Completion Configuration
354
355
Settings for search query auto-completion functionality and data sources.
356
357
```python { .api }
358
class CompletionConfig:
359
name: str # Completion config resource name (read-only)
360
matching_order: str # Order of completion matching
361
max_suggestions: int # Maximum completion suggestions to return
362
min_prefix_length: int # Minimum query prefix length for completions
363
auto_learning: bool # Enable automatic learning from user queries
364
denylist_input_config: CompletionDataInputConfig # Blocked terms configuration
365
allowlist_input_config: CompletionDataInputConfig # Allowed terms configuration
366
last_denylist_import_operation: str # Last denylist import operation (read-only)
367
last_allowlist_import_operation: str # Last allowlist import operation (read-only)
368
last_suggestions_import_operation: str # Last suggestions import operation (read-only)
369
suggestions_input_config: CompletionDataInputConfig # Custom suggestions configuration
370
371
class CompletionDataInputConfig:
372
big_query_source: BigQuerySource # BigQuery data source
373
# Additional source types can be added here
374
```
375
376
### Request Types
377
378
Comprehensive request configurations for catalog management operations.
379
380
```python { .api }
381
class ListCatalogsRequest:
382
parent: str # Location resource name (required)
383
page_size: int # Maximum catalogs to return
384
page_token: str # Token for pagination
385
386
class UpdateCatalogRequest:
387
catalog: Catalog # Catalog with updates (required)
388
update_mask: FieldMask # Fields to update
389
390
class GetDefaultBranchRequest:
391
catalog: str # Catalog resource name (required)
392
393
class SetDefaultBranchRequest:
394
catalog: str # Catalog resource name (required)
395
branch_id: str # Branch ID to set as default
396
note: str # Optional note for the change
397
force: bool # Force change even if branch has no products
398
399
class GetAttributesConfigRequest:
400
name: str # Attributes config resource name (required)
401
402
class UpdateAttributesConfigRequest:
403
attributes_config: AttributesConfig # Config with updates (required)
404
update_mask: FieldMask # Fields to update
405
406
class AddCatalogAttributeRequest:
407
attributes_config: str # Attributes config resource name (required)
408
catalog_attribute: CatalogAttribute # Attribute to add (required)
409
410
class RemoveCatalogAttributeRequest:
411
attributes_config: str # Attributes config resource name (required)
412
key: str # Attribute key to remove (required)
413
414
class ReplaceCatalogAttributeRequest:
415
attributes_config: str # Attributes config resource name (required)
416
catalog_attribute: CatalogAttribute # New attribute configuration (required)
417
update_mask: FieldMask # Fields to update
418
419
class GetCompletionConfigRequest:
420
name: str # Completion config resource name (required)
421
422
class UpdateCompletionConfigRequest:
423
completion_config: CompletionConfig # Config with updates (required)
424
update_mask: FieldMask # Fields to update
425
```
426
427
## Usage Examples
428
429
### Catalog Management
430
431
```python
432
from google.cloud import retail
433
434
client = retail.CatalogServiceClient()
435
436
# List all catalogs in a location
437
request = retail.ListCatalogsRequest(
438
parent="projects/my-project/locations/global"
439
)
440
441
response = client.list_catalogs(request=request)
442
443
print("Available catalogs:")
444
for catalog in response.catalogs:
445
print(f"- {catalog.display_name}")
446
print(f" Name: {catalog.name}")
447
print(f" Product Level Config: {catalog.product_level_config}")
448
449
# Update catalog configuration
450
catalog_name = "projects/my-project/locations/global/catalogs/default_catalog"
451
updated_catalog = retail.Catalog(
452
name=catalog_name,
453
display_name="My Updated Catalog",
454
product_level_config=retail.ProductLevelConfig(
455
ingestion_product_type="PRIMARY"
456
)
457
)
458
459
request = retail.UpdateCatalogRequest(
460
catalog=updated_catalog,
461
update_mask=field_mask_pb2.FieldMask(paths=["display_name", "product_level_config"])
462
)
463
464
updated = client.update_catalog(request=request)
465
print(f"Updated catalog: {updated.display_name}")
466
```
467
468
### Branch Management
469
470
```python
471
# Get default branch
472
request = retail.GetDefaultBranchRequest(
473
catalog="projects/my-project/locations/global/catalogs/default_catalog"
474
)
475
476
response = client.get_default_branch(request=request)
477
print(f"Default branch: {response.branch}")
478
print(f"Set time: {response.set_time}")
479
print(f"Note: {response.note}")
480
481
# Set a new default branch
482
request = retail.SetDefaultBranchRequest(
483
catalog="projects/my-project/locations/global/catalogs/default_catalog",
484
branch_id="production_branch",
485
note="Switching to production branch for live traffic",
486
force=False
487
)
488
489
client.set_default_branch(request=request)
490
print("Default branch updated successfully")
491
```
492
493
### Attribute Configuration Management
494
495
```python
496
# Get current attributes configuration
497
request = retail.GetAttributesConfigRequest(
498
name="projects/my-project/locations/global/catalogs/default_catalog/attributesConfig"
499
)
500
501
attributes_config = client.get_attributes_config(request=request)
502
print(f"Current attribute config level: {attributes_config.attribute_config_level}")
503
print(f"Number of configured attributes: {len(attributes_config.catalog_attributes)}")
504
505
# Add a new catalog attribute for search and faceting
506
new_attribute = retail.CatalogAttribute(
507
key="brand",
508
type=retail.CatalogAttribute.AttributeType.TEXTUAL,
509
indexable_option=retail.CatalogAttribute.IndexableOption.INDEXABLE_ENABLED,
510
dynamic_facetable_option=retail.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_ENABLED,
511
searchable_option=retail.CatalogAttribute.SearchableOption.SEARCHABLE_ENABLED,
512
exact_searchable_option=retail.CatalogAttribute.ExactSearchableOption.EXACT_SEARCHABLE_ENABLED,
513
retrievable_option=retail.CatalogAttribute.RetrievableOption.RETRIEVABLE_ENABLED
514
)
515
516
request = retail.AddCatalogAttributeRequest(
517
attributes_config="projects/my-project/locations/global/catalogs/default_catalog/attributesConfig",
518
catalog_attribute=new_attribute
519
)
520
521
updated_config = client.add_catalog_attribute(request=request)
522
print(f"Added attribute 'brand'. Total attributes: {len(updated_config.catalog_attributes)}")
523
524
# Update an existing attribute
525
existing_attribute = updated_config.catalog_attributes["brand"]
526
existing_attribute.dynamic_facetable_option = retail.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_DISABLED
527
528
request = retail.ReplaceCatalogAttributeRequest(
529
attributes_config="projects/my-project/locations/global/catalogs/default_catalog/attributesConfig",
530
catalog_attribute=existing_attribute,
531
update_mask=field_mask_pb2.FieldMask(paths=["dynamic_facetable_option"])
532
)
533
534
updated_config = client.replace_catalog_attribute(request=request)
535
print("Updated brand attribute configuration")
536
```
537
538
### Completion Configuration
539
540
```python
541
# Get current completion configuration
542
request = retail.GetCompletionConfigRequest(
543
name="projects/my-project/locations/global/catalogs/default_catalog/completionConfig"
544
)
545
546
completion_config = client.get_completion_config(request=request)
547
print(f"Current completion config:")
548
print(f"- Max suggestions: {completion_config.max_suggestions}")
549
print(f"- Min prefix length: {completion_config.min_prefix_length}")
550
print(f"- Auto learning: {completion_config.auto_learning}")
551
552
# Update completion configuration
553
updated_config = retail.CompletionConfig(
554
name=completion_config.name,
555
max_suggestions=15,
556
min_prefix_length=2,
557
auto_learning=True,
558
matching_order="order-by-score-desc"
559
)
560
561
request = retail.UpdateCompletionConfigRequest(
562
completion_config=updated_config,
563
update_mask=field_mask_pb2.FieldMask(paths=[
564
"max_suggestions",
565
"min_prefix_length",
566
"auto_learning",
567
"matching_order"
568
])
569
)
570
571
updated = client.update_completion_config(request=request)
572
print("Completion configuration updated:")
573
print(f"- Max suggestions: {updated.max_suggestions}")
574
print(f"- Min prefix length: {updated.min_prefix_length}")
575
print(f"- Auto learning: {updated.auto_learning}")
576
```
577
578
### Advanced Attribute Configuration
579
580
```python
581
# Configure multiple attributes for a comprehensive product catalog
582
attributes_to_add = [
583
retail.CatalogAttribute(
584
key="color",
585
type=retail.CatalogAttribute.AttributeType.TEXTUAL,
586
indexable_option=retail.CatalogAttribute.IndexableOption.INDEXABLE_ENABLED,
587
dynamic_facetable_option=retail.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_ENABLED,
588
searchable_option=retail.CatalogAttribute.SearchableOption.SEARCHABLE_ENABLED,
589
retrievable_option=retail.CatalogAttribute.RetrievableOption.RETRIEVABLE_ENABLED
590
),
591
retail.CatalogAttribute(
592
key="price_range",
593
type=retail.CatalogAttribute.AttributeType.NUMERICAL,
594
indexable_option=retail.CatalogAttribute.IndexableOption.INDEXABLE_ENABLED,
595
dynamic_facetable_option=retail.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_ENABLED,
596
searchable_option=retail.CatalogAttribute.SearchableOption.SEARCHABLE_DISABLED,
597
retrievable_option=retail.CatalogAttribute.RetrievableOption.RETRIEVABLE_ENABLED
598
),
599
retail.CatalogAttribute(
600
key="customer_rating",
601
type=retail.CatalogAttribute.AttributeType.NUMERICAL,
602
indexable_option=retail.CatalogAttribute.IndexableOption.INDEXABLE_ENABLED,
603
dynamic_facetable_option=retail.CatalogAttribute.DynamicFacetableOption.DYNAMIC_FACETABLE_ENABLED,
604
searchable_option=retail.CatalogAttribute.SearchableOption.SEARCHABLE_DISABLED,
605
retrievable_option=retail.CatalogAttribute.RetrievableOption.RETRIEVABLE_ENABLED
606
)
607
]
608
609
attributes_config_name = "projects/my-project/locations/global/catalogs/default_catalog/attributesConfig"
610
611
# Add each attribute
612
for attribute in attributes_to_add:
613
request = retail.AddCatalogAttributeRequest(
614
attributes_config=attributes_config_name,
615
catalog_attribute=attribute
616
)
617
618
try:
619
updated_config = client.add_catalog_attribute(request=request)
620
print(f"Added attribute: {attribute.key}")
621
except Exception as e:
622
print(f"Failed to add attribute {attribute.key}: {e}")
623
624
# Get final configuration
625
final_config = client.get_attributes_config(
626
request=retail.GetAttributesConfigRequest(name=attributes_config_name)
627
)
628
629
print(f"\nFinal attribute configuration:")
630
for key, attr in final_config.catalog_attributes.items():
631
print(f"- {key}: {attr.type}, indexable={attr.indexable_option}, facetable={attr.dynamic_facetable_option}")
632
```
633
634
### Completion Data Management
635
636
```python
637
# Configure custom completion suggestions from BigQuery
638
completion_data_config = retail.CompletionDataInputConfig(
639
big_query_source=retail.BigQuerySource(
640
project_id="my-project",
641
dataset_id="retail_data",
642
table_id="completion_suggestions",
643
data_schema="suggestion"
644
)
645
)
646
647
updated_config = retail.CompletionConfig(
648
name="projects/my-project/locations/global/catalogs/default_catalog/completionConfig",
649
suggestions_input_config=completion_data_config,
650
max_suggestions=20,
651
min_prefix_length=1,
652
auto_learning=True
653
)
654
655
request = retail.UpdateCompletionConfigRequest(
656
completion_config=updated_config,
657
update_mask=field_mask_pb2.FieldMask(paths=[
658
"suggestions_input_config",
659
"max_suggestions",
660
"min_prefix_length"
661
])
662
)
663
664
updated = client.update_completion_config(request=request)
665
print("Updated completion config with custom suggestions from BigQuery")
666
print(f"Suggestions import operation: {updated.last_suggestions_import_operation}")
667
```