Package: azure-search-documents
Azure Cognitive Search client library for PythonAzure Cognitive Searchis 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)|Package (Conda)|API reference documentation|Product documentation|SamplesGetting startedInstall the packageInstall the Azure Cognitive Search client library for Python withpip:pipinstallazure-search-documentsPrerequisitesPython 3.7 or later is required to use this package.You need anAzure subscriptionand anAzure Cognitive Search serviceto use this package.To create a new search service, you can use theAzure portal,Azure PowerShell, or theAzure CLI.azsearchservicecreate--name<mysearch>--resource-group<mysearch-rg>--skufree--locationwestusSeechoosing a pricing tierfor more information about available options.Authenticate the clientTo interact with the Search service, you'll need to create an instance of the appropriate client class:SearchClientfor searching indexed documents,SearchIndexClientfor managing indexes, orSearchIndexerClientfor crawling data sources and loading search documents into an index. To instantiate a client object, you'll need anendpointand anAPI key. You can refer to the documentation for more information onsupported authenticating approacheswith the Search service.Get an API KeyYou can get theendpointand anAPI keyfrom the Search service in theAzure Portal. Please refer thedocumentationfor instructions on how to get an API key.Alternatively, you can use the followingAzure CLIcommand to retrieve the API key from the Search service:azsearchadmin-keyshow--service-name<mysearch>--resource-group<mysearch-rg>There are two types of keys used to access your search service:admin(read-write)andquery(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.Create a SearchClientTo instantiate theSearchClient, you'll need theendpoint,API keyandindex name:fromazure.core.credentialsimportAzureKeyCredentialfromazure.search.documentsimportSearchClientservice_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))Create a client using Azure Active Directory authenticationYou can also create aSearchClient,SearchIndexClient, orSearchIndexerClientusing Azure Active Directory (AAD) authentication. Your user or service principal must be assigned the "Search Index Data Reader" role.
Using theDefaultAzureCredentialyou can authenticate a service using Managed Identity or a service principal, authenticate as a developer working on an application, and more all without changing code. Please refer thedocumentationfor instructions on how to connect to Azure Cognitive Search using Azure role-based access control (Azure RBAC).Before you can use theDefaultAzureCredential, or any credential type fromAzure.Identity, you'll first need toinstall the Azure.Identity package.To useDefaultAzureCredentialwith a client ID and secret, you'll need to set theAZURE_TENANT_ID,AZURE_CLIENT_ID, andAZURE_CLIENT_SECRETenvironment variables; alternatively, you can pass those values
to theClientSecretCredentialalso in Azure.Identity.Make sure you use the right namespace forDefaultAzureCredentialat the top of your source file:fromazure.identityimportDefaultAzureCredentialfromazure.search.documentsimportSearchClientservice_endpoint=os.getenv("AZURE_SEARCH_SERVICE_ENDPOINT")index_name=os.getenv("AZURE_SEARCH_INDEX_NAME")credential=DefaultAzureCredential()search_client=SearchClient(service_endpoint,index_name,credential)Key conceptsAn 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.SearchClienthelps with:Searchingyour indexed documents usingrich queriesandpowerful data shapingAutocompletingpartially typed search terms based on documents in the indexSuggestingthe most likely matching text in documents as a user typesAdding, Updating or Deleting Documentsdocuments from an indexSearchIndexClientallows you to:Create, delete, update, or configure a search indexDeclare custom synonym maps to expand or rewrite queriesMost of theSearchServiceClientfunctionality is not yet available in our current previewSearchIndexerClientallows you to:Start indexers to automatically crawl data sourcesDefine AI powered Skillsets to transform and enrich your dataAzure Cognitive Search provides two powerful features:Semantic SearchandVector Search.Semantic Searchenhances the quality of search results for text-based queries. By enabling Semantic Search on your search service, you can improve the relevance of search results in two ways:It applies secondary ranking to the initial result set, promoting the most semantically relevant results to the top.It extracts and returns captions and answers in the response, which can be displayed on a search page to enhance the user's search experience.To learn more about Semantic Search, you can refer to thedocumentation.Vector Searchis an information retrieval technique that overcomes the limitations of traditional keyword-based search. Instead of relying solely on lexical analysis and matching individual query terms, Vector Search utilizes machine learning models to capture the contextual meaning of words and phrases. It represents documents and queries as vectors in a high-dimensional space called an embedding. By understanding the intent behind the query, Vector Search can deliver more relevant results that align with the user's requirements, even if the exact terms are not present in the document. Moreover, Vector Search can be applied to various types of content, including images and videos, not just text.To learn how to index vector fields and perform vector search, you can refer to thesample. This sample provides detailed guidance on indexing vector fields and demonstrates how to perform vector search.Additionally, for more comprehensive information about Vector Search, including its concepts and usage, you can refer to thedocumentation. The documentation provides in-depth explanations and guidance on leveraging the power of Vector Search in Azure Cognitive Search.TheAzure.Search.Documentsclient library (v1) is a brand new offering for
Python developers who want to use search technology in their applications.  There
is an older, fully featuredMicrosoft.Azure.Searchclient library (v10) with
many similar looking APIs, so please be careful to avoid confusion when
exploring online resources.ExamplesThe following examples all use a simpleHotel data setthat you canimport into your own index from the Azure portal.These are just a few of the basics - pleasecheck out our Samplesfor
much more.QueryingCreating an indexAdding documents to your indexRetrieving a specific document from your indexAsync APIsQueryingLet's start by importing our namespaces.importosfromazure.core.credentialsimportAzureKeyCredentialfromazure.search.documentsimportSearchClientWe'll then create aSearchClientto 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")forresultinresults:print("{}:{})".format(result["hotelId"],result["hotelName"]))Creating an indexYou can use theSearchIndexClientto create a search index. Fields can be
defined using convenientSimpleField,SearchableField, orComplexFieldmodels. Indexes can also define suggesters, lexical analyzers, and more.client=SearchIndexClient(service_endpoint,AzureKeyCredential(key))name="hotels"fields=[SimpleField(name="hotelId",type=SearchFieldDataType.String,key=True),SimpleField(name="baseRate",type=SearchFieldDataType.Double),SearchableField(name="description",type=SearchFieldDataType.String,collection=True),ComplexField(name="address",fields=[SimpleField(name="streetAddress",type=SearchFieldDataType.String),SimpleField(name="city",type=SearchFieldDataType.String),],collection=True,),]cors_options=CorsOptions(allowed_origins=["*"],max_age_in_seconds=60)scoring_profiles:List[ScoringProfile]=[]index=SearchIndex(name=name,fields=fields,scoring_profiles=scoring_profiles,cors_options=cors_options)result=client.create_index(index)Adding documents to your indexYou canUpload,Merge,MergeOrUpload, andDeletemultiple documents from
an index in a single batched request.  There area few special rules for mergingto be aware of.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))Authenticate in a National CloudTo authenticate in aNational Cloud, you will need to make the following additions to your client configuration:Set theAuthorityHostin the credential options or via theAZURE_AUTHORITY_HOSTenvironment variableSet theaudienceinSearchClient,SearchIndexClient, orSearchIndexerClient# Create a SearchClient that will authenticate through AAD in the China national cloud.importosfromazure.identityimportDefaultAzureCredential,AzureAuthorityHostsfromazure.search.documentsimportSearchClientindex_name="hotels"endpoint=os.environ["SEARCH_ENDPOINT"]key=os.environ["SEARCH_API_KEY"]credential=DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_CHINA)search_client=SearchClient(endpoint,index_name,credential=credential,audience="https://search.azure.cn")Retrieving a specific document from your indexIn 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.fromazure.core.credentialsimportAzureKeyCredentialfromazure.search.documentsimportSearchClientsearch_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"]))Async APIsThis library includes a complete async API. To use it, you must
first install an async transport, such asaiohttp.
Seeazure-core documentationfor more information.fromazure.core.credentialsimportAzureKeyCredentialfromazure.search.documents.aioimportSearchClientsearch_client=SearchClient(service_endpoint,index_name,AzureKeyCredential(key))asyncwithsearch_client:results=awaitsearch_client.search(search_text="spa")print("Hotels containing 'spa' in the name (or other fields):")asyncforresultinresults:print("    Name:{}(rating{})".format(result["hotelName"],result["rating"]))TroubleshootingGeneralThe Azure Cognitive Search client will raise exceptions defined inAzure Core.LoggingThis library uses the standardlogginglibrary 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 thelogging_enablekeyword argument:importsysimportloggingfromazure.core.credentialsimportAzureKeyCredentialfromazure.search.documentsimportSearchClient# Create a logger for the 'azure' SDKlogger=logging.getLogger('azure')logger.setLevel(logging.DEBUG)# Configure a console outputhandler=logging.StreamHandler(stream=sys.stdout)logger.addHandler(handler)# This client will log detailed information about its HTTP sessions, at DEBUG levelclient=SearchClient("<service endpoint>","<index_name>",AzureKeyCredential("<api key>"),logging_enable=True)Similarly,logging_enablecan 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 stepsGo further with Azure.Search.Documents and ourhttps://github.com/Azure/azure-sdk-for-python/blob/master/sdk/search/azure-search-documents/samplesWatch ademo or deep dive videoRead more about theAzure Cognitive Search serviceContributingSee ourSearch CONTRIBUTING.mdfor details on building,
testing, and contributing to this library.This project welcomes contributions and suggestions.  Most contributions require
you to agree to a Contributor License Agreement (CLA) declaring that you have
the right to, and actually do, grant us the rights to use your contribution. For
details, visitcla.microsoft.com.This project has adopted theMicrosoft Open Source Code of Conduct.
For more information see theCode of Conduct FAQor contactopencode@microsoft.comwith any
additional questions or comments.Related projectsMicrosoft Azure SDK for Python