Index
CompletionService(interface)ConversationalSearchService(interface)DocumentService(interface)RecommendationService(interface)SchemaService(interface)SearchService(interface)UserEventService(interface)BigQuerySource(message)CollectUserEventRequest(message)CompleteQueryRequest(message)CompleteQueryResponse(message)CompleteQueryResponse.QuerySuggestion(message)CompletionInfo(message)Conversation(message)Conversation.State(enum)ConversationContext(message)ConversationMessage(message)ConverseConversationRequest(message)ConverseConversationResponse(message)CreateConversationRequest(message)CreateDocumentRequest(message)CreateSchemaMetadata(message)CreateSchemaRequest(message)CustomAttribute(message)DeleteConversationRequest(message)DeleteDocumentRequest(message)DeleteSchemaMetadata(message)DeleteSchemaRequest(message)Document(message)Document.Content(message)DocumentInfo(message)DoubleList(message)GcsSource(message)GetConversationRequest(message)GetDocumentRequest(message)GetSchemaRequest(message)ImportDocumentsMetadata(message)ImportDocumentsRequest(message)ImportDocumentsRequest.InlineSource(message)ImportDocumentsRequest.ReconciliationMode(enum)ImportDocumentsResponse(message)ImportErrorConfig(message)ImportUserEventsMetadata(message)ImportUserEventsRequest(message)ImportUserEventsRequest.InlineSource(message)ImportUserEventsResponse(message)Interval(message)ListConversationsRequest(message)ListConversationsResponse(message)ListDocumentsRequest(message)ListDocumentsResponse(message)ListSchemasRequest(message)ListSchemasResponse(message)MediaInfo(message)PageInfo(message)PanelInfo(message)PurgeDocumentsMetadata(message)PurgeDocumentsRequest(message)PurgeDocumentsResponse(message)RecommendRequest(message)RecommendResponse(message)RecommendResponse.RecommendationResult(message)Reply(message)Reply.Reference(message) (deprecated)Schema(message)SearchInfo(message)SearchRequest(message)SearchRequest.BoostSpec(message)SearchRequest.BoostSpec.ConditionBoostSpec(message)SearchRequest.ContentSearchSpec(message)SearchRequest.ContentSearchSpec.ExtractiveContentSpec(message)SearchRequest.ContentSearchSpec.SnippetSpec(message)SearchRequest.ContentSearchSpec.SummarySpec(message)SearchRequest.EmbeddingSpec(message)SearchRequest.EmbeddingSpec.EmbeddingVector(message)SearchRequest.FacetSpec(message)SearchRequest.FacetSpec.FacetKey(message)SearchRequest.ImageQuery(message)SearchRequest.QueryExpansionSpec(message)SearchRequest.QueryExpansionSpec.Condition(enum)SearchRequest.SpellCorrectionSpec(message)SearchRequest.SpellCorrectionSpec.Mode(enum)SearchResponse(message)SearchResponse.Facet(message)SearchResponse.Facet.FacetValue(message)SearchResponse.GuidedSearchResult(message)SearchResponse.GuidedSearchResult.RefinementAttribute(message)SearchResponse.QueryExpansionInfo(message)SearchResponse.SearchResult(message)SearchResponse.Summary(message)SearchResponse.Summary.SafetyAttributes(message)SearchResponse.Summary.SummarySkippedReason(enum)TextInput(message)TransactionInfo(message)UpdateConversationRequest(message)UpdateDocumentRequest(message)UpdateSchemaMetadata(message)UpdateSchemaRequest(message)UserEvent(message)UserInfo(message)WriteUserEventRequest(message)
CompletionService
Service for Auto-Completion.
| CompleteQuery |
|---|
|
Completes the specified user input with keyword suggestions.
|
ConversationalSearchService
Service for conversational search.
| ConverseConversation |
|---|
|
Converses a conversation.
|
| CreateConversation |
|---|
|
Creates a Conversation. If the
|
| DeleteConversation |
|---|
|
Deletes a Conversation. If the
|
| GetConversation |
|---|
|
Gets a Conversation.
|
| ListConversations |
|---|
|
Lists all Conversations by their parent
|
| UpdateConversation |
|---|
|
Updates a Conversation.
|
DocumentService
Service for ingesting Document information of the customer's website.
| CreateDocument |
|---|
|
Creates a
|
| DeleteDocument |
|---|
|
Deletes a
|
| GetDocument |
|---|
|
Gets a
|
| ImportDocuments |
|---|
|
Bulk import of multiple Note: It is possible for a subset of the
|
| ListDocuments |
|---|
|
Gets a list of
|
| PurgeDocuments |
|---|
|
Permanently deletes all selected This process is asynchronous. Depending on the number of To get a list of the
|
| UpdateDocument |
|---|
|
Updates a
|
RecommendationService
Service for making recommendations.
| Recommend |
|---|
|
Makes a recommendation, which requires a contextual user event.
|
SchemaService
Service for managing Schemas.
| CreateSchema |
|---|
|
Creates a
|
| DeleteSchema |
|---|
|
Deletes a
|
| GetSchema |
|---|
|
Gets a
|
| ListSchemas |
|---|
|
Gets a list of
|
| UpdateSchema |
|---|
|
Updates a
|
SearchService
Service for search.
| Search |
|---|
|
Performs a search.
|
UserEventService
Service for ingesting end user actions on a website to Discovery Engine API.
| CollectUserEvent |
|---|
|
Writes a single user event from the browser. This uses a GET request to due to browser restriction of POST-ing to a third-party domain. This method is used only by the Discovery Engine API JavaScript pixel and Google Tag Manager. Users should not call this method directly.
|
| ImportUserEvents |
|---|
|
Bulk import of User events. Request processing might be synchronous. Events that already exist are skipped. Use this method for backfilling historical user events. Operation.response is of type ImportResponse. Note that it is possible for a subset of the items to be successfully inserted. Operation.metadata is of type ImportMetadata.
|
| WriteUserEvent |
|---|
|
Writes a single user event.
|
BigQuerySource
BigQuery source import data from.
| Fields | |
|---|---|
project_id |
The project ID (can be project # or ID) that the BigQuery source is in with a length limit of 128 characters. If not specified, inherits the project ID from the parent request. |
dataset_id |
Required. The BigQuery data set to copy the data from with a length limit of 1,024 characters. |
table_id |
Required. The BigQuery table to copy the data from with a length limit of 1,024 characters. |
gcs_staging_dir |
Intermediate Cloud Storage directory used for the import with a length limit of 2,000 characters. Can be specified if one wants to have the BigQuery export to a specific Cloud Storage directory. |
data_schema |
The schema to use when parsing the data from the source. Supported values for user event imports:
Supported values for document imports:
|
Union field partition. BigQuery table partition info. Leave this empty if the BigQuery table is not partitioned. partition can be only one of the following: |
|
partition_date |
BigQuery time partitioned table's _PARTITIONDATE in YYYY-MM-DD format. |
CollectUserEventRequest
Request message for CollectUserEvent method.
| Fields | |
|---|---|
parent |
Required. The parent DataStore resource name, such as |
user_event |
Required. URL encoded UserEvent proto with a length limit of 2,000,000 characters. |
uri |
The URL including cgi-parameters but excluding the hash fragment with a length limit of 5,000 characters. This is often more useful than the referer URL, because many browsers only send the domain for third-party requests. |
ets |
The event timestamp in milliseconds. This prevents browser caching of otherwise identical get requests. The name is abbreviated to reduce the payload bytes. |
CompleteQueryRequest
Request message for CompletionService.CompleteQuery method.
| Fields | |
|---|---|
data_store |
Required. The parent data store resource name for which the completion is performed, such as |
query |
Required. The typeahead input used to fetch suggestions. Maximum length is 128 characters. |
query_model |
Selects data model of query suggestions for serving. Currently supported values:
Default values:
|
user_pseudo_id |
A unique identifier for tracking visitors. For example, this could be implemented with an HTTP cookie, which should be able to uniquely identify a visitor on a single device. This unique identifier should not change if the visitor logs in or out of the website. This field should NOT have a fixed value such as This should be the same identifier as The field must be a UTF-8 encoded string with a length limit of 128 characters. Otherwise, an |
include_tail_suggestions |
Indicates if tail suggestions should be returned if there are no suggestions that match the full query. Even if set to true, if there are suggestions that match the full query, those are returned and no tail suggestions are returned. |
CompleteQueryResponse
Response message for CompletionService.CompleteQuery method.
| Fields | |
|---|---|
query_suggestions[] |
Results of the matched query suggestions. The result list is ordered and the first result is a top suggestion. |
tail_match_triggered |
True if the returned suggestions are all tail suggestions. For tail matching to be triggered, include_tail_suggestions in the request must be true and there must be no suggestions that match the full query. |
QuerySuggestion
Suggestions as search queries.
| Fields | |
|---|---|
suggestion |
The suggestion for the query. |
completable_field_paths[] |
The unique document field paths that serve as the source of this suggestion if it was generated from completable fields. This field is only populated for the document-completable model. |
CompletionInfo
Detailed completion information including completion attribution token and clicked completion info.
| Fields | |
|---|---|
selected_suggestion |
End user selected |
selected_position |
End user selected |
Conversation
External conversation proto definition.
| Fields | |
|---|---|
name |
Immutable. Fully qualified name |
state |
The state of the Conversation. |
user_pseudo_id |
A unique identifier for tracking users. |
messages[] |
Conversation messages. |
start_time |
Output only. The time the conversation started. |
end_time |
Output only. The time the conversation finished. |
State
Enumeration of the state of the conversation.
| Enums | |
|---|---|
STATE_UNSPECIFIED |
Unknown. |
IN_PROGRESS |
Conversation is currently open. |
COMPLETED |
Conversation has been completed. |
ConversationContext
Defines context of the conversation
| Fields | |
|---|---|
context_documents[] |
The current list of documents the user is seeing. It contains the document resource references. |
active_document |
The current active document the user opened. It contains the document resource reference. |
ConversationMessage
Defines a conversation message.
| Fields | |
|---|---|
create_time |
Output only. Message creation timestamp. |
Union field
|
|
user_input |
User text input. |
reply |
Search reply. |
ConverseConversationRequest
Request message for ConversationalSearchService.ConverseConversation method.
| Fields | |
|---|---|
name |
Required. The resource name of the Conversation to get. Format: |
query |
Required. Current user input. |
serving_config |
The resource name of the Serving Config to use. Format: |
conversation |
The conversation to be used by auto session only. The name field will be ignored as we automatically assign new name for the conversation in auto session. |
safe_search |
Whether to turn on safe search. |
user_labels |
The user labels applied to a resource must meet the following requirements:
See Google Cloud Document for more details. |
summary_spec |
A specification for configuring the summary returned in the response. |
ConverseConversationResponse
Response message for ConversationalSearchService.ConverseConversation method.
| Fields | |
|---|---|
reply |
Answer to the current query. |
conversation |
Updated conversation including the answer. |
related_questions[] |
Suggested related questions. |
search_results[] |
Search Results. |
CreateConversationRequest
Request for CreateConversation method.
| Fields | |
|---|---|
parent |
Required. Full resource name of parent data store. Format: |
conversation |
Required. The conversation to create. |
CreateDocumentRequest
Request message for DocumentService.CreateDocument method.
| Fields | |
|---|---|
parent |
Required. The parent resource name, such as |
document |
Required. The |
document_id |
Required. The ID to use for the If the caller does not have permission to create the This field must be unique among all This field must conform to RFC-1034 standard with a length limit of 63 characters. Otherwise, an |
CreateSchemaMetadata
Metadata for Create Schema LRO.
| Fields | |
|---|---|
create_time |
Operation create time. |
update_time |
Operation last update time. If the operation is done, this is also the finish time. |
CreateSchemaRequest
Request message for SchemaService.CreateSchema method.
| Fields | |
|---|---|
parent |
Required. The parent data store resource name, in the format of |
schema |
Required. The |
schema_id |
Required. The ID to use for the This field should conform to RFC-1034 standard with a length limit of 63 characters. |
CustomAttribute
A custom attribute that is not explicitly modeled in a resource, e.g. UserEvent.
| Fields | |
|---|---|
text[] |
The textual values of this custom attribute. For example, Empty string is not allowed. Otherwise, an Exactly one of |
numbers[] |
The numerical values of this custom attribute. For example, Exactly one of |
DeleteConversationRequest
Request for DeleteConversation method.
| Fields | |
|---|---|
name |
Required. The resource name of the Conversation to delete. Format: |
DeleteDocumentRequest
Request message for DocumentService.DeleteDocument method.
| Fields | |
|---|---|
name |
Required. Full resource name of If the caller does not have permission to delete the If the |
DeleteSchemaMetadata
Metadata for DeleteSchema LRO.
| Fields | |
|---|---|
create_time |
Operation create time. |
update_time |
Operation last update time. If the operation is done, this is also the finish time. |
DeleteSchemaRequest
Request message for SchemaService.DeleteSchema method.
| Fields | |
|---|---|
name |
Required. The full resource name of the schema, in the format of |
Document
Document captures all raw metadata information of items to be recommended or searched.
| Fields | |
|---|---|
name |
Immutable. The full resource name of the document. Format: This field must be a UTF-8 encoded string with a length limit of 1024 characters. |
id |
Immutable. The identifier of the document. Id should conform to RFC-1034 standard with a length limit of 63 characters. |
schema_id |
The identifier of the schema located in the same data store. |
content |
The unstructured data linked to this document. Content must be set if this document is under a |
parent_document_id |
The identifier of the parent document. Currently supports at most two level document hierarchy. Id should conform to RFC-1034 standard with a length limit of 63 characters. |
derived_struct_data |
Output only. This field is OUTPUT_ONLY. It contains derived data that are not in the original input document. |
Union field data. Data representation. One of struct_data or json_data should be provided otherwise an INVALID_ARGUMENT error is thrown. data can be only one of the following: |
|
struct_data |
The structured JSON data for the document. It should conform to the registered |
json_data |
The JSON string representation of the document. It should conform to the registered |
Content
Unstructured data linked to this document.
| Fields | |
|---|---|
mime_type |
The MIME type of the content. Supported types:
See https://www.iana.org/assignments/media-types/media-types.xhtml. |
Union field
|
|
raw_bytes |
The content represented as a stream of bytes. The maximum length is 1,000,000 bytes (1 MB / ~0.95 MiB). Note: As with all |
uri |
The URI of the content. Only Cloud Storage URIs (e.g. |
DocumentInfo
Detailed document information associated with a user event.
| Fields | |
|---|---|
promotion_ids[] |
The promotion IDs associated with this Document. Currently, this field is restricted to at most one ID. |
Union field
|
|
id |
The |
name |
The |
uri |
The |
quantity |
Quantity of the Document associated with the user event. Defaults to 1. For example, this field will be 2 if two quantities of the same Document are involved in a Required for events of the following event types:
|
DoubleList
Double list.
| Fields | |
|---|---|
values[] |
Double values. |
GcsSource
Cloud Storage location for input content.
| Fields | |
|---|---|
input_uris[] |
Required. Cloud Storage URIs to input files. URI can be up to 2000 characters long. URIs can match the full object path (for example, A request can contain at most 100 files (or 100,000 files if |
data_schema |
The schema to use when parsing the data from the source. Supported values for document imports:
Supported values for user even imports:
|
GetConversationRequest
Request for GetConversation method.
| Fields | |
|---|---|
name |
Required. The resource name of the Conversation to get. Format: |
GetDocumentRequest
Request message for DocumentService.GetDocument method.
| Fields | |
|---|---|
name |
Required. Full resource name of If the caller does not have permission to access the If the requested |
GetSchemaRequest
Request message for SchemaService.GetSchema method.
| Fields | |
|---|---|
name |
Required. The full resource name of the schema, in the format of |
ImportDocumentsMetadata
Metadata related to the progress of the ImportDocuments operation. This is returned by the google.longrunning.Operation.metadata field.
| Fields | |
|---|---|
create_time |
Operation create time. |
update_time |
Operation last update time. If the operation is done, this is also the finish time. |
success_count |
Count of entries that were processed successfully. |
failure_count |
Count of entries that encountered errors while processing. |
ImportDocumentsRequest
Request message for Import methods.
| Fields | |
|---|---|
parent |
Required. The parent branch resource name, such as |
error_config |
The desired location of errors incurred during the Import. |
reconciliation_mode |
The mode of reconciliation between existing documents and the documents to be imported. Defaults to |
auto_generate_ids |
Whether to automatically generate IDs for the documents if absent. If set to Only set this field when using |
id_field |
The field in the Cloud Storage and BigQuery sources that indicates the unique IDs of the documents. For The values of the JSON field or the BigQuery column are used as the Only set this field when using If it is unset, a default value |
Union field source. Required. The source of the input. source can be only one of the following: |
|
inline_source |
The Inline source for the input content for documents. |
gcs_source |
Cloud Storage location for the input content. |
bigquery_source |
BigQuery input source. |
InlineSource
The inline source for the input config for ImportDocuments method.
| Fields | |
|---|---|
documents[] |
Required. A list of documents to update/create. Each document must have a valid |
ReconciliationMode
Indicates how imported documents are reconciled with the existing documents created or imported before.
| Enums | |
|---|---|
RECONCILIATION_MODE_UNSPECIFIED |
Defaults to INCREMENTAL. |
INCREMENTAL |
Inserts new documents or updates existing documents. |
FULL |
Calculates diff and replaces the entire document dataset. Existing documents may be deleted if they are not present in the source location. |
ImportDocumentsResponse
Response of the ImportDocumentsRequest. If the long running operation is done, then this message is returned by the google.longrunning.Operations.response field if the operation was successful.
| Fields | |
|---|---|
error_samples[] |
A sample of errors encountered while processing the request. |
error_config |
Echoes the destination for the complete errors in the request if set. |
ImportErrorConfig
Configuration of destination for Import related errors.
| Fields | |
|---|---|
Union field destination. Required. Errors destination. destination can be only one of the following: |
|
gcs_prefix |
Cloud Storage prefix for import errors. This must be an empty, existing Cloud Storage directory. Import errors are written to sharded files in this directory, one per line, as a JSON-encoded |
ImportUserEventsMetadata
Metadata related to the progress of the Import operation. This is returned by the google.longrunning.Operation.metadata field.
| Fields | |
|---|---|
create_time |
Operation create time. |
update_time |
Operation last update time. If the operation is done, this is also the finish time. |
success_count |
Count of entries that were processed successfully. |
failure_count |
Count of entries that encountered errors while processing. |
ImportUserEventsRequest
Request message for the ImportUserEvents request.
| Fields | |
|---|---|
parent |
Required. Parent DataStore resource name, of the form |
error_config |
The desired location of errors incurred during the Import. Cannot be set for inline user event imports. |
Union field source. Required - The desired input source of the user event data. source can be only one of the following: |
|
inline_source |
The Inline source for the input content for UserEvents. |
gcs_source |
Cloud Storage location for the input content. |
bigquery_source |
BigQuery input source. |
InlineSource
The inline source for the input config for ImportUserEvents method.
| Fields | |
|---|---|
user_events[] |
Required. A list of user events to import. Recommended max of 10k items. |
ImportUserEventsResponse
Response of the ImportUserEventsRequest. If the long running operation was successful, then this message is returned by the google.longrunning.Operations.response field if the operation was successful.
| Fields | |
|---|---|
error_samples[] |
A sample of errors encountered while processing the request. |
error_config |
Echoes the destination for the complete errors if this field was set in the request. |
joined_events_count |
Count of user events imported with complete existing Documents. |
unjoined_events_count |
Count of user events imported, but with Document information not found in the existing Branch. |
Interval
A floating point interval.
| Fields | |
|---|---|
Union field This field must be not larger than max. Otherwise, an |
|
minimum |
Inclusive lower bound. |
exclusive_minimum |
Exclusive lower bound. |
Union field This field must be not smaller than min. Otherwise, an |
|
maximum |
Inclusive upper bound. |
exclusive_maximum |
Exclusive upper bound. |
ListConversationsRequest
Request for ListConversations method.
| Fields | |
|---|---|
parent |
Required. The data store resource name. Format: |
page_size |
Maximum number of results to return. If unspecified, defaults to 50. Max allowed value is 1000. |
page_token |
A page token, received from a previous |
filter |
A filter to apply on the list results. The supported features are: user_pseudo_id, state. Example: "user_pseudo_id = some_id" |
order_by |
A comma-separated list of fields to order by, sorted in ascending order. Use "desc" after a field name for descending. Supported fields: * Example: "update_time desc" "create_time" |
ListConversationsResponse
Response for ListConversations method.
| Fields | |
|---|---|
conversations[] |
All the Conversations for a given data store. |
next_page_token |
Pagination token, if not returned indicates the last page. |
ListDocumentsRequest
Request message for DocumentService.ListDocuments method.
| Fields | |
|---|---|
parent |
Required. The parent branch resource name, such as If the caller does not have permission to list |
page_size |
Maximum number of If this field is negative, an |
page_token |
A page token When paginating, all other parameters provided to |
ListDocumentsResponse
Response message for DocumentService.ListDocuments method.
| Fields | |
|---|---|
documents[] |
The |
next_page_token |
A token that can be sent as |
ListSchemasRequest
Request message for SchemaService.ListSchemas method.
| Fields | |
|---|---|
parent |
Required. The parent data store resource name, in the format of |
page_size |
The maximum number of If unspecified, at most 100 The maximum value is 1000; values above 1000 will be coerced to 1000. |
page_token |
A page token, received from a previous When paginating, all other parameters provided to |
ListSchemasResponse
Response message for SchemaService.ListSchemas method.
| Fields | |
|---|---|
schemas[] |
The |
next_page_token |
A token that can be sent as |
MediaInfo
Media-specific user event information.
| Fields | |
|---|---|
media_progress_duration |
The media progress time in seconds, if applicable. For example, if the end user has finished 90 seconds of a playback video, then |
media_progress_percentage |
Media progress should be computed using only the This value must be between If this is not a playback or the progress cannot be computed (e.g. ongoing livestream), this field should be unset. |
PageInfo
Detailed page information.
| Fields | |
|---|---|
pageview_id |
A unique ID of a web page view. This should be kept the same for all user events triggered from the same pageview. For example, an item detail page view could trigger multiple events as the user is browsing the page. The When using the client side event reporting with JavaScript pixel and Google Tag Manager, this value is filled in automatically. |
page_category |
The most specific category associated with a category page. To represent full path of category, use '>' sign to separate different hierarchies. If '>' is part of the category name, please replace it with other character(s). Category pages include special pages such as sales or promotions. For instance, a special sale page may have the category hierarchy: Required for |
uri |
Complete URL (window.location.href) of the user's current page. When using the client side event reporting with JavaScript pixel and Google Tag Manager, this value is filled in automatically. Maximum length 5,000 characters. |
referrer_uri |
The referrer URL of the current page. When using the client side event reporting with JavaScript pixel and Google Tag Manager, this value is filled in automatically. However, some browser privacy restrictions may cause this field to be empty. |
PanelInfo
Detailed panel information associated with a user event.
| Fields | |
|---|---|
panel_id |
Required. The panel ID. |
display_name |
The display name of the panel. |
panel_position |
The ordered position of the panel, if shown to the user with other panels. If set, then |
total_panels |
The total number of panels, including this one, shown to the user. Must be set if |
PurgeDocumentsMetadata
Metadata related to the progress of the PurgeDocuments operation. This will be returned by the google.longrunning.Operation.metadata field.
| Fields | |
|---|---|
create_time |
Operation create time. |
update_time |
Operation last update time. If the operation is done, this is also the finish time. |
success_count |
Count of entries that were deleted successfully. |
failure_count |
Count of entries that encountered errors while processing. |
PurgeDocumentsRequest
Request message for DocumentService.PurgeDocuments method.
| Fields | |
|---|---|
parent |
Required. The parent resource name, such as |
filter |
Required. Filter matching documents to purge. Only currently supported value is |
force |
Actually performs the purge. If |
PurgeDocumentsResponse
Response message for DocumentService.PurgeDocuments method. If the long running operation is successfully done, then this message is returned by the google.longrunning.Operations.response field.
| Fields | |
|---|---|
purge_count |
The total count of documents purged as a result of the operation. |
purge_sample[] |
A sample of document names that will be deleted. Only populated if |
RecommendRequest
Request message for Recommend method.
| Fields | |
|---|---|
serving_config |
Required. Full resource name of the format: Before you can request recommendations from your model, you must create at least one serving config for it. |
user_event |
Required. Context about the user, what they are looking at and what action they took to trigger the Recommend request. Note that this user event detail won't be ingested to userEvent logs. Thus, a separate userEvent write request is required for event logging. Don't set |
page_size |
Maximum number of results to return. Set this property to the number of recommendation results needed. If zero, the service will choose a reasonable default. The maximum allowed value is 100. Values above 100 will be coerced to 100. |
filter |
Filter for restricting recommendation results with a length limit of 5,000 characters. Currently, only filter expressions on the Examples:
If your filter blocks all results, the API will return generic (unfiltered) popular Documents. If you only want results strictly matching the filters, set Note that the API will never return |
validate_only |
Use validate only mode for this recommendation query. If set to true, a fake model will be used that returns arbitrary Document IDs. Note that the validate only mode should only be used for testing the API, or if the model is not ready. |
params |
Additional domain specific parameters for the recommendations. Allowed values:
|
user_labels |
The user labels applied to a resource must meet the following requirements:
See Requirements for labels for more details. |
RecommendResponse
Response message for Recommend method.
| Fields | |
|---|---|
results[] |
A list of recommended Documents. The order represents the ranking (from the most relevant Document to the least). |
attribution_token |
A unique attribution token. This should be included in the |
missing_ids[] |
IDs of documents in the request that were missing from the default Branch associated with the requested ServingConfig. |
validate_only |
True if |
RecommendationResult
RecommendationResult represents a generic recommendation result with associated metadata.
| Fields | |
|---|---|
id |
Resource ID of the recommended Document. |
document |
Set if |
metadata |
Additional Document metadata / annotations. Possible values:
|
Reply
Defines a reply message to user.
| Fields | |
|---|---|
reply |
DEPRECATED: use |
references[] |
References in the reply. |
summary |
Summary based on search results. |
Reference
Defines reference in reply.
| Fields | |
|---|---|
uri |
URI link reference. |
anchor_text |
Anchor text. |
start |
Anchor text start index. |
end |
Anchor text end index. |
Schema
Defines the structure and layout of a type of document data.
| Fields | |
|---|---|
name |
Immutable. The full resource name of the schema, in the format of This field must be a UTF-8 encoded string with a length limit of 1024 characters. |
Union field schema. Schema representation. One of struct_schema or json_schema should be provided otherwise an INVALID_ARGUMENT error is thrown. schema can be only one of the following: |
|
struct_schema |
The structured representation of the schema. |
json_schema |
The JSON representation of the schema. |
SearchInfo
Detailed search information.
| Fields | |
|---|---|
search_query |
The user's search query. See The value must be a UTF-8 encoded string with a length limit of 5,000 characters. Otherwise, an At least one of |
order_by |
The order in which products are returned, if applicable. See The value must be a UTF-8 encoded string with a length limit of 1,000 characters. Otherwise, an This can only be set for |
offset |
An integer that specifies the current offset for pagination (the 0-indexed starting location, amongst the products deemed by the API as relevant). See If this field is negative, an This can only be set for |
SearchRequest
Request message for SearchService.Search method.
| Fields | |
|---|---|
serving_config |
Required. The resource name of the Search serving config, such as |
branch |
The branch resource name, such as Use |
query |
Raw search query. |
image_query |
Raw image query. |
page_size |
Maximum number of If this field is negative, an |
page_token |
A page token received from a previous When paginating, all other parameters provided to |
offset |
A 0-indexed integer that specifies the current offset (that is, starting result location, amongst the If this field is negative, an |
filter |
The filter syntax consists of an expression language for constructing a predicate from one or more fields of the documents being filtered. Filter expression is case-sensitive. If this field is unrecognizable, an |
order_by |
The order in which documents are returned. Documents can be ordered by a field in an If this field is unrecognizable, an |
user_info |
Information about the end user. Highly recommended for analytics. |
facet_specs[] |
Facet specifications for faceted search. If empty, no facets are returned. A maximum of 100 values are allowed. Otherwise, an |
boost_spec |
Boost specification to boost certain documents. |
params |
Additional search parameters. For public website search only, supported values are:
|
query_expansion_spec |
The query expansion specification that specifies the conditions under which query expansion occurs. |
spell_correction_spec |
The spell correction specification that specifies the mode under which spell correction takes effect. |
user_pseudo_id |
A unique identifier for tracking visitors. For example, this could be implemented with an HTTP cookie, which should be able to uniquely identify a visitor on a single device. This unique identifier should not change if the visitor logs in or out of the website. This field should NOT have a fixed value such as This should be the same identifier as The field must be a UTF-8 encoded string with a length limit of 128 characters. Otherwise, an |
content_search_spec |
A specification for configuring the behavior of content search. |
embedding_spec |
Uses the provided embedding to do additional semantic document retrieval. The retrieval is based on the dot product of [SearchRequest.embedding_spec.embedding_vectors.vector][] and the document embedding that is provided in [SearchRequest.embedding_spec.embedding_vectors.field_path][]. If [SearchRequest.embedding_spec.embedding_vectors.field_path][] is not provided, it will use [ServingConfig.embedding_config.field_paths][]. |
ranking_expression |
The ranking expression controls the customized ranking on retrieval documents. This overrides [ServingConfig.ranking_expression][]. The ranking expression is a single function or multiple functions that are joint by "+". * ranking_expression = function, { " + ", function }; Supported functions: * double * relevance_score * double * dotProduct(embedding_field_path) Function variables: Example ranking expression: If document has an embedding field doc_embedding, the ranking expression could be |
safe_search |
Whether to turn on safe search. This is only supported for website search. |
user_labels |
The user labels applied to a resource must meet the following requirements:
See Google Cloud Document for more details. |
BoostSpec
Boost specification to boost certain documents.
| Fields | |
|---|---|
condition_boost_specs[] |
Condition boost specifications. If a document matches multiple conditions in the specifictions, boost scores from these specifications are all applied and combined in a non-linear way. Maximum number of specifications is 20. |
ConditionBoostSpec
Boost applies to documents which match a condition.
| Fields | |
|---|---|
condition |
An expression which specifies a boost condition. The syntax and supported fields are the same as a filter expression. See Examples:
|
boost |
Strength of the condition boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0. Setting to 1.0 gives the document a big promotion. However, it does not necessarily mean that the boosted document will be the top result at all times, nor that other documents will be excluded. Results could still be shown even when none of them matches the condition. And results that are significantly more relevant to the search query can still trump your heavily favored but irrelevant documents. Setting to -1.0 gives the document a big demotion. However, results that are deeply relevant might still be shown. The document will have an upstream battle to get a fairly high ranking, but it is not blocked out completely. Setting to 0.0 means no boost applied. The boosting condition is ignored. |
ContentSearchSpec
A specification for configuring the behavior of content search.
| Fields | |
|---|---|
snippet_spec |
If |
summary_spec |
If |
extractive_content_spec |
If there is no extractive_content_spec provided, there will be no extractive answer in the search response. |
ExtractiveContentSpec
A specification for configuring the extractive content in a search response.
| Fields | |
|---|---|
max_extractive_answer_count |
The maximum number of extractive answers returned in each search result. An extractive answer is a verbatim answer extracted from the original document, which provides a precise and contextually relevant answer to the search query. If the number of matching answers is less than the At most one answer is returned for each |
max_extractive_segment_count |
The max number of extractive segments returned in each search result. Only applied if the An extractive segment is a text segment extracted from the original document that is relevant to the search query, and, in general, more verbose than an extractive answer. The segment could then be used as input for LLMs to generate summaries and answers. If the number of matching segments is less than |
num_previous_segments |
Specifies whether to also include the adjacent from each selected segments. Return at most |
num_next_segments |
Return at most |
SnippetSpec
A specification for configuring snippets in a search response.
| Fields | |
|---|---|
max_snippet_count |
[DEPRECATED] This field is deprecated. To control snippet return, use |
reference_only |
[DEPRECATED] This field is deprecated and will have no affect on the snippet. |
return_snippet |
If |
SummarySpec
A specification for configuring a summary returned in a search response.
| Fields | |
|---|---|
summary_result_count |
The number of top results to generate the summary from. If the number of results returned is less than At most five results can be used to generate a summary. |
include_citations |
Specifies whether to include citations in the summary. The default value is When this field is set to Example summary including citations: BigQuery is Google Cloud's fully managed and completely serverless enterprise data warehouse [1]. BigQuery supports all data types, works across clouds, and has built-in machine learning and business intelligence, all within a unified platform [2, 3]. The citation numbers refer to the returned search results and are 1-indexed. For example, [1] means that the sentence is attributed to the first search result. [2, 3] means that the sentence is attributed to both the second and third search results. |
ignore_adversarial_query |
Specifies whether to filter out adversarial queries. The default value is Google employs search-query classification to detect adversarial queries. No summary is returned if the search query is classified as an adversarial query. For example, a user might ask a question regarding negative comments about the company or submit a query designed to generate unsafe, policy-violating output. If this field is set to |
ignore_non_summary_seeking_query |
Specifies whether to filter out queries that are not summary-seeking. The default value is Google employs search-query classification to detect summary-seeking queries. No summary is returned if the search query is classified as a non-summary seeking query. For example, |
language_code |
Language code for Summary. Use language tags defined by BCP47. Note: This is an experimental feature. |
EmbeddingSpec
The specification that uses customized query embedding vector to do semantic document retrieval.
| Fields | |
|---|---|
embedding_vectors[] |
The embedding vector used for retrieval. Limit to 1. |
EmbeddingVector
Embedding vector.
| Fields | |
|---|---|
field_path |
Embedding field path in schema. |
vector[] |
Query embedding vector. |
FacetSpec
A facet specification to perform faceted search.
| Fields | |
|---|---|
facet_key |
Required. The facet key specification. |
limit |
Maximum of facet values that should be returned for this facet. If unspecified, defaults to 20. The maximum allowed value is 300. Values above 300 are coerced to 300. If this field is negative, an |
excluded_filter_keys[] |
List of keys to exclude when faceting. By default, Listing a facet key in this field allows its values to appear as facet results, even when they are filtered out of search results. Using this field does not affect what search results are returned. For example, suppose there are 100 documents with the color facet "Red" and 200 documents with the color facet "Blue". A query containing the filter "color:ANY("Red")" and having "color" as If "color" is listed in "excludedFilterKeys", then the query returns the facet values "Red" with count 100 and "Blue" with count 200, because the "color" key is now excluded from the filter. Because this field doesn't affect search results, the search results are still correctly filtered to return only "Red" documents. A maximum of 100 values are allowed. Otherwise, an |
enable_dynamic_position |
Enables dynamic position for this facet. If set to true, the position of this facet among all facets in the response is determined automatically. If dynamic facets are enabled, it is ordered together. If set to false, the position of this facet in the response is the same as in the request, and it is ranked before the facets with dynamic position enable and all dynamic facets. For example, you may always want to have rating facet returned in the response, but it's not necessarily to always display the rating facet at the top. In that case, you can set enable_dynamic_position to true so that the position of rating facet in response is determined automatically. Another example, assuming you have the following facets in the request:
And also you have a dynamic facets enabled, which generates a facet |
FacetKey
Specifies how a facet is computed.
| Fields | |
|---|---|
key |
Required. Supported textual and numerical facet keys in |
intervals[] |
Set only if values should be bucketed into intervals. Must be set for facets with numerical values. Must not be set for facet with text values. Maximum number of intervals is 30. |
restricted_values[] |
Only get facet for the given restricted values. Only supported on textual fields. For example, suppose "category" has three values "Action > 2022", "Action > 2021" and "Sci-Fi > 2022". If set "restricted_values" to "Action > 2022", the "category" facet only contains "Action > 2022". Only supported on textual fields. Maximum is 10. |
prefixes[] |
Only get facet values that start with the given string prefix. For example, suppose "category" has three values "Action > 2022", "Action > 2021" and "Sci-Fi > 2022". If set "prefixes" to "Action", the "category" facet only contains "Action > 2022" and "Action > 2021". Only supported on textual fields. Maximum is 10. |
contains[] |
Only get facet values that contains the given strings. For example, suppose "category" has three values "Action > 2022", "Action > 2021" and "Sci-Fi > 2022". If set "contains" to "2022", the "category" facet only contains "Action > 2022" and "Sci-Fi > 2022". Only supported on textual fields. Maximum is 10. |
case_insensitive |
True to make facet keys case insensitive when getting faceting values with prefixes or contains; false otherwise. |
order_by |
The order in which documents are returned. Allowed values are:
If not set, textual values are sorted in natural order; numerical intervals are sorted in the order given by |
ImageQuery
Specifies the image query input.
| Fields | |
|---|---|
Union field
|
|
image_bytes |
Base64 encoded image bytes. Supported image formats: JPEG, PNG, and BMP. |
QueryExpansionSpec
Specification to determine under which conditions query expansion should occur.
| Fields | |
|---|---|
condition |
The condition under which query expansion should occur. Default to |
pin_unexpanded_results |
Whether to pin unexpanded results. If this field is set to true, unexpanded products are always at the top of the search results, followed by the expanded results. |
Condition
Enum describing under which condition query expansion should occur.
| Enums | |
|---|---|
CONDITION_UNSPECIFIED |
Unspecified query expansion condition. In this case, server behavior defaults to Condition.DISABLED. |
DISABLED |
Disabled query expansion. Only the exact search query is used, even if SearchResponse.total_size is zero. |
AUTO |
Automatic query expansion built by the Search API. |
SpellCorrectionSpec
The specification for query spell correction.
| Fields | |
|---|---|
mode |
The mode under which spell correction should take effect to replace the original search query. Default to |
Mode
Enum describing under which mode spell correction should occur.
| Enums | |
|---|---|
MODE_UNSPECIFIED |
Unspecified spell correction mode. In this case, server behavior defaults to Mode.AUTO. |
SUGGESTION_ONLY |
Search API will try to find a spell suggestion if there is any and put in the SearchResponse.corrected_query. The spell suggestion will not be used as the search query. |
AUTO |
Automatic spell correction built by the Search API. Search will be based on the corrected query if found. |
SearchResponse
Response message for SearchService.Search method.
| Fields | |
|---|---|
results[] |
A list of matched documents. The order represents the ranking. |
facets[] |
Results of facets requested by user. |
guided_search_result |
Guided search result. |
total_size |
The estimated total count of matched items irrespective of pagination. The count of |
attribution_token |
A unique search token. This should be included in the |
redirect_uri |
The URI of a customer-defined redirect page. If redirect action is triggered, no search is performed, and only |
next_page_token |
A token that can be sent as |
corrected_query |
Contains the spell corrected query, if found. If the spell correction type is AUTOMATIC, then the search results are based on corrected_query. Otherwise the original query is used for search. |
summary |
A summary as part of the search results. This field is only returned if |
applied_controls[] |
Controls applied as part of the Control service. |
query_expansion_info |
Query expansion information for the returned results. |
Facet
A facet result.
| Fields | |
|---|---|
key |
The key for this facet. E.g., "colors" or "price". It matches |
values[] |
The facet values for this field. |
dynamic_facet |
Whether the facet is dynamically generated. |
FacetValue
A facet value which contains value names and their count.
| Fields | |
|---|---|
count |
Number of items that have this facet value. |
Union field facet_value. A facet value which contains values. facet_value can be only one of the following: |
|
value |
Text value of a facet, such as "Black" for facet "colors". |
interval |
Interval value for a facet, such as [10, 20) for facet "price". It matches |
GuidedSearchResult
Guided search result. The guided search helps user to refine the search results and narrow down to the real needs from a broaded search results.
| Fields | |
|---|---|
refinement_attributes[] |
A list of ranked refinement attributes. |
follow_up_questions[] |
Suggested follow-up questions. |
RefinementAttribute
Useful attribute for search result refinements.
| Fields | |
|---|---|
attribute_key |
Attribute key used to refine the results e.g. 'movie_type'. |
attribute_value |
Attribute value used to refine the results e.g. 'drama'. |
QueryExpansionInfo
Information describing query expansion including whether expansion has occurred.
| Fields | |
|---|---|
expanded_query |
Bool describing whether query expansion has occurred. |
pinned_result_count |
Number of pinned results. This field will only be set when expansion happens and |
SearchResult
Represents the search results.
| Fields | |
|---|---|
id |
|
document |
The document data snippet in the search response. Only fields that are marked as retrievable are populated. |
model_scores |
Google provided available scores. |
Summary
Summary of the top N search result specified by the summary spec.
| Fields | |
|---|---|
summary_text |
The summary content. |
summary_skipped_reasons[] |
Additional summary-skipped reasons. This provides the reason for ignored cases. If nothing is skipped, this field is not set. |
safety_attributes |
A collection of Safety Attribute categories and their associated confidence scores. |
SafetyAttributes
Safety Attribute categories and their associated confidence scores.
| Fields | |
|---|---|
categories[] |
The display names of Safety Attribute categories associated with the generated content. Order matches the Scores. |
scores[] |
The confidence scores of the each category, higher value means higher confidence. Order matches the Categories. |
SummarySkippedReason
An Enum for summary-skipped reasons.
| Enums | |
|---|---|
SUMMARY_SKIPPED_REASON_UNSPECIFIED |
Default value. The summary skipped reason is not specified. |
ADVERSARIAL_QUERY_IGNORED |
The adversarial query ignored case. Only populated when |
NON_SUMMARY_SEEKING_QUERY_IGNORED |
The non-summary seeking query ignored case. Only populated when |
OUT_OF_DOMAIN_QUERY_IGNORED |
The out-of-domain query ignored case. Google skips the summary if there are no high-relevance search results. For example, the data store contains facts about company A but the user query is asking questions about company B. |
POTENTIAL_POLICY_VIOLATION |
The potential policy violation case. Google skips the summary if there is a potential policy violation detected. This includes content that may be violent or toxic. |
LLM_ADDON_NOT_ENABLED |
The LLM addon not enabled case. Google skips the summary if the LLM addon is not enabled. |
TextInput
Defines text input.
| Fields | |
|---|---|
input |
Text input. |
context |
Conversation context of the input. |
TransactionInfo
A transaction represents the entire purchase transaction.
| Fields | |
|---|---|
currency |
Required. Currency code. Use three-character ISO-4217 code. |
transaction_id |
The transaction ID with a length limit of 128 characters. |
value |
Required. Total non-zero value associated with the transaction. This value may include shipping, tax, or other adjustments to the total value that you want to include. |
tax |
All the taxes associated with the transaction. |
cost |
All the costs associated with the products. These can be manufacturing costs, shipping expenses not borne by the end user, or any other costs, such that: |
discount_value |
The total discount(s) value applied to this transaction. This figure should be excluded from For example, if a user paid This means that profit is calculated the same way, regardless of the discount value, and that |
UpdateConversationRequest
Request for UpdateConversation method.
| Fields | |
|---|---|
conversation |
Required. The Conversation to update. |
update_mask |
Indicates which fields in the provided
If not set or empty, all supported fields are updated. |
UpdateDocumentRequest
Request message for DocumentService.UpdateDocument method.
| Fields | |
|---|---|
document |
Required. The document to update/create. If the caller does not have permission to update the If the |
allow_missing |
If set to true, and the |
UpdateSchemaMetadata
Metadata for UpdateSchema LRO.
| Fields | |
|---|---|
create_time |
Operation create time. |
update_time |
Operation last update time. If the operation is done, this is also the finish time. |
UpdateSchemaRequest
Request message for SchemaService.UpdateSchema method.
| Fields | |
|---|---|
schema |
Required. The |
allow_missing |
If set to true, and the |
UserEvent
UserEvent captures all metadata information Discovery Engine API needs to know about how end users interact with customers' website.
| Fields | |
|---|---|
event_type |
Required. User event type. Allowed values are: Generic values:
Retail-related values:
Media-related values:
|
user_pseudo_id |
Required. A unique identifier for tracking visitors. For example, this could be implemented with an HTTP cookie, which should be able to uniquely identify a visitor on a single device. This unique identifier should not change if the visitor log in/out of the website. Do not set the field to the same fixed ID for different users. This mixes the event history of those users together, which results in degraded model quality. The field must be a UTF-8 encoded string with a length limit of 128 characters. Otherwise, an The field should not contain PII or user-data. We recommend to use Google Analytics Client ID for this field. |
event_time |
Only required for |
user_info |
Information about the end user. |
direct_user_request |
Should set to true if the request is made directly from the end user, in which case the This flag should be set only if the API request is made directly from the end user such as a mobile app (and not if a gateway or a server is processing and pushing the user events). This should not be set when using the JavaScript tag in |
session_id |
A unique identifier for tracking a visitor session with a length limit of 128 bytes. A session is an aggregation of an end user behavior in a time span. A general guideline to populate the session_id:
|
page_info |
Page metadata such as categories and other critical information for certain event types such as |
attribution_token |
Token to attribute an API response to user action(s) to trigger the event. Highly recommended for user events that are the result of The value must be one of:
This token enables us to accurately attribute page view or conversion completion back to the event and the particular predict response containing this clicked/purchased product. If user clicks on product K in the recommendation results, pass |
filter |
The filter syntax consists of an expression language for constructing a predicate from one or more fields of the documents being filtered. One example is for Similarly, for The value must be a UTF-8 encoded string with a length limit of 1,000 characters. Otherwise, an |
documents[] |
List of This field is optional except for the following event types:
In a |
panel |
Panel metadata associated with this user event. |
search_info |
This field should be set for |
completion_info |
This field should be set for |
transaction_info |
The transaction metadata (if any) associated with this user event. |
tag_ids[] |
A list of identifiers for the independent experiment groups this user event belongs to. This is used to distinguish between user events associated with different experiment setups on the customer end. |
promotion_ids[] |
The promotion IDs if this is an event associated with promotions. Currently, this field is restricted to at most one ID. |
attributes |
Extra user event features to include in the recommendation model. These attributes must NOT contain data that needs to be parsed or processed further, e.g. JSON or other encodings. If you provide custom attributes for ingested user events, also include them in the user events that you associate with prediction requests. Custom attribute formatting must be consistent between imported events and events provided with prediction requests. This lets the Discovery Engine API use those custom attributes when training models and serving predictions, which helps improve recommendation quality. This field needs to pass all below criteria, otherwise an
For product recommendations, an example of extra user information is |
media_info |
Media-specific info. |
UserInfo
Information of an end user.
| Fields | |
|---|---|
user_id |
Highly recommended for logged-in users. Unique identifier for logged-in user, such as a user name. Don't set for anonymous users. Always use a hashed value for this ID. Don't set the field to the same fixed ID for different users. This mixes the event history of those users together, which results in degraded model quality. The field must be a UTF-8 encoded string with a length limit of 128 characters. Otherwise, an |
user_agent |
User agent as included in the HTTP header. The field must be a UTF-8 encoded string with a length limit of 1,000 characters. Otherwise, an This should not be set when using the client side event reporting with GTM or JavaScript tag in |
WriteUserEventRequest
Request message for WriteUserEvent method.
| Fields | |
|---|---|
parent |
Required. The parent DataStore resource name, such as |
user_event |
Required. User event to write. |