Azure Cognitive Search client library for Python — Azure SDK for Python 2.0.0 documentation

Azure Cognitive Search is a search-as-a-service cloud solution that gives developers APIs and tools for adding a rich search experience over private, heterogeneous content in web, mobile, and enterprise applications.

The Azure Cognitive Search service is well suited for the following

application scenarios:

• Consolidate varied content types into a single searchable index. To populate an index, you can push JSON documents that contain your content, or if your data is already in Azure, create an indexer to pull in data automatically.

• Attach skillsets to an indexer to create searchable content from images and large text documents. A skillset leverages AI from Cognitive Services for built-in OCR, entity recognition, key phrase extraction, language detection, text translation, and sentiment analysis. You can also add custom skills to integrate external processing of your content during data ingestion.

• In a search client application, implement query logic and user experiences similar to commercial web search engines.

Use the Azure.Search.Documents client library to:

• Submit queries for simple and advanced query forms that include fuzzy search, wildcard search, regular expressions.

• Implement filtered queries for faceted navigation, geospatial search, or to narrow results based on filter criteria.

• Create and manage search indexes.

• Upload and update documents in the search index.

• Create and manage indexers that pull data from Azure into an index.

• Create and manage skillsets that add AI enrichment to data ingestion.

• Create and manage analyzers for advanced text analysis or multi-lingual content.

• Optimize results through scoring profiles to factor in business logic or freshness.

Source code |Package (PyPI) |API reference documentation |Product documentation |Samples

Getting started¶

Install the package¶

Install the Azure Cognitive Search client library for Python with pip:

pip install azure-search-documents --pre

Authenticate the client¶

All requests to a search service need an api-key that was generated specifically for your service. The api-key is the sole mechanism for authenticating access to your search service endpoint.You can obtain your api-key from theAzure portal or via the Azure CLI:

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

There are two types of keys used to access your search service: admin(read-write) and query (read-only) keys. Restricting access and operations in client apps is essential to safeguarding the search assets on your service. Always use a query key rather than an admin key for any query originating from a client app.

Note: The example Azure CLI snippet above retrieves an admin key so it’s easier to get started exploring APIs, but it should be managed carefully.

We can use the api-key to create a new SearchClient.

import osfrom azure.core.credentials import AzureKeyCredentialfrom azure.search.documents import SearchClientindex_name = "nycjobs";# Get the service endpoint and API key from the environmentendpoint = os.environ["SEARCH_ENDPOINT"]key = os.environ["SEARCH_API_KEY"]# Create a clientcredential = AzureKeyCredential(key)client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

Send your first search request¶

To get running immediately, we’re going to connect to a well known sandbox Search service provided by Microsoft. This means you do not need an Azure subscription or Azure Cognitive Search service to try out this query.

from azure.core.credentials import AzureKeyCredentialfrom azure.search.documents import SearchClient# We'll connect to the Azure Cognitive Search public sandbox and send a# query to its "nycjobs" index built from a public dataset of available jobs# in New York.service_name = "azs-playground"index_name = "nycjobs"api_key = "252044BE3886FE4A8E3BAA4F595114BB"# Create a SearchClient to send queriesendpoint = "https://{}.".format(service_name)credential = AzureKeyCredential(api_key)client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)# Let's get the top 5 jobs related to Microsoftresults = client.search(search_text="Microsoft", top=5)for result in results: # Print out the title and job description print("{}\n{}\n)".format(result["business_title"], result["job_description"]))

Key concepts¶

An Azure Cognitive Search service contains one or more indexes that provide persistent storage of searchable data in the form of JSON documents. (If you’re brand new to search, you can make a very rough analogy between indexes and database tables.) The Azure.Search.Documents client library exposes operations on these resources through two main client types.

• SearchClient helps with:

• SearchIndexClient allows you to:

• SearchIndexerClient allows you to:

The ``Azure.Search.Documents`` client library (v1) is a brand new offering for Python developers who want to use search technology in their applications. There is an older, fully featured ``Microsoft.Azure.Search`` client library (v10) with many similar looking APIs, so please be careful to avoid confusion when exploring online resources.

Examples¶

The following examples all use a simple Hotel data setthat you can import into your own index from the Azure portal.These are just a few of the basics - please check out our Samples for much more.

Querying¶

Let’s start by importing our namespaces.

import osfrom azure.core.credentials import AzureKeyCredentialfrom azure.search.documents import SearchClient

We’ll then create a SearchClient to access our hotels search index.

index_name = "hotels"# Get the service endpoint and API key from the environmentendpoint = os.environ["SEARCH_ENDPOINT"]key = os.environ["SEARCH_API_KEY"]# Create a clientcredential = AzureKeyCredential(key)client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

Let’s search for a “luxury” hotel.

results = client.search(search_text="luxury")for result in results: print("{}: {})".format(result["hotelId"], result["hotelName"]))

Creating an index¶

You can use the SearchIndexClient to create a search index. Fields can be defined using convenient SimpleField, SearchableField, or ComplexFieldmodels. Indexes can also define suggesters, lexical analyzers, and more.

import osfrom azure.core.credentials import AzureKeyCredentialfrom azure.search.documents.indexes import SearchIndexClientfrom azure.search.documents.indexes.models import ( ComplexField, CorsOptions, SearchIndex, ScoringProfile, SearchFieldDataType, SimpleField, SearchableField)endpoint = os.environ["SEARCH_ENDPOINT"]key = os.environ["SEARCH_API_KEY"]# Create a service clientclient = SearchIndexClient(endpoint, AzureKeyCredential(key))# Create the indexname = "hotels"fields = [ SimpleField(name="hotelId", type=SearchFieldDataType.String, key=True), SimpleField(name="baseRate", type=SearchFieldDataType.Double), SearchableField(name="description", type=SearchFieldDataType.String), ComplexField(name="address", fields=[ SimpleField(name="streetAddress", type=SearchFieldDataType.String), SimpleField(name="city", type=SearchFieldDataType.String), ]) ]cors_options = CorsOptions(allowed_origins=["*"], max_age_in_seconds=60)scoring_profiles = []index = SearchIndex( name=name, fields=fields, scoring_profiles=scoring_profiles, cors_options=cors_options)result = client.create_index(index)

Adding documents to your index¶

You can Upload, Merge, MergeOrUpload, and Delete multiple documents from an index in a single batched request. There area few special rules for mergingto be aware of.

import osfrom azure.core.credentials import AzureKeyCredentialfrom azure.search.documents import SearchClientindex_name = "hotels"endpoint = os.environ["SEARCH_ENDPOINT"]key = os.environ["SEARCH_API_KEY"]DOCUMENT = { 'Category': 'Hotel', 'HotelId': '1000', 'Rating': 4.0, 'Rooms': [], 'HotelName': 'Azure Inn',}result = client.upload_documents(documents=[DOCUMENT])print("Upload of new document succeeded: {}".format(result[0].succeeded))

Retrieve a specific document from an index¶

In addition to querying for documents using keywords and optional filters, you can retrieve a specific document from your index if you already know the key. You could get the key from a query, for example, and want to show more information about it or navigate your customer to that document.

import osfrom azure.core.credentials import AzureKeyCredentialfrom azure.search.documents import SearchClientindex_name = "hotels"endpoint = os.environ["SEARCH_ENDPOINT"]key = os.environ["SEARCH_API_KEY"]client = SearchClient(endpoint, index_name, AzureKeyCredential(key))result = client.get_document(key="1")print("Details for hotel '1' are:")print(" Name: {}".format(result["HotelName"]))print(" Rating: {}".format(result["Rating"]))print(" Category: {}".format(result["Category"]))

Async APIs¶

This library includes a complete async API supported on Python 3.5+. To use it, you must first install an async transport, such as aiohttp. Seeazure-core documentationfor more information.

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.aio import SearchClient
client = SearchClient(endpoint, index_name, AzureKeyCredential(api_key))
async with client: results = await client.search(search_text="hotel") async for result in results: print("{}: {})".format(result["hotelId"], result["hotelName"]))
...
## Troubleshooting
### General
The Azure Cognitive Search client will raise exceptions defined in [Azure Core][azure_core].
### Logging
This library uses the standard [logging][python_logging] library for logging.
Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO
level.
Detailed DEBUG level logging, including request/response bodies and unredacted
headers, can be enabled on a client with the `logging_enable` keyword argument:
python
import sys
import logging
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
# This client will log detailed information about its HTTP sessions, at DEBUG level
client = SearchClient("<service endpoint>", "<index_name>", AzureKeyCredential("<api key>"), logging_enable=True)

Similarly, logging_enable can enable detailed logging for a single operation, even when it isn’t enabled for the client:

result = client.search(search_text="spa", logging_enable=True)

Next steps¶

Indices and tables¶

Developer Documentation