SearchClient Класс

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

Наследование

azure.search.documents._headers_mixin.HeadersMixin

SearchClient

Конструктор

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

Параметры

endpoint

str

Обязательно

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

index_name

str

Обязательно

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

credential

AzureKeyCredential или AsyncTokenCredential

Обязательно

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

api_version

str

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

audience

str

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

Примеры

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

   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents.aio 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. символ и не более 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".

async 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.aio import SearchClient

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

   async with search_client:
       results = await 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 Закройте сеанс.

async close() -> None

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

Нет

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

None

delete_documents

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

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

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

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

Параметры

documents

list[dict]

Обязательно

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

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

Список indexingResult

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

list[IndexingResult]

Примеры

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

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

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

get_document

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

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

Параметры

key

str

Обязательно

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

selected_fields

list[str]

Обязательно

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

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

Документ, соответствующий указанному ключу

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

dict

Примеры

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

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

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

   async with search_client:
       result = await 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.

async get_document_count(**kwargs: Any) -> int

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

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

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

int

index_documents

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

:Поднимает RequestEntityTooLargeError

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

Параметры

batch

IndexDocumentsBatch

Обязательно

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

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

Список indexingResult

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

list[IndexingResult]

merge_documents

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

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

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

Параметры

documents

list[dict]

Обязательно

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

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

Список indexingResult

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

list[IndexingResult]

Примеры

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

   result = await search_client.upload_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 с новым документом.

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

Параметры

documents

list[dict]

Обязательно

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

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

Список indexingResult

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

list[IndexingResult]

search

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

async 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) -> AsyncSearchItemPaged[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

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

query_answer_count

int

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

query_answer_threshold

float

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

query_caption

str или QueryCaptionType

Этот параметр действителен, только если тип запроса — "семантический". Если задано значение , запрос возвращает заголовки, извлеченные из ключевых фрагментов в документах с самым высоким рейтингом. Значение по умолчанию — 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".

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

Список документов (диктовок), соответствующих указанным условиям поиска.

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

AsyncSearchItemPaged[dict]

Примеры

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

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

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

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

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

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

suggest

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

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

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

async 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.aio import SearchClient

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

   async with search_client:
       results = await search_client.suggest(search_text="coffee", suggester_name="sg")

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

upload_documents

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

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

async 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 = await search_client.upload_documents(documents=[DOCUMENT])

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