0
# Search and Discovery
1

2
Search functionality with advanced filtering, faceting, ranking, and query auto-completion capabilities. The Search Service provides intelligent product discovery with personalization, spell correction, and comprehensive result customization.
3

4
## Capabilities
5

6
### Product Search
7

8
Core search functionality for finding products based on user queries with advanced filtering and ranking.
9

10
```python { .api }
11
class SearchServiceClient:
12
    def search(self, request: SearchRequest) -> SearchResponse:
13
        """
14
        Performs product search with comprehensive filtering and ranking options.
15
        
16
        Args:
17
            request: Search parameters including query, filters, facets, and personalization
18
            
19
        Returns:
20
            SearchResponse: Search results with products, facets, corrected query, and metadata
21
            
22
        Raises:
23
            InvalidArgument: If search parameters are invalid
24
            PermissionDenied: If placement is not accessible
25
        """
26
```
27

28
### Query Auto-completion
29

30
Intelligent query suggestions and auto-completion to enhance search experience.
31

32
```python { .api }
33
class CompletionServiceClient:
34
    def complete_query(self, request: CompleteQueryRequest) -> CompleteQueryResponse:
35
        """
36
        Provides query auto-completion suggestions based on catalog data and user behavior.
37
        
38
        Args:
39
            request: Contains catalog path, query prefix, and completion parameters
40
            
41
        Returns:
42
            CompleteQueryResponse: Completion suggestions with attribution metadata
43
            
44
        Raises:
45
            InvalidArgument: If completion parameters are invalid
46
        """
47

48
class SearchServiceAsyncClient:
49
    async def search(self, request: SearchRequest) -> SearchResponse:
50
        """Async version of search."""
51

52
class CompletionServiceAsyncClient:
53
    async def complete_query(self, request: CompleteQueryRequest) -> CompleteQueryResponse:
54
        """Async version of complete_query."""
55
```
56

57
## Data Types
58

59
### Search Request
60

61
Comprehensive search request with query, filtering, faceting, and personalization options.
62

63
```python { .api }
64
class SearchRequest:
65
    placement: str  # Placement resource name (required)
66
    branch: str  # Catalog branch to search
67
    query: str  # Search query text
68
    visitor_id: str  # Unique visitor identifier for personalization
69
    user_info: UserInfo  # User context information
70
    page_size: int  # Maximum results per page (default: 100, max: 1000)
71
    page_token: str  # Token for pagination
72
    offset: int  # Number of results to skip
73
    filter: str  # Filter expression for products
74
    canonical_filter: str  # Canonical filter for consistent results
75
    order_by: str  # Sort order specification
76
    facet_specs: List[FacetSpec]  # Faceting configuration
77
    dynamic_facet_spec: SearchRequestDynamicFacetSpec  # Dynamic facet generation
78
    boost_spec: SearchRequestBoostSpec  # Result boosting configuration
79
    query_expansion_spec: SearchRequestQueryExpansionSpec  # Query expansion settings
80
    variant_rollup_keys: List[str]  # Keys for variant product rollup
81
    page_categories: List[str]  # Page context categories
82
    search_mode: SearchMode  # PRODUCT_SEARCH_ONLY or FACETED_SEARCH_ONLY
83
    personalization_spec: SearchRequestPersonalizationSpec  # Personalization settings
84
    labels: Dict[str, str]  # Custom labels for analytics
85
    spell_correction_spec: SearchRequestSpellCorrectionSpec  # Spell correction settings
86
```
87

88
### Search Response
89

90
Comprehensive search results with products, facets, analytics, and metadata.
91

92
```python { .api }
93
class SearchResponse:
94
    results: List[SearchResponseSearchResult]  # Search results with products
95
    facets: List[SearchResponseFacet]  # Facet results for filtering
96
    total_size: int  # Total number of matching products
97
    corrected_query: str  # Spell-corrected version of query
98
    attribution_token: str  # Token for result attribution
99
    next_page_token: str  # Token for next page of results
100
    query_expansion_info: SearchResponseQueryExpansionInfo  # Query expansion details
101
    redirect_uri: str  # Redirect URL if applicable
102
    applied_controls: List[str]  # Applied business rules/controls
103
    invalid_condition_boost_specs: List[SearchRequestBoostSpecConditionBoostSpec]  # Invalid boost conditions
104
    experiment_info: List[ExperimentInfo]  # A/B test experiment information
105
    personalization_info: SearchResponsePersonalizationInfo  # Personalization details
106
```
107

108
### Search Result
109

110
Individual search result containing product information and metadata.
111

112
```python { .api }
113
class SearchResponseSearchResult:
114
    id: str  # Product ID
115
    product: Product  # Full product information
116
    matching_variant_count: int  # Number of matching variants
117
    matching_variant_fields: Dict[str, FieldMask]  # Matching variant field details
118
    variant_rollup_values: Dict[str, Value]  # Rolled-up variant values
119
    personal_labels: List[str]  # Personalized labels for this result
120
```
121

122
### Faceting
123

124
Configuration and results for search faceting functionality.
125

126
```python { .api }
127
class FacetSpec:
128
    facet_key: FacetKeySpec  # Facet key configuration
129
    limit: int  # Maximum facet values to return
130
    excluded_filter_keys: List[str]  # Filter keys to exclude from facet counts
131
    enable_dynamic_position: bool  # Enable dynamic facet positioning
132
    
133
class FacetKeySpec:
134
    key: str  # Facet key (attribute name or predefined key)
135
    intervals: List[Interval]  # Numeric intervals for numeric facets
136
    restricted_values: List[str]  # Restrict facet to specific values
137
    prefixes: List[str]  # Prefix matching for text facets
138
    contains: List[str]  # Substring matching for text facets
139
    case_insensitive: bool  # Case-insensitive matching
140
    order_by: str  # Facet value ordering
141
    query: str  # Query for facet value filtering
142
    return_min_max: bool  # Return min/max values for numeric facets
143

144
class SearchResponseFacet:
145
    key: str  # Facet key
146
    values: List[SearchResponseFacetFacetValue]  # Facet values and counts
147
    dynamic_facet: bool  # Whether this is a dynamically generated facet
148

149
class SearchResponseFacetFacetValue:
150
    value: str  # Facet value
151
    count: int  # Number of products with this facet value
152
    interval: Interval  # Interval for numeric facets
153
    min_value: float  # Minimum value for numeric facets
154
    max_value: float  # Maximum value for numeric facets
155
```
156

157
### Completion Request and Response
158

159
Query auto-completion configuration and results.
160

161
```python { .api }
162
class CompleteQueryRequest:
163
    catalog: str  # Catalog resource name (required)
164
    query: str  # Query prefix for completion (required)
165
    visitor_id: str  # Unique visitor identifier
166
    language_codes: List[str]  # Preferred completion languages
167
    device_type: str  # Device type (DESKTOP, MOBILE, TABLET)
168
    dataset: str  # Dataset for completion suggestions
169
    max_suggestions: int  # Maximum suggestions to return (default: 20)
170

171
class CompleteQueryResponse:
172
    completion_results: List[CompleteQueryResponseCompletionResult]  # Completion suggestions
173
    attribution_token: str  # Token for attribution
174
    recent_search_results: List[CompleteQueryResponseRecentSearchResult]  # Recent searches
175

176
class CompleteQueryResponseCompletionResult:
177
    suggestion: str  # Completion suggestion text
178
    attributes: Dict[str, CustomAttribute]  # Additional attributes
179

180
class CompleteQueryResponseRecentSearchResult:
181
    recent_search: str  # Recent search query
182
```
183

184
### Personalization and User Context
185

186
User information and personalization settings for search customization.
187

188
```python { .api }
189
class UserInfo:
190
    user_id: str  # Persistent user identifier
191
    ip_address: str  # User IP address for geo-targeting
192
    user_agent: str  # User agent string
193
    direct_user_request: bool  # Whether request is directly from user
194

195
class SearchRequestPersonalizationSpec:
196
    mode: PersonalizationSpecMode  # AUTO, DISABLED
197
    
198
class SearchResponsePersonalizationInfo:
199
    personalization_mode: PersonalizationSpecMode  # Applied personalization mode
200
    user_id: str  # User ID used for personalization
201
```
202

203
### Boosting and Ranking
204

205
Configuration for result boosting and custom ranking.
206

207
```python { .api }
208
class SearchRequestBoostSpec:
209
    condition_boost_specs: List[SearchRequestBoostSpecConditionBoostSpec]  # Conditional boosting
210
    skip_boost_spec_validation: bool  # Skip boost validation
211

212
class SearchRequestBoostSpecConditionBoostSpec:
213
    condition: str  # Boost condition expression
214
    boost: float  # Boost multiplier
215
```
216

217
### Query Processing
218

219
Query expansion and spell correction configuration.
220

221
```python { .api }
222
class SearchRequestQueryExpansionSpec:
223
    condition: QueryExpansionSpecCondition  # AUTO, DISABLED
224
    pin_unexpanded_results: bool  # Pin original results
225

226
class SearchRequestSpellCorrectionSpec:
227
    mode: SpellCorrectionSpecMode  # AUTO, DISABLED
228

229
class SearchResponseQueryExpansionInfo:
230
    expanded_query: bool  # Whether query was expanded
231
    pinned_result_count: int  # Number of pinned unexpanded results
232
```
233

234
## Usage Examples
235

236
### Basic Product Search
237

238
```python
239
from google.cloud import retail
240

241
client = retail.SearchServiceClient()
242

243
# Basic search with query
244
request = retail.SearchRequest(
245
    placement="projects/my-project/locations/global/catalogs/default_catalog/placements/search",
246
    query="gaming laptop",
247
    page_size=20,
248
    visitor_id="visitor-123"
249
)
250

251
response = client.search(request=request)
252

253
print(f"Found {response.total_size} products")
254
for result in response.results:
255
    product = result.product
256
    print(f"- {product.title} (${product.price_info.price})")
257
```
258

259
### Advanced Search with Filtering and Faceting
260

261
```python
262
# Advanced search with filters, facets, and personalization
263
request = retail.SearchRequest(
264
    placement="projects/my-project/locations/global/catalogs/default_catalog/placements/search",
265
    query="laptop",
266
    filter='(categories: ANY("Electronics", "Computers")) AND (price_info.price: [200, 2000])',
267
    facet_specs=[
268
        retail.SearchRequest.FacetSpec(
269
            facet_key=retail.SearchRequest.FacetSpec.FacetKey(
270
                key="brands"
271
            ),
272
            limit=10
273
        ),
274
        retail.SearchRequest.FacetSpec(
275
            facet_key=retail.SearchRequest.FacetSpec.FacetKey(
276
                key="price_info.price",
277
                intervals=[
278
                    retail.Interval(minimum=0, maximum=500),
279
                    retail.Interval(minimum=500, maximum=1000),
280
                    retail.Interval(minimum=1000, maximum=2000),
281
                    retail.Interval(minimum=2000)
282
                ]
283
            )
284
        ),
285
        retail.SearchRequest.FacetSpec(
286
            facet_key=retail.SearchRequest.FacetSpec.FacetKey(
287
                key="attributes.screen_size"
288
            ),
289
            limit=5
290
        )
291
    ],
292
    order_by="price_info.price desc",
293
    visitor_id="visitor-123",
294
    user_info=retail.UserInfo(
295
        user_id="user-456",
296
        ip_address="192.168.1.100"
297
    )
298
)
299

300
response = client.search(request=request)
301

302
print(f"Search Results: {len(response.results)} of {response.total_size}")
303
print(f"Corrected query: {response.corrected_query}")
304

305
# Display products
306
for result in response.results:
307
    product = result.product
308
    print(f"- {product.title}")
309
    print(f"  Price: ${product.price_info.price}")
310
    print(f"  Brand: {', '.join(product.brands)}")
311
    print(f"  Categories: {', '.join(product.categories)}")
312

313
# Display facets
314
print("\nFacets:")
315
for facet in response.facets:
316
    print(f"\n{facet.key}:")
317
    for value in facet.values[:5]:  # Show top 5 values
318
        print(f"  {value.value} ({value.count})")
319
```
320

321
### Search with Boosting
322

323
```python
324
# Search with conditional boosting for promoted products
325
boost_spec = retail.SearchRequest.BoostSpec(
326
    condition_boost_specs=[
327
        retail.SearchRequest.BoostSpec.ConditionBoostSpec(
328
            condition='(tags: ANY("promoted"))',
329
            boost=2.0  # Double the relevance score
330
        ),
331
        retail.SearchRequest.BoostSpec.ConditionBoostSpec(
332
            condition='(brands: ANY("TechBrand"))',
333
            boost=1.5  # 1.5x boost for preferred brand
334
        )
335
    ]
336
)
337

338
request = retail.SearchRequest(
339
    placement="projects/my-project/locations/global/catalogs/default_catalog/placements/search",
340
    query="laptop",
341
    boost_spec=boost_spec,
342
    visitor_id="visitor-123"
343
)
344

345
response = client.search(request=request)
346
```
347

348
### Query Auto-completion
349

350
```python
351
completion_client = retail.CompletionServiceClient()
352

353
# Get query suggestions
354
request = retail.CompleteQueryRequest(
355
    catalog="projects/my-project/locations/global/catalogs/default_catalog",
356
    query="gam",  # User has typed "gam"
357
    max_suggestions=10,
358
    visitor_id="visitor-123"
359
)
360

361
response = completion_client.complete_query(request=request)
362

363
print("Completion suggestions:")
364
for result in response.completion_results:
365
    print(f"- {result.suggestion}")
366

367
print("\nRecent searches:")
368
for recent in response.recent_search_results:
369
    print(f"- {recent.recent_search}")
370
```
371

372
### Personalized Search
373

374
```python
375
# Search with enhanced personalization
376
personalization_spec = retail.SearchRequest.PersonalizationSpec(
377
    mode=retail.SearchRequest.PersonalizationSpec.Mode.AUTO
378
)
379

380
request = retail.SearchRequest(
381
    placement="projects/my-project/locations/global/catalogs/default_catalog/placements/search",
382
    query="laptop",
383
    visitor_id="visitor-123",
384
    user_info=retail.UserInfo(
385
        user_id="user-456",
386
        ip_address="192.168.1.100",
387
        user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
388
    ),
389
    personalization_spec=personalization_spec
390
)
391

392
response = client.search(request=request)
393

394
# Check personalization details
395
if response.personalization_info:
396
    print(f"Personalization mode: {response.personalization_info.personalization_mode}")
397
    print(f"User ID: {response.personalization_info.user_id}")
398
```