SearchClient Класс

  • Ссылка

Клиент для взаимодействия с существующим индексом поиска Azure.

Наследование
azure.search.documents._headers_mixin.HeadersMixin
SearchClient

Конструктор

SearchClient(endpoint: str, index_name: str, credential: AzureKeyCredential | TokenCredential, **kwargs: Any)

Параметры

endpoint
str
Обязательно

Конечная точка URL-адреса службы поиска Azure

index_name
str
Обязательно

Имя индекса, к которому необходимо подключиться.

credential
AzureKeyCredential или TokenCredential
Обязательно

Учетные данные для авторизации запросов клиентов поиска

api_version
str

Версия API поиска, используемая для запросов.

audience
str

задает аудиторию, используемую для проверки подлинности в Azure Active Directory (AAD). Аудитория не учитывается при использовании общего ключа. Если аудитория не указана, предполагается аудитория общедоступного облака.

Примеры

Создание SearchClient с помощью ключа API.


   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents import SearchClient

   service_endpoint = os.environ["AZURE_SEARCH_SERVICE_ENDPOINT"]
   index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
   key = os.environ["AZURE_SEARCH_API_KEY"]

   search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

Методы

autocomplete

Получение результатов автозавершения поиска из индекса поиска Azure.

коллекция, которая является частью определения индекса. :ключевое слово режим: указывает режим автозаполнения. Значение по умолчанию — "oneTerm". Использование

"twoTerms" для получения черепицы и "oneTermWithContext", чтобы использовать текущий контекст при создании автоматически завершенных терминов. Возможные значения: "oneTerm", "twoTerms", "oneTermWithContext".
close

SearchClient Закройте сеанс.
delete_documents

Удаление документов из индекса поиска Azure

действие "удалить" удаляет указанный документ из индекса. Все поля, указанные в операции удаления, кроме ключевого, будут игнорироваться. Если вы хотите удалить отдельное поле из документа, используйте вместо него merge_documents и явно задайте для поля значение Нет.

Операции удаления являются идемпотентными. То есть, даже если ключ документа не существует в индексе, при попытке операции удаления с этим ключом возвращается код состояния 200.
get_document

Получение документа из индекса поиска Azure по его ключу.
get_document_count

Возвращает количество документов в индексе поиска Azure.
index_documents

Укажите операции с документами для выполнения в виде пакета.

:Поднимает RequestEntityTooLargeError
merge_documents

Слияние документов в с существующими документами в индексе поиска Azure.

при объединении обновляются указанные поля в существующем документе. Если документ не существует, объединение возвращает ошибку. Поля, указанные в запросе на объединение, заменяют собой существующие поля документа. Это также относится к коллекциям примитивных и сложных типов.
merge_or_upload_documents

Объедините документы в существующие документы в индексе поиска Azure или отправьте их, если они еще не существуют.

Это действие действует так, как merge_documents , если документ с заданным ключом уже существует в индексе. Если документ не существует, он ведет себя так, как upload_documents с новым документом.
search

Поиск документов в индексе поиска Azure.
suggest

Получите результаты предложений поиска из индекса поиска Azure.

character и не более 100 символов. :p aram str suggester_name: обязательный. Имя средства подбора, указанное в коллекции средств подбора, которая является частью определения индекса. :ключевое слово str filter: выражение OData, которое фильтрует документы, рассматриваемые для предложений. :ключевое слово bool use_fuzzy_matching: значение, указывающее, следует ли использовать нечеткое сопоставление для предложений.

базы данных. Значение по умолчанию — false. Если задано значение true, запрос найдет термины, даже если в тексте поиска есть заменяющий или отсутствующий символ. Хотя в некоторых сценариях это обеспечивает лучшие возможности, это снижает производительность, так как запросы нечетких предложений выполняются медленнее и потребляют больше ресурсов.
upload_documents

Отправка документов в индекс поиска Azure.

действие отправки аналогично upsert, где документ будет вставлен, если он новый, и обновлен или заменен, если он существует. Все поля заменяются в случае обновления.

autocomplete

Получение результатов автозавершения поиска из индекса поиска Azure.

коллекция, которая является частью определения индекса. :ключевое слово режим: указывает режим автозаполнения. Значение по умолчанию — "oneTerm". Использование

"twoTerms" для получения черепицы и "oneTermWithContext", чтобы использовать текущий контекст при создании автоматически завершенных терминов. Возможные значения: "oneTerm", "twoTerms", "oneTermWithContext".

autocomplete(search_text: str, suggester_name: str, *, mode: str | AutocompleteMode | None = None, use_fuzzy_matching: bool | None = None, highlight_post_tag: str | None = None, highlight_pre_tag: str | None = None, minimum_coverage: float | None = None, search_fields: List[str] | None = None, top: int | None = None, **kwargs) -> List[Dict]

Параметры

filter
str

Выражение OData, которое фильтрует документы, используемые для создания завершенных терминов для результата автозаполнения.

use_fuzzy_matching
bool

Значение , указывающее, следует ли использовать нечеткое сопоставление для запроса автозавершения. Значение по умолчанию — false. Если задано значение true, запрос будет находить термины, даже если в тексте поиска есть заменяющий или отсутствующий символ. Хотя это обеспечивает лучшие возможности в некоторых сценариях, это связано с затратами на производительность, так как нечеткие запросы автозаполнения выполняются медленнее и потребляют больше ресурсов.

highlight_post_tag
str

Строковый тег, добавляемый к выделению нажатия. Необходимо задать параметр highlightPreTag. Если этот параметр опущен, выделение нажатий отключено.

highlight_pre_tag
str

Строковый тег, который добавляется к выделению нажатия. Должен быть задан с параметром highlightPostTag. Если этот параметр опущен, выделение нажатий отключено.

minimum_coverage
float

Число от 0 до 100, указывающее процент индекса, который должен быть охвачен запросом автозаполнения, чтобы запрос сообщал об успешном выполнении. Этот параметр может быть полезен для обеспечения доступности поиска даже для служб с одним реплика. Значение по умолчанию — 80.

search_fields
list[str]

Список имен полей, которые следует учитывать при запросе автоматически заполненных терминов. Целевые поля должны быть включены в указанный средство подбора.

top
int

Количество автоматически заполненных терминов для извлечения. Это должно быть значение от 1 до 100. Значение по умолчанию — 5.

Возвращаемый тип

list[dict]

Примеры

Получение автозавершения.


   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents import SearchClient

   search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

   results = search_client.autocomplete(search_text="bo", suggester_name="sg")

   print("Autocomplete suggestions for 'bo'")
   for result in results:
       print("    Completion: {}".format(result["text"]))

close

SearchClient Закройте сеанс.

close() -> None

delete_documents

Удаление документов из индекса поиска Azure

действие "удалить" удаляет указанный документ из индекса. Все поля, указанные в операции удаления, кроме ключевого, будут игнорироваться. Если вы хотите удалить отдельное поле из документа, используйте вместо него merge_documents и явно задайте для поля значение Нет.

Операции удаления являются идемпотентными. То есть, даже если ключ документа не существует в индексе, при попытке операции удаления с этим ключом возвращается код состояния 200.

delete_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]

Параметры

documents
list[dict]
Обязательно

Список удаляемых документов.

Возвращаемое значение

Список indexingResult

Возвращаемый тип

list[IndexingResult]

Примеры

Удаление существующих документов в индекс


   result = search_client.delete_documents(documents=[{"hotelId": "1000"}])

   print("Delete new document succeeded: {}".format(result[0].succeeded))

get_document

Получение документа из индекса поиска Azure по его ключу.

get_document(key: str, selected_fields: List[str] | None = None, **kwargs: Any) -> Dict

Параметры

key
str
Обязательно

Значение первичного ключа для извлекаемого документа

selected_fields
list[str]
Обязательно

список разрешенных полей для включения в результаты

Возвращаемое значение

Документ, хранящийся в индексе поиска Azure

Возвращаемый тип

dict

Примеры

Получение определенного документа из индекса поиска.


   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents import SearchClient

   search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

   result = search_client.get_document(key="23")

   print("Details for hotel '23' are:")
   print("        Name: {}".format(result["hotelName"]))
   print("      Rating: {}".format(result["rating"]))
   print("    Category: {}".format(result["category"]))

get_document_count

Возвращает количество документов в индексе поиска Azure.

get_document_count(**kwargs: Any) -> int

Возвращаемое значение

Количество документов в индексе

Возвращаемый тип

int

index_documents

Укажите операции с документами для выполнения в виде пакета.

:Поднимает RequestEntityTooLargeError

index_documents(batch: IndexDocumentsBatch, **kwargs: Any) -> List[IndexingResult]

Параметры

batch
IndexDocumentsBatch
Обязательно

Пакет операций с документами для выполнения.

Возвращаемое значение

Список indexingResult

Возвращаемый тип

list[IndexingResult]

merge_documents

Слияние документов в с существующими документами в индексе поиска Azure.

при объединении обновляются указанные поля в существующем документе. Если документ не существует, объединение возвращает ошибку. Поля, указанные в запросе на объединение, заменяют собой существующие поля документа. Это также относится к коллекциям примитивных и сложных типов.

merge_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]

Параметры

documents
list[dict]
Обязательно

Список документов для слияния.

Возвращаемое значение

Список indexingResult

Возвращаемый тип

list[IndexingResult]

Примеры

Объединение полей с существующими документами в индекс


   result = search_client.merge_documents(documents=[{"hotelId": "1000", "rating": 4.5}])

   print("Merge into new document succeeded: {}".format(result[0].succeeded))

merge_or_upload_documents

Объедините документы в существующие документы в индексе поиска Azure или отправьте их, если они еще не существуют.

Это действие действует так, как merge_documents , если документ с заданным ключом уже существует в индексе. Если документ не существует, он ведет себя так, как upload_documents с новым документом.

merge_or_upload_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]

Параметры

documents
list[dict]
Обязательно

Список документов для слияния или отправки.

Возвращаемое значение

Список indexingResult

Возвращаемый тип

list[IndexingResult]

Поиск документов в индексе поиска Azure.

search(search_text: str | None = None, *, include_total_count: bool | None = None, facets: List[str] | None = None, filter: str | None = None, highlight_fields: str | None = None, highlight_post_tag: str | None = None, highlight_pre_tag: str | None = None, minimum_coverage: float | None = None, order_by: List[str] | None = None, query_type: str | QueryType | None = None, scoring_parameters: List[str] | None = None, scoring_profile: str | None = None, search_fields: List[str] | None = None, search_mode: str | SearchMode | None = None, query_answer: str | QueryAnswerType | None = None, query_answer_count: int | None = None, query_answer_threshold: float | None = None, query_caption: str | QueryCaptionType | None = None, query_caption_highlight_enabled: bool | None = None, semantic_configuration_name: str | None = None, select: List[str] | None = None, skip: int | None = None, top: int | None = None, scoring_statistics: str | ScoringStatistics | None = None, session_id: str | None = None, vector_queries: List[VectorQuery] | None = None, vector_filter_mode: str | VectorFilterMode | None = None, semantic_error_mode: str | SemanticErrorMode | None = None, semantic_max_wait_in_milliseconds: int | None = None, **kwargs: Any) -> SearchItemPaged[Dict]

Параметры

search_text
str
Обязательно

Выражение запроса полнотекстового поиска; Используйте "*" или опустите этот параметр, чтобы сопоставить все документы.

include_total_count
bool

Значение типа , указывающее, следует ли получить общее количество результатов. Значение по умолчанию — false. Установка этого значения в значение true может повлиять на производительность. Обратите внимание на то, что возвращается приблизительное количество результатов.

facets
list[str]

Список выражений аспектов, применяемых к поисковому запросу. Каждое выражение аспекта содержит имя поля, за которым при необходимости следует разделенный запятыми список пар "имя:значение".

filter
str

Выражение OData $filter, применяемого к поисковому запросу.

highlight_fields
str

Разделенный запятыми список имен полей, используемых для выделения нажатия. Для выделения попаданий можно использовать только доступные для поиска поля.

highlight_post_tag
str

Строковый тег, добавляемый к выделению нажатия. Необходимо задать параметр highlightPreTag. По умолчанию — .

highlight_pre_tag
str

Строковый тег, который добавляется к выделению нажатия. Должен быть задан с параметром highlightPostTag. По умолчанию — .

minimum_coverage
float

Число от 0 до 100, указывающее процент индекса, который должен быть охвачен поисковым запросом, чтобы запрос сообщал об успешном выполнении. Этот параметр может быть полезен для обеспечения доступности поиска даже для служб с одним реплика. Значение по умолчанию — 100.

order_by
list[str]

Список выражений OData $orderby, по которым сортируются результаты. Каждое выражение может быть именем поля или вызовом функций geo.distance() или search.score(). За каждым выражением может следовать asc для указания по возрастанию, и desc для указания по убыванию. По умолчанию результаты сортируются по возрастанию. При равенстве позиций порядок определяется по показателю совпадения документа. Если orderBy не указан, порядок сортировки по умолчанию убывания по оценке соответствия документа. Может быть не более 32 предложений $orderby.

query_type
str или QueryType

Значение типа , указывающее синтаксис поискового запроса. Значение по умолчанию — simple. Используйте "full", если в запросе используется синтаксис запроса Lucene. Возможные значения: simple, full, semantic.

scoring_parameters
list[str]

Список значений параметров, используемых в функциях оценки (например, referencePointParameter) с использованием формата name-values. Например, если профиль оценки определяет функцию с параметром mylocation, строка параметра будет иметь значение mylocation–122.2,44.8 (без кавычек).

scoring_profile
str

Имя профиля для оценки соответствующих показателей, для сопоставления документов с целью сортировки результатов.

search_fields
list[str]

Список имен полей, к которым следует область полнотекстового поиска. При использовании поля поиска (fieldName:searchExpression) в полном запросе Lucene имена полей каждого поля выражения поиска имеют приоритет над именами полей, перечисленными в этом параметре.

search_mode
str или SearchMode

Значение типа , указывающее, должны ли совпадать все условия поиска, чтобы подсчитать документ как совпадение. Возможные значения: "any", "all".

query_answer
str или QueryAnswerType

Этот параметр действителен только в том случае, если тип запроса имеет тип "semantic". Если задано значение , запрос возвращает ответы, извлеченные из ключевых фрагментов в документах с самым высоким рейтингом. Возможные значения: "none", "extractive".

query_answer_count
int

Этот параметр действителен, только если тип запроса — "семантический", а ответ запроса — "extractive". Настраивает количество возвращаемых ответов. Число по умолчанию — 1.

query_answer_threshold
float

Этот параметр действителен, только если тип запроса — "семантический", а ответ запроса — "extractive". Настраивает число порогового значения достоверности. Число по умолчанию — 0,7.

query_caption
str или QueryCaptionType

Этот параметр действителен только в том случае, если тип запроса имеет тип "semantic". Если задано значение , запрос возвращает заголовки, извлеченные из ключевых фрагментов в документах с самым высоким рейтингом. Значение по умолчанию — None. Возможные значения: "none", "extractive".

query_caption_highlight_enabled
bool

Этот параметр действителен, только если тип запроса является "семантический", если подпись запроса имеет значение "extractive". Определяет, включено ли выделение. Значение по умолчанию — true.

semantic_configuration_name
str

Имя семантической конфигурации, которая будет использоваться при обработке документов для запросов семантики типа.

select
list[str]

Список извлекаемых полей. Если этот параметр не указан, возвращаются все поля, помеченные в схеме как подлежащие извлечению.

skip
int

Количество пропускаемых результатов поиска. Значение не должно превышать 100 000. Если вам нужно сканировать документы в последовательности, но не удается использовать $skip из-за этого ограничения, рассмотрите возможность использования $orderby на полностью упорядоченном ключе и $filter с запросом диапазона.

top
int

Количество получаемых результатов поиска. Его можно использовать в сочетании с $skip для реализации разбиения результатов поиска на стороне клиента. Если результаты усечены из-за разбиения по страницам на стороне сервера, ответ будет содержать маркер продолжения, который можно использовать для выдачи другого запроса поиска для следующей страницы результатов.

scoring_statistics
str или ScoringStatistics

Значение типа , указывающее, нужно ли вычислить статистику оценки (например, частоту документов) глобально для более согласованной оценки или локально для меньшей задержки. Значение по умолчанию — local. Используйте "global" для глобальной статистической обработки статистики оценки перед оценкой. Использование глобальной статистики оценки может увеличить задержку поисковых запросов. Возможные значения: local, global.

session_id
str

Значение, используемое для создания прикрепленного сеанса, которое может помочь получить более согласованные результаты. Если используется один и тот же sessionId, будет предпринята попытка нацелиться на тот же реплика набор. Будьте осторожны, что многократное повторное использовать одни и те же значения sessionID может помешать балансировке нагрузки запросов между репликами и отрицательно повлиять на производительность службы поиска. Значение, используемое в качестве sessionId, не может начинаться с символа "_".

semantic_error_mode
str или SemanticErrorMode

Позволяет пользователю выбрать, должен ли семантический вызов завершиться сбоем (по умолчанию или текущее поведение) или возвратить частичные результаты. Известные значения: partial и fail.

semantic_max_wait_in_milliseconds
int

Позволяет пользователю задать верхнюю границу времени, необходимого для завершения обработки семантического обогащения до сбоя запроса.

vector_queries
list[VectorQuery]

Параметры запроса для векторных и гибридных поисковых запросов.

vector_filter_mode
str или VectorFilterMode

Определяет, применяются ли фильтры до или после выполнения векторного поиска. Значение по умолчанию — preFilter. Известные значения: "postFilter" и "preFilter".

Возвращаемый тип

SearchItemPaged[dict]

Примеры

Получение аспектов результатов поиска.


   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents import SearchClient

   search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

   results = search_client.search(search_text="WiFi", facets=["category,count:3", "parkingIncluded"])

   facets: Dict[str, List[str]] = cast(Dict[str, List[str]], results.get_facets())

   print("Catgory facet counts for hotels:")
   for facet in facets["category"]:
       print("    {}".format(facet))

suggest

Получите результаты предложений поиска из индекса поиска Azure.

character и не более 100 символов. :p aram str suggester_name: обязательный. Имя средства подбора, указанное в коллекции средств подбора, которая является частью определения индекса. :ключевое слово str filter: выражение OData, которое фильтрует документы, рассматриваемые для предложений. :ключевое слово bool use_fuzzy_matching: значение, указывающее, следует ли использовать нечеткое сопоставление для предложений.

базы данных. Значение по умолчанию — false. Если задано значение true, запрос найдет термины, даже если в тексте поиска есть заменяющий или отсутствующий символ. Хотя в некоторых сценариях это обеспечивает лучшие возможности, это снижает производительность, так как запросы нечетких предложений выполняются медленнее и потребляют больше ресурсов.

suggest(search_text: str, suggester_name: str, *, use_fuzzy_matching: bool | None = None, highlight_post_tag: str | None = None, highlight_pre_tag: str | None = None, minimum_coverage: float | None = None, order_by: List[str] | None = None, search_fields: List[str] | None = None, select: List[str] | None = None, top: int | None = None, **kwargs) -> List[Dict]

Параметры

highlight_post_tag
str

Строковый тег, добавляемый к выделенному нажатию. Должно быть задано значение highlightPreTag. Если этот параметр опущен, выделение подсказок отключается.

highlight_pre_tag
str

Строковый тег, который добавляется к выделению нажатия. Должен быть задан с параметром highlightPostTag. Если этот параметр опущен, выделение подсказок отключается.

minimum_coverage
float

Число от 0 до 100, указывающее процент индекса, который должен быть охвачен запросом предложений, чтобы запрос сообщал об успешном выполнении. Этот параметр может быть полезен для обеспечения доступности поиска даже для служб с одним реплика. Значение по умолчанию — 80.

order_by
list[str]

Список выражений OData $orderby, по которым сортируются результаты. Каждое выражение может быть именем поля или вызовом функций geo.distance() или search.score(). За каждым выражением может следовать asc для указания возрастания, или desc, чтобы обозначить по убыванию. По умолчанию результаты сортируются по возрастанию. При равенстве позиций порядок определяется по показателю совпадения документа. Если $orderby не указан, порядок сортировки по умолчанию убывания по оценке соответствия документа. Может быть не более 32 $orderby предложений.

search_fields
list[str]

Список имен полей для поиска указанного текста поиска. Целевые поля должны быть включены в указанный средство подбора.

select
list[str]

Список извлекаемых полей. Если значение не указано, в результаты будет включено только ключевое поле.

top
int

Число предложений, которое необходимо получить. Значение должно быть числом от 1 до 100. Значение по умолчанию — 5.

Возвращаемое значение

Список документов.

Возвращаемый тип

list[dict]

Примеры

Получите предложения поиска.


   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents import SearchClient

   search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

   results = search_client.suggest(search_text="coffee", suggester_name="sg")

   print("Search suggestions for 'coffee'")
   for result in results:
       hotel = search_client.get_document(key=result["hotelId"])
       print("    Text: {} for Hotel: {}".format(repr(result["text"]), hotel["hotelName"]))

upload_documents

Отправка документов в индекс поиска Azure.

действие отправки аналогично upsert, где документ будет вставлен, если он новый, и обновлен или заменен, если он существует. Все поля заменяются в случае обновления.

upload_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]

Параметры

documents
list[dict]
Обязательно

Список документов для отправки.

Возвращаемое значение

Список indexingResult

Возвращаемый тип

list[IndexingResult]

Примеры

Отправка новых документов в индекс


   DOCUMENT = {
       "category": "Hotel",
       "hotelId": "1000",
       "rating": 4.0,
       "rooms": [],
       "hotelName": "Azure Inn",
   }

   result = search_client.upload_documents(documents=[DOCUMENT])

   print("Upload of new document succeeded: {}".format(result[0].succeeded))