From 615600712839fd0dcb55ffe7942f32d60b5baf7a Mon Sep 17 00:00:00 2001 From: Travis Prescott Date: Wed, 8 Sep 2021 15:45:21 -0700 Subject: [PATCH 1/4] Update SearchClient.search API. --- .../azure/search/documents/_search_client.py | 39 +++++++++++++++---- 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/sdk/search/azure-search-documents/azure/search/documents/_search_client.py b/sdk/search/azure-search-documents/azure/search/documents/_search_client.py index 27853cd783cb..3b2863db0a38 100644 --- a/sdk/search/azure-search-documents/azure/search/documents/_search_client.py +++ b/sdk/search/azure-search-documents/azure/search/documents/_search_client.py @@ -200,12 +200,23 @@ def search(self, search_text, **kwargs): :keyword query_language: A value that specifies the language of the search query. Possible values include: "none", "en-us". :paramtype query_language: str or ~azure.search.documents.models.QueryLanguage - :keyword speller: A value that specified the type of the speller to use to spell-correct + :keyword query_speller: A value that specified the type of the speller to use to spell-correct individual search query terms. Possible values include: "none", "lexicon". - :paramtype speller: str or ~azure.search.documents.models.Speller - :keyword answers: A value that specifies whether answers should be returned as part of the search - response. Possible values include: "none", "extractive". - :paramtype answers: str or ~azure.search.documents.models.Answers + :paramtype query_speller: str or ~azure.search.documents.models.Speller + :keyword query_answer: This parameter is only valid if the query type is 'semantic'. If set, + the query returns answers extracted from key passages in the highest ranked documents. + Possible values include: "none", "extractive". + :paramtype query_answer: str or ~azure.search.documents.models.Answers + :keyword int query_answer_count: This parameter is only valid if the query type is 'semantic'. + Configures the number of answers returned. Default count is 1. + :keyword query_caption: This parameter is only valid if the query type is 'semantic'. If set, the + query returns captions extracted from key passages in the highest ranked documents. + Defaults to 'None'. Possible values include: "none", "extractive". + :paramtype query_caption: str or ~azure.search.documents.models.Captions + :keyword bool query_caption_highlight: This parameter is only valid if the query type is 'semantic' when + query_caption is set to 'extractive'. Determines whether highlighting is enabled. + Defaults to 'true'. + :keyword list[str] semantic_fields: The list of field names used for semantic search. :keyword list[str] select: The list of fields to retrieve. If unspecified, all fields marked as retrievable in the schema are included. :keyword int skip: The number of search results to skip. This value cannot be greater than 100,000. @@ -259,11 +270,21 @@ def search(self, search_text, **kwargs): search_fields_str = ",".join(search_fields) if search_fields else None search_mode = kwargs.pop("search_mode", None) query_language = kwargs.pop("query_language", None) - speller = kwargs.pop("speller", None) - answers = kwargs.pop("answers", None) + query_speller = kwargs.pop("query_speller", None) select = kwargs.pop("select", None) skip = kwargs.pop("skip", None) top = kwargs.pop("top", None) + + query_answer = kwargs.pop("query_answer", None) + query_answer_count = kwargs.pop("query_answer_count", None) + answers = '{}|count-{}'.format(query_answer, query_answer_count) + + query_caption = kwargs.pop("query_caption", None) + query_caption_highlight = kwargs.pop("query_caption_highlight", None) + captions = '{}|highlight-{}'.format(query_caption, query_caption_highlight) + + semantic_fields = kwargs.pop("semantic_fields", None) + query = SearchQuery( search_text=search_text, include_total_result_count=include_total_result_count, @@ -280,8 +301,10 @@ def search(self, search_text, **kwargs): search_fields=search_fields_str, search_mode=search_mode, query_language=query_language, - speller=speller, + speller=query_speller, answers=answers, + captions=captions, + semantic_fields=",".join(semantic_fields) if semantic_fields else None, select=select if isinstance(select, six.string_types) else None, skip=skip, top=top, From b1b73de2109529371f04c6ed2d436416890c8dee Mon Sep 17 00:00:00 2001 From: Travis Prescott Date: Wed, 8 Sep 2021 15:54:15 -0700 Subject: [PATCH 2/4] Update CHANGELOG and async SearchClient. --- .../azure-search-documents/CHANGELOG.md | 6 +++ .../documents/aio/_search_client_async.py | 39 +++++++++++++++---- 2 files changed, 37 insertions(+), 8 deletions(-) diff --git a/sdk/search/azure-search-documents/CHANGELOG.md b/sdk/search/azure-search-documents/CHANGELOG.md index dce720459dba..6d44c481b52e 100644 --- a/sdk/search/azure-search-documents/CHANGELOG.md +++ b/sdk/search/azure-search-documents/CHANGELOG.md @@ -4,8 +4,14 @@ ### Features Added +- Added properties to `SearchClient`: `query_answer`, `query_answer_count`, + `query_caption`, `query_caption_highlight` and `semantic_fields`. + ### Breaking Changes +- Renamed `SearchClient.speller` to `SearchClient.query_speller`. +- Removed keyword arguments from `SearchClient`: `answers` and `captions`. + ### Bugs Fixed ### Other Changes diff --git a/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py b/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py index 650b62dd1666..65cacbe50229 100644 --- a/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py +++ b/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py @@ -177,12 +177,23 @@ async def search(self, search_text, **kwargs): :keyword query_language: A value that specifies the language of the search query. Possible values include: "none", "en-us". :paramtype query_language: str or ~azure.search.documents.models.QueryLanguage - :keyword speller: A value that specified the type of the speller to use to spell-correct + :keyword query_speller: A value that specified the type of the speller to use to spell-correct individual search query terms. Possible values include: "none", "lexicon". - :paramtype speller: str or ~azure.search.documents.models.Speller - :keyword answers: A value that specifies whether answers should be returned as part of the search - response. Possible values include: "none", "extractive". - :paramtype answers: str or ~azure.search.documents.models.Answers + :paramtype query_speller: str or ~azure.search.documents.models.Speller + :keyword query_answer: This parameter is only valid if the query type is 'semantic'. If set, + the query returns answers extracted from key passages in the highest ranked documents. + Possible values include: "none", "extractive". + :paramtype query_answer: str or ~azure.search.documents.models.Answers + :keyword int query_answer_count: This parameter is only valid if the query type is 'semantic'. + Configures the number of answers returned. Default count is 1. + :keyword query_caption: This parameter is only valid if the query type is 'semantic'. If set, the + query returns captions extracted from key passages in the highest ranked documents. + Defaults to 'None'. Possible values include: "none", "extractive". + :paramtype query_caption: str or ~azure.search.documents.models.Captions + :keyword bool query_caption_highlight: This parameter is only valid if the query type is 'semantic' when + query_caption is set to 'extractive'. Determines whether highlighting is enabled. + Defaults to 'true'. + :keyword list[str] semantic_fields: The list of field names used for semantic search. :keyword list[str] select: The list of fields to retrieve. If unspecified, all fields marked as retrievable in the schema are included. :keyword int skip: The number of search results to skip. This value cannot be greater than 100,000. @@ -236,11 +247,21 @@ async def search(self, search_text, **kwargs): search_fields_str = ",".join(search_fields) if search_fields else None search_mode = kwargs.pop("search_mode", None) query_language = kwargs.pop("query_language", None) - speller = kwargs.pop("speller", None) - answers = kwargs.pop("answers", None) + query_speller = kwargs.pop("query_speller", None) select = kwargs.pop("select", None) skip = kwargs.pop("skip", None) top = kwargs.pop("top", None) + + query_answer = kwargs.pop("query_answer", None) + query_answer_count = kwargs.pop("query_answer_count", None) + answers = '{}|count-{}'.format(query_answer, query_answer_count) + + query_caption = kwargs.pop("query_caption", None) + query_caption_highlight = kwargs.pop("query_caption_highlight", None) + captions = '{}|highlight-{}'.format(query_caption, query_caption_highlight) + + semantic_fields = kwargs.pop("semantic_fields", None) + query = SearchQuery( search_text=search_text, include_total_result_count=include_total_result_count, @@ -257,8 +278,10 @@ async def search(self, search_text, **kwargs): search_fields=search_fields_str, search_mode=search_mode, query_language=query_language, - speller=speller, + speller=query_speller, answers=answers, + captions=captions, + semantic_fields=",".join(semantic_fields) if semantic_fields else None, select=select if isinstance(select, six.string_types) else None, skip=skip, top=top, From 7ce032c8cf9db340921bc0eb8006e9c192fbc6c5 Mon Sep 17 00:00:00 2001 From: Travis Prescott Date: Wed, 8 Sep 2021 16:01:27 -0700 Subject: [PATCH 3/4] Update parameter parsing for omitted values. --- .../azure/search/documents/_search_client.py | 4 ++-- .../azure/search/documents/aio/_search_client_async.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/sdk/search/azure-search-documents/azure/search/documents/_search_client.py b/sdk/search/azure-search-documents/azure/search/documents/_search_client.py index 3b2863db0a38..0d15e4aac9a3 100644 --- a/sdk/search/azure-search-documents/azure/search/documents/_search_client.py +++ b/sdk/search/azure-search-documents/azure/search/documents/_search_client.py @@ -277,11 +277,11 @@ def search(self, search_text, **kwargs): query_answer = kwargs.pop("query_answer", None) query_answer_count = kwargs.pop("query_answer_count", None) - answers = '{}|count-{}'.format(query_answer, query_answer_count) + answers = query_answer if not query_answer_count else '{}|count-{}'.format(query_answer, query_answer_count) query_caption = kwargs.pop("query_caption", None) query_caption_highlight = kwargs.pop("query_caption_highlight", None) - captions = '{}|highlight-{}'.format(query_caption, query_caption_highlight) + captions = query_caption if not query_caption_highlight else '{}|highlight-{}'.format(query_caption, query_caption_highlight) semantic_fields = kwargs.pop("semantic_fields", None) diff --git a/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py b/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py index 65cacbe50229..3526956adb55 100644 --- a/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py +++ b/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py @@ -254,11 +254,11 @@ async def search(self, search_text, **kwargs): query_answer = kwargs.pop("query_answer", None) query_answer_count = kwargs.pop("query_answer_count", None) - answers = '{}|count-{}'.format(query_answer, query_answer_count) + answers = query_answer if not query_answer_count else '{}|count-{}'.format(query_answer, query_answer_count) query_caption = kwargs.pop("query_caption", None) query_caption_highlight = kwargs.pop("query_caption_highlight", None) - captions = '{}|highlight-{}'.format(query_caption, query_caption_highlight) + captions = query_caption if not query_caption_highlight else '{}|highlight-{}'.format(query_caption, query_caption_highlight) semantic_fields = kwargs.pop("semantic_fields", None) From 65ff56c6eb55788d3e3923c9c30c83c2e61dd7e6 Mon Sep 17 00:00:00 2001 From: Travis Prescott Date: Wed, 8 Sep 2021 16:16:02 -0700 Subject: [PATCH 4/4] Code review comments and linter fixes. --- .../azure/search/documents/_search_client.py | 16 ++++++++++------ .../search/documents/aio/_search_client_async.py | 16 +++++++++++----- 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/sdk/search/azure-search-documents/azure/search/documents/_search_client.py b/sdk/search/azure-search-documents/azure/search/documents/_search_client.py index 0d15e4aac9a3..68a1e180bb42 100644 --- a/sdk/search/azure-search-documents/azure/search/documents/_search_client.py +++ b/sdk/search/azure-search-documents/azure/search/documents/_search_client.py @@ -152,7 +152,7 @@ def get_document(self, key, selected_fields=None, **kwargs): return cast(dict, result) @distributed_trace - def search(self, search_text, **kwargs): + def search(self, search_text, **kwargs): # pylint:disable=too-many-locals # type: (str, **Any) -> SearchItemPaged[dict] """Search the Azure search index for documents. @@ -207,14 +207,14 @@ def search(self, search_text, **kwargs): the query returns answers extracted from key passages in the highest ranked documents. Possible values include: "none", "extractive". :paramtype query_answer: str or ~azure.search.documents.models.Answers - :keyword int query_answer_count: This parameter is only valid if the query type is 'semantic'. - Configures the number of answers returned. Default count is 1. + :keyword int query_answer_count: This parameter is only valid if the query type is 'semantic' and + query answer is 'extractive'. Configures the number of answers returned. Default count is 1. :keyword query_caption: This parameter is only valid if the query type is 'semantic'. If set, the query returns captions extracted from key passages in the highest ranked documents. Defaults to 'None'. Possible values include: "none", "extractive". :paramtype query_caption: str or ~azure.search.documents.models.Captions :keyword bool query_caption_highlight: This parameter is only valid if the query type is 'semantic' when - query_caption is set to 'extractive'. Determines whether highlighting is enabled. + query caption is set to 'extractive'. Determines whether highlighting is enabled. Defaults to 'true'. :keyword list[str] semantic_fields: The list of field names used for semantic search. :keyword list[str] select: The list of fields to retrieve. If unspecified, all fields marked as retrievable @@ -277,11 +277,15 @@ def search(self, search_text, **kwargs): query_answer = kwargs.pop("query_answer", None) query_answer_count = kwargs.pop("query_answer_count", None) - answers = query_answer if not query_answer_count else '{}|count-{}'.format(query_answer, query_answer_count) + answers = query_answer if not query_answer_count else '{}|count-{}'.format( + query_answer, query_answer_count + ) query_caption = kwargs.pop("query_caption", None) query_caption_highlight = kwargs.pop("query_caption_highlight", None) - captions = query_caption if not query_caption_highlight else '{}|highlight-{}'.format(query_caption, query_caption_highlight) + captions = query_caption if not query_caption_highlight else '{}|highlight-{}'.format( + query_caption, query_caption_highlight + ) semantic_fields = kwargs.pop("semantic_fields", None) diff --git a/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py b/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py index 3526956adb55..e7f66ca59ae0 100644 --- a/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py +++ b/sdk/search/azure-search-documents/azure/search/documents/aio/_search_client_async.py @@ -128,8 +128,9 @@ async def get_document(self, key, selected_fields=None, **kwargs): ) return cast(dict, result) + @distributed_trace_async - async def search(self, search_text, **kwargs): + async def search(self, search_text, **kwargs): # pylint:disable=too-many-locals # type: (str, **Any) -> AsyncSearchItemPaged[dict] """Search the Azure search index for documents. @@ -184,14 +185,15 @@ async def search(self, search_text, **kwargs): the query returns answers extracted from key passages in the highest ranked documents. Possible values include: "none", "extractive". :paramtype query_answer: str or ~azure.search.documents.models.Answers - :keyword int query_answer_count: This parameter is only valid if the query type is 'semantic'. + :keyword int query_answer_count: This parameter is only valid if the query type is 'semantic' and + query answer is 'extractive'. Configures the number of answers returned. Default count is 1. :keyword query_caption: This parameter is only valid if the query type is 'semantic'. If set, the query returns captions extracted from key passages in the highest ranked documents. Defaults to 'None'. Possible values include: "none", "extractive". :paramtype query_caption: str or ~azure.search.documents.models.Captions :keyword bool query_caption_highlight: This parameter is only valid if the query type is 'semantic' when - query_caption is set to 'extractive'. Determines whether highlighting is enabled. + query caption is set to 'extractive'. Determines whether highlighting is enabled. Defaults to 'true'. :keyword list[str] semantic_fields: The list of field names used for semantic search. :keyword list[str] select: The list of fields to retrieve. If unspecified, all fields marked as retrievable @@ -254,11 +256,15 @@ async def search(self, search_text, **kwargs): query_answer = kwargs.pop("query_answer", None) query_answer_count = kwargs.pop("query_answer_count", None) - answers = query_answer if not query_answer_count else '{}|count-{}'.format(query_answer, query_answer_count) + answers = query_answer if not query_answer_count else '{}|count-{}'.format( + query_answer, query_answer_count + ) query_caption = kwargs.pop("query_caption", None) query_caption_highlight = kwargs.pop("query_caption_highlight", None) - captions = query_caption if not query_caption_highlight else '{}|highlight-{}'.format(query_caption, query_caption_highlight) + captions = query_caption if not query_caption_highlight else '{}|highlight-{}'.format( + query_caption, query_caption_highlight + ) semantic_fields = kwargs.pop("semantic_fields", None)