google-cloud-discovery_engine-v1beta 0.20.1 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2110b6076063952f57281b6236885c6768e4c30c4449ce59696442fc19ccb74b
-  data.tar.gz: 5d1177c31411721a942f882ffe161766d437a50199fe8014200e17fb9c69e359
+  metadata.gz: 78e275b33576c302ab8e440d1c9163966b8d2fc2161ed9ad7c0dd7713d0f646d
+  data.tar.gz: 1c667b21e7349f66746ff44468c0dc048970d4992d0744b767ca76d8567109b6
 SHA512:
-  metadata.gz: 4aaf723159521cb49de8b0ed2f979bdcca4fae27b3783f006c2bf2c61829c1930597a7e244f48d60aa97066092abdc5ef655468b7ad4a5017ff16f6c0970e2b9
-  data.tar.gz: 723b3782504a8d6d9c755ad1a683741b69d8616a37ce1108903b3a6dfec66192114c6fb7e9306b326ebe6f2965dcf4f4cdbdfa8b498276175b52e1cb9b134872
+  metadata.gz: 17395001fae5b28121556691832d9ef5be24ab74cd05d6c8bf9a7f81699b2c360f37f6eb2975b340bb68622fea5d40be0dbef145641ea15ab9e5b38168f6d219
+  data.tar.gz: 9ad1d72c052d58339762023545c6b5731ea5f47a400b58ac4742dc57736403b1e0f081a6638267dc020ba44d4ba2078f4662966435fee46a014ee61d74d9cbb9

data/lib/google/cloud/discovery_engine/v1beta/conversational_search_service/client.rb

@@ -1355,7 +1355,7 @@ module Google
             #   @param options [::Gapic::CallOptions, ::Hash]
             #     Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
             #
-            # @overload get_session(name: nil)
+            # @overload get_session(name: nil, include_answer_details: nil)
             #   Pass arguments to `get_session` via keyword arguments. Note that at
             #   least one keyword argument is required. To specify no parameters, or to keep all
             #   the default parameter values, pass an empty Hash as a request object (see above).
@@ -1363,6 +1363,9 @@ module Google
             #   @param name [::String]
             #     Required. The resource name of the Session to get. Format:
             #     `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store_id}/sessions/{session_id}`
+            #   @param include_answer_details [::Boolean]
+            #     Optional. If set to true, the full session including all answer details
+            #     will be returned.
             #
             # @yield [response, operation] Access the result along with the RPC operation
             # @yieldparam response [::Google::Cloud::DiscoveryEngine::V1beta::Session]
@@ -1457,22 +1460,39 @@ module Google
             #     A page token, received from a previous `ListSessions` call.
             #     Provide this to retrieve the subsequent page.
             #   @param filter [::String]
-            #     A filter to apply on the list results. The supported features are:
-            #     user_pseudo_id, state.
-            #
-            #     Example:
+            #     A comma-separated list of fields to filter by, in EBNF grammar.
+            #     The supported fields are:
+            #     * `user_pseudo_id`
+            #     * `state`
+            #     * `display_name`
+            #     * `starred`
+            #     * `is_pinned`
+            #     * `labels`
+            #     * `create_time`
+            #     * `update_time`
+            #
+            #     Examples:
             #     "user_pseudo_id = some_id"
+            #     "display_name = \"some_name\""
+            #     "starred = true"
+            #     "is_pinned=true AND (NOT labels:hidden)"
+            #     "create_time > \"1970-01-01T12:00:00Z\""
             #   @param order_by [::String]
             #     A comma-separated list of fields to order by, sorted in ascending order.
             #     Use "desc" after a field name for descending.
             #     Supported fields:
+            #
             #       * `update_time`
             #       * `create_time`
             #       * `session_name`
+            #       * `is_pinned`
             #
             #     Example:
-            #     "update_time desc"
-            #     "create_time"
+            #
+            #     * "update_time desc"
+            #     * "create_time"
+            #     * "is_pinned desc,update_time desc": list sessions by is_pinned first, then
+            #        by update_time.
             #
             # @yield [response, operation] Access the result along with the RPC operation
             # @yieldparam response [::Gapic::PagedEnumerable<::Google::Cloud::DiscoveryEngine::V1beta::Session>]

data/lib/google/cloud/discovery_engine/v1beta/conversational_search_service/rest/client.rb

@@ -1271,7 +1271,7 @@ module Google
               #   @param options [::Gapic::CallOptions, ::Hash]
               #     Overrides the default settings for this call, e.g, timeout, retries etc. Optional.
               #
-              # @overload get_session(name: nil)
+              # @overload get_session(name: nil, include_answer_details: nil)
               #   Pass arguments to `get_session` via keyword arguments. Note that at
               #   least one keyword argument is required. To specify no parameters, or to keep all
               #   the default parameter values, pass an empty Hash as a request object (see above).
@@ -1279,6 +1279,9 @@ module Google
               #   @param name [::String]
               #     Required. The resource name of the Session to get. Format:
               #     `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store_id}/sessions/{session_id}`
+              #   @param include_answer_details [::Boolean]
+              #     Optional. If set to true, the full session including all answer details
+              #     will be returned.
               # @yield [result, operation] Access the result along with the TransportOperation object
               # @yieldparam result [::Google::Cloud::DiscoveryEngine::V1beta::Session]
               # @yieldparam operation [::Gapic::Rest::TransportOperation]
@@ -1366,22 +1369,39 @@ module Google
               #     A page token, received from a previous `ListSessions` call.
               #     Provide this to retrieve the subsequent page.
               #   @param filter [::String]
-              #     A filter to apply on the list results. The supported features are:
-              #     user_pseudo_id, state.
-              #
-              #     Example:
+              #     A comma-separated list of fields to filter by, in EBNF grammar.
+              #     The supported fields are:
+              #     * `user_pseudo_id`
+              #     * `state`
+              #     * `display_name`
+              #     * `starred`
+              #     * `is_pinned`
+              #     * `labels`
+              #     * `create_time`
+              #     * `update_time`
+              #
+              #     Examples:
               #     "user_pseudo_id = some_id"
+              #     "display_name = \"some_name\""
+              #     "starred = true"
+              #     "is_pinned=true AND (NOT labels:hidden)"
+              #     "create_time > \"1970-01-01T12:00:00Z\""
               #   @param order_by [::String]
               #     A comma-separated list of fields to order by, sorted in ascending order.
               #     Use "desc" after a field name for descending.
               #     Supported fields:
+              #
               #       * `update_time`
               #       * `create_time`
               #       * `session_name`
+              #       * `is_pinned`
               #
               #     Example:
-              #     "update_time desc"
-              #     "create_time"
+              #
+              #     * "update_time desc"
+              #     * "create_time"
+              #     * "is_pinned desc,update_time desc": list sessions by is_pinned first, then
+              #        by update_time.
               # @yield [result, operation] Access the result along with the TransportOperation object
               # @yieldparam result [::Gapic::Rest::PagedEnumerable<::Google::Cloud::DiscoveryEngine::V1beta::Session>]
               # @yieldparam operation [::Gapic::Rest::TransportOperation]

data/lib/google/cloud/discovery_engine/v1beta/rest.rb

@@ -33,6 +33,7 @@ require "google/cloud/discovery_engine/v1beta/sample_query_set_service/rest"
 require "google/cloud/discovery_engine/v1beta/schema_service/rest"
 require "google/cloud/discovery_engine/v1beta/search_tuning_service/rest"
 require "google/cloud/discovery_engine/v1beta/serving_config_service/rest"
+require "google/cloud/discovery_engine/v1beta/session_service/rest"
 require "google/cloud/discovery_engine/v1beta/site_search_engine_service/rest"
 require "google/cloud/discovery_engine/v1beta/user_event_service/rest"
 require "google/cloud/discovery_engine/v1beta/version"

data/lib/google/cloud/discovery_engine/v1beta/search_service/client.rb

@@ -217,7 +217,7 @@ module Google
             #   @param options [::Gapic::CallOptions, ::Hash]
             #     Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
             #
-            # @overload search(serving_config: nil, branch: nil, query: nil, image_query: nil, page_size: nil, page_token: nil, offset: nil, one_box_page_size: nil, data_store_specs: nil, filter: nil, canonical_filter: nil, order_by: nil, user_info: nil, language_code: nil, region_code: nil, facet_specs: nil, boost_spec: nil, params: nil, query_expansion_spec: nil, spell_correction_spec: nil, user_pseudo_id: nil, content_search_spec: nil, embedding_spec: nil, ranking_expression: nil, safe_search: nil, user_labels: nil, natural_language_query_understanding_spec: nil, search_as_you_type_spec: nil, session: nil, session_spec: nil, relevance_threshold: nil, personalization_spec: nil)
+            # @overload search(serving_config: nil, branch: nil, query: nil, image_query: nil, page_size: nil, page_token: nil, offset: nil, one_box_page_size: nil, data_store_specs: nil, filter: nil, canonical_filter: nil, order_by: nil, user_info: nil, language_code: nil, region_code: nil, facet_specs: nil, boost_spec: nil, params: nil, query_expansion_spec: nil, spell_correction_spec: nil, user_pseudo_id: nil, content_search_spec: nil, embedding_spec: nil, ranking_expression: nil, ranking_expression_backend: nil, safe_search: nil, user_labels: nil, natural_language_query_understanding_spec: nil, search_as_you_type_spec: nil, session: nil, session_spec: nil, relevance_threshold: nil, personalization_spec: nil)
             #   Pass arguments to `search` via keyword arguments. Note that at
             #   least one keyword argument is required. To specify no parameters, or to keep all
             #   the default parameter values, pass an empty Hash as a request object (see above).
@@ -397,8 +397,14 @@ module Google
             #     The ranking expression controls the customized ranking on retrieval
             #     documents. This overrides
             #     {::Google::Cloud::DiscoveryEngine::V1beta::ServingConfig#ranking_expression ServingConfig.ranking_expression}.
-            #     The ranking expression is a single function or multiple functions that are
-            #     joined by "+".
+            #     The syntax and supported features depend on the
+            #     `ranking_expression_backend` value. If `ranking_expression_backend` is not
+            #     provided, it defaults to `RANK_BY_EMBEDDING`.
+            #
+            #     If
+            #     {::Google::Cloud::DiscoveryEngine::V1beta::SearchRequest#ranking_expression_backend ranking_expression_backend}
+            #     is not provided or set to `RANK_BY_EMBEDDING`, it should be a single
+            #     function or multiple functions that are joined by "+".
             #
             #       * ranking_expression = function, { " + ", function };
             #
@@ -413,13 +419,73 @@ module Google
             #       between query and document.
             #       * `embedding_field_path`: the document embedding field
             #       used with query embedding vector.
-            #       * `dotProduct`: embedding function between embedding_field_path and query
-            #       embedding vector.
+            #       * `dotProduct`: embedding function between `embedding_field_path` and
+            #       query embedding vector.
             #
             #      Example ranking expression:
             #
             #        If document has an embedding field doc_embedding, the ranking expression
             #        could be `0.5 * relevance_score + 0.3 * dotProduct(doc_embedding)`.
+            #
+            #     If
+            #     {::Google::Cloud::DiscoveryEngine::V1beta::SearchRequest#ranking_expression_backend ranking_expression_backend}
+            #     is set to `RANK_BY_FORMULA`, the following expression types (and
+            #     combinations of those chained using + or
+            #     * operators) are supported:
+            #
+            #       * `double`
+            #       * `signal`
+            #       * `log(signal)`
+            #       * `exp(signal)`
+            #       * `rr(signal, double > 0)`  -- reciprocal rank transformation with second
+            #       argument being a denominator constant.
+            #       * `is_nan(signal)` -- returns 0 if signal is NaN, 1 otherwise.
+            #       * `fill_nan(signal1, signal2 | double)` -- if signal1 is NaN, returns
+            #       signal2 | double, else returns signal1.
+            #
+            #       Here are a few examples of ranking formulas that use the supported
+            #       ranking expression types:
+            #
+            #       - `0.2 * semantic_similarity_score + 0.8 * log(keyword_similarity_score)`
+            #       -- mostly rank by the logarithm of `keyword_similarity_score` with slight
+            #       `semantic_smilarity_score` adjustment.
+            #       - `0.2 * exp(fill_nan(semantic_similarity_score, 0)) + 0.3 *
+            #       is_nan(keyword_similarity_score)` -- rank by the exponent of
+            #       `semantic_similarity_score` filling the value with 0 if it's NaN, also
+            #       add constant 0.3 adjustment to the final score if
+            #       `semantic_similarity_score` is NaN.
+            #       - `0.2 * rr(semantic_similarity_score, 16) + 0.8 *
+            #       rr(keyword_similarity_score, 16)` -- mostly rank by the reciprocal rank
+            #       of `keyword_similarity_score` with slight adjustment of reciprocal rank
+            #       of `semantic_smilarity_score`.
+            #
+            #     The following signals are supported:
+            #
+            #       * `semantic_similarity_score`: semantic similarity adjustment that is
+            #       calculated using the embeddings generated by a proprietary Google model.
+            #       This score determines how semantically similar a search query is to a
+            #       document.
+            #       * `keyword_similarity_score`: keyword match adjustment uses the Best
+            #       Match 25 (BM25) ranking function. This score is calculated using a
+            #       probabilistic model to estimate the probability that a document is
+            #       relevant to a given query.
+            #       * `relevance_score`: semantic relevance adjustment that uses a
+            #       proprietary Google model to determine the meaning and intent behind a
+            #       user's query in context with the content in the documents.
+            #       * `pctr_rank`: predicted conversion rate adjustment as a rank use
+            #       predicted Click-through rate (pCTR) to gauge the relevance and
+            #       attractiveness of a search result from a user's perspective. A higher
+            #       pCTR suggests that the result is more likely to satisfy the user's query
+            #       and intent, making it a valuable signal for ranking.
+            #       * `freshness_rank`: freshness adjustment as a rank
+            #       * `document_age`: The time in hours elapsed since the document was last
+            #       updated, a floating-point number (e.g., 0.25 means 15 minutes).
+            #       * `topicality_rank`: topicality adjustment as a rank. Uses proprietary
+            #       Google model to determine the keyword-based overlap between the query and
+            #       the document.
+            #       * `base_rank`: the default rank of the result
+            #   @param ranking_expression_backend [::Google::Cloud::DiscoveryEngine::V1beta::SearchRequest::RankingExpressionBackend]
+            #     The backend to use for the ranking expression evaluation.
             #   @param safe_search [::Boolean]
             #     Whether to turn on safe search. This is only supported for
             #     website search.
@@ -455,22 +521,16 @@ module Google
             #     between /search API calls and /answer API calls.
             #
             #     Example #1 (multi-turn /search API calls):
-            #       1. Call /search API with the auto-session mode (see below).
-            #       2. Call /search API with the session ID generated in the first call.
-            #          Here, the previous search query gets considered in query
-            #          standing. I.e., if the first query is "How did Alphabet do in 2022?"
-            #          and the current query is "How about 2023?", the current query will
-            #          be interpreted as "How did Alphabet do in 2023?".
+            #       Call /search API with the session ID generated in the first call.
+            #       Here, the previous search query gets considered in query
+            #       standing. I.e., if the first query is "How did Alphabet do in 2022?"
+            #       and the current query is "How about 2023?", the current query will
+            #       be interpreted as "How did Alphabet do in 2023?".
             #
             #     Example #2 (coordination between /search API calls and /answer API calls):
-            #       1. Call /search API with the auto-session mode (see below).
-            #       2. Call /answer API with the session ID generated in the first call.
-            #          Here, the answer generation happens in the context of the search
-            #          results from the first search call.
-            #
-            #     Auto-session mode: when `projects/.../sessions/-` is used, a new session
-            #     gets automatically created. Otherwise, users can use the create-session API
-            #     to create a session manually.
+            #       Call /answer API with the session ID generated in the first call.
+            #       Here, the answer generation happens in the context of the search
+            #       results from the first search call.
             #
             #     Multi-turn Search feature is currently at private GA stage. Please use
             #     v1alpha or v1beta version instead before we launch this feature to public
@@ -592,7 +652,7 @@ module Google
             #   @param options [::Gapic::CallOptions, ::Hash]
             #     Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
             #
-            # @overload search_lite(serving_config: nil, branch: nil, query: nil, image_query: nil, page_size: nil, page_token: nil, offset: nil, one_box_page_size: nil, data_store_specs: nil, filter: nil, canonical_filter: nil, order_by: nil, user_info: nil, language_code: nil, region_code: nil, facet_specs: nil, boost_spec: nil, params: nil, query_expansion_spec: nil, spell_correction_spec: nil, user_pseudo_id: nil, content_search_spec: nil, embedding_spec: nil, ranking_expression: nil, safe_search: nil, user_labels: nil, natural_language_query_understanding_spec: nil, search_as_you_type_spec: nil, session: nil, session_spec: nil, relevance_threshold: nil, personalization_spec: nil)
+            # @overload search_lite(serving_config: nil, branch: nil, query: nil, image_query: nil, page_size: nil, page_token: nil, offset: nil, one_box_page_size: nil, data_store_specs: nil, filter: nil, canonical_filter: nil, order_by: nil, user_info: nil, language_code: nil, region_code: nil, facet_specs: nil, boost_spec: nil, params: nil, query_expansion_spec: nil, spell_correction_spec: nil, user_pseudo_id: nil, content_search_spec: nil, embedding_spec: nil, ranking_expression: nil, ranking_expression_backend: nil, safe_search: nil, user_labels: nil, natural_language_query_understanding_spec: nil, search_as_you_type_spec: nil, session: nil, session_spec: nil, relevance_threshold: nil, personalization_spec: nil)
             #   Pass arguments to `search_lite` via keyword arguments. Note that at
             #   least one keyword argument is required. To specify no parameters, or to keep all
             #   the default parameter values, pass an empty Hash as a request object (see above).
@@ -772,8 +832,14 @@ module Google
             #     The ranking expression controls the customized ranking on retrieval
             #     documents. This overrides
             #     {::Google::Cloud::DiscoveryEngine::V1beta::ServingConfig#ranking_expression ServingConfig.ranking_expression}.
-            #     The ranking expression is a single function or multiple functions that are
-            #     joined by "+".
+            #     The syntax and supported features depend on the
+            #     `ranking_expression_backend` value. If `ranking_expression_backend` is not
+            #     provided, it defaults to `RANK_BY_EMBEDDING`.
+            #
+            #     If
+            #     {::Google::Cloud::DiscoveryEngine::V1beta::SearchRequest#ranking_expression_backend ranking_expression_backend}
+            #     is not provided or set to `RANK_BY_EMBEDDING`, it should be a single
+            #     function or multiple functions that are joined by "+".
             #
             #       * ranking_expression = function, { " + ", function };
             #
@@ -788,13 +854,73 @@ module Google
             #       between query and document.
             #       * `embedding_field_path`: the document embedding field
             #       used with query embedding vector.
-            #       * `dotProduct`: embedding function between embedding_field_path and query
-            #       embedding vector.
+            #       * `dotProduct`: embedding function between `embedding_field_path` and
+            #       query embedding vector.
             #
             #      Example ranking expression:
             #
             #        If document has an embedding field doc_embedding, the ranking expression
             #        could be `0.5 * relevance_score + 0.3 * dotProduct(doc_embedding)`.
+            #
+            #     If
+            #     {::Google::Cloud::DiscoveryEngine::V1beta::SearchRequest#ranking_expression_backend ranking_expression_backend}
+            #     is set to `RANK_BY_FORMULA`, the following expression types (and
+            #     combinations of those chained using + or
+            #     * operators) are supported:
+            #
+            #       * `double`
+            #       * `signal`
+            #       * `log(signal)`
+            #       * `exp(signal)`
+            #       * `rr(signal, double > 0)`  -- reciprocal rank transformation with second
+            #       argument being a denominator constant.
+            #       * `is_nan(signal)` -- returns 0 if signal is NaN, 1 otherwise.
+            #       * `fill_nan(signal1, signal2 | double)` -- if signal1 is NaN, returns
+            #       signal2 | double, else returns signal1.
+            #
+            #       Here are a few examples of ranking formulas that use the supported
+            #       ranking expression types:
+            #
+            #       - `0.2 * semantic_similarity_score + 0.8 * log(keyword_similarity_score)`
+            #       -- mostly rank by the logarithm of `keyword_similarity_score` with slight
+            #       `semantic_smilarity_score` adjustment.
+            #       - `0.2 * exp(fill_nan(semantic_similarity_score, 0)) + 0.3 *
+            #       is_nan(keyword_similarity_score)` -- rank by the exponent of
+            #       `semantic_similarity_score` filling the value with 0 if it's NaN, also
+            #       add constant 0.3 adjustment to the final score if
+            #       `semantic_similarity_score` is NaN.
+            #       - `0.2 * rr(semantic_similarity_score, 16) + 0.8 *
+            #       rr(keyword_similarity_score, 16)` -- mostly rank by the reciprocal rank
+            #       of `keyword_similarity_score` with slight adjustment of reciprocal rank
+            #       of `semantic_smilarity_score`.
+            #
+            #     The following signals are supported:
+            #
+            #       * `semantic_similarity_score`: semantic similarity adjustment that is
+            #       calculated using the embeddings generated by a proprietary Google model.
+            #       This score determines how semantically similar a search query is to a
+            #       document.
+            #       * `keyword_similarity_score`: keyword match adjustment uses the Best
+            #       Match 25 (BM25) ranking function. This score is calculated using a
+            #       probabilistic model to estimate the probability that a document is
+            #       relevant to a given query.
+            #       * `relevance_score`: semantic relevance adjustment that uses a
+            #       proprietary Google model to determine the meaning and intent behind a
+            #       user's query in context with the content in the documents.
+            #       * `pctr_rank`: predicted conversion rate adjustment as a rank use
+            #       predicted Click-through rate (pCTR) to gauge the relevance and
+            #       attractiveness of a search result from a user's perspective. A higher
+            #       pCTR suggests that the result is more likely to satisfy the user's query
+            #       and intent, making it a valuable signal for ranking.
+            #       * `freshness_rank`: freshness adjustment as a rank
+            #       * `document_age`: The time in hours elapsed since the document was last
+            #       updated, a floating-point number (e.g., 0.25 means 15 minutes).
+            #       * `topicality_rank`: topicality adjustment as a rank. Uses proprietary
+            #       Google model to determine the keyword-based overlap between the query and
+            #       the document.
+            #       * `base_rank`: the default rank of the result
+            #   @param ranking_expression_backend [::Google::Cloud::DiscoveryEngine::V1beta::SearchRequest::RankingExpressionBackend]
+            #     The backend to use for the ranking expression evaluation.
             #   @param safe_search [::Boolean]
             #     Whether to turn on safe search. This is only supported for
             #     website search.
@@ -830,22 +956,16 @@ module Google
             #     between /search API calls and /answer API calls.
             #
             #     Example #1 (multi-turn /search API calls):
-            #       1. Call /search API with the auto-session mode (see below).
-            #       2. Call /search API with the session ID generated in the first call.
-            #          Here, the previous search query gets considered in query
-            #          standing. I.e., if the first query is "How did Alphabet do in 2022?"
-            #          and the current query is "How about 2023?", the current query will
-            #          be interpreted as "How did Alphabet do in 2023?".
+            #       Call /search API with the session ID generated in the first call.
+            #       Here, the previous search query gets considered in query
+            #       standing. I.e., if the first query is "How did Alphabet do in 2022?"
+            #       and the current query is "How about 2023?", the current query will
+            #       be interpreted as "How did Alphabet do in 2023?".
             #
             #     Example #2 (coordination between /search API calls and /answer API calls):
-            #       1. Call /search API with the auto-session mode (see below).
-            #       2. Call /answer API with the session ID generated in the first call.
-            #          Here, the answer generation happens in the context of the search
-            #          results from the first search call.
-            #
-            #     Auto-session mode: when `projects/.../sessions/-` is used, a new session
-            #     gets automatically created. Otherwise, users can use the create-session API
-            #     to create a session manually.
+            #       Call /answer API with the session ID generated in the first call.
+            #       Here, the answer generation happens in the context of the search
+            #       results from the first search call.
             #
             #     Multi-turn Search feature is currently at private GA stage. Please use
             #     v1alpha or v1beta version instead before we launch this feature to public