Update docs metadata
This commit is contained in:
azure-sdk
Родитель
e435989e54
Коммит
f003d7834e
|
|
@ -1,41 +1,40 @@
|
|||
---
|
||||
title: Azure AI Search client library for Java
|
||||
title: Azure Cognitive Search client library for Java
|
||||
keywords: Azure, java, SDK, API, azure-search-documents, cognitive-search
|
||||
ms.date: 12/07/2023
|
||||
ms.date: 02/22/2024
|
||||
ms.topic: reference
|
||||
ms.devlang: java
|
||||
ms.service: cognitive-search
|
||||
---
|
||||
# Azure AI Search client library for Java - version 11.6.1
|
||||
# Azure Cognitive Search client library for Java - version 11.6.2
|
||||
|
||||
This is the Java client library for [Azure AI Search](https://docs.microsoft.com/azure/search/) (formerly known as "Azure Cognitive Search"). Azure AI Search service is an AI-powered information retrieval platform that helps developers build rich search experiences and generative AI apps that combine large language models with enterprise data.
|
||||
|
||||
Azure AI Search is well suited for the following application scenarios:
|
||||
This is the Java client library for [Azure Cognitive Search](/azure/search/).
|
||||
Azure Cognitive Search service 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.
|
||||
|
||||
* 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 unstructured documents. A skillset leverages APIs from Azure AI 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 and chat-style apps.
|
||||
The Azure Cognitive Search service is well suited for the following application scenarios:
|
||||
|
||||
Use the Azure AI Search client library to:
|
||||
* 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.
|
||||
|
||||
* Submit queries using vector, keyword, and hybrid query forms.
|
||||
* Implement filtered queries for metadata, geospatial search, faceted navigation,
|
||||
or to narrow results based on filter criteria.
|
||||
* 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 Cognitive Search 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 semantic ranking and scoring profiles to factor in business logic or freshness.
|
||||
* Optimize results through scoring profiles to factor in business logic or freshness.
|
||||
|
||||
[Source code][source_code] | [Package (Maven)][package] | [API reference documentation][api_documentation]| [Product documentation][search_docs] | [Samples][samples]
|
||||
|
||||
|
|
@ -46,7 +45,7 @@ Use the Azure AI Search client library to:
|
|||
#### Include the BOM file
|
||||
|
||||
Please include the azure-sdk-bom to your project to take dependency on the General Availability (GA) version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number.
|
||||
To learn more about the BOM, see the [AZURE SDK BOM README](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.1/sdk/boms/azure-sdk-bom/README.md).
|
||||
To learn more about the BOM, see the [AZURE SDK BOM README](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.2/sdk/boms/azure-sdk-bom/README.md).
|
||||
|
||||
```xml
|
||||
<dependencyManagement>
|
||||
|
|
@ -83,7 +82,7 @@ add the direct dependency to your project as follows.
|
|||
<dependency>
|
||||
<groupId>com.azure</groupId>
|
||||
<artifactId>azure-search-documents</artifactId>
|
||||
<version>11.6.1</version>
|
||||
<version>11.6.2</version>
|
||||
</dependency>
|
||||
```
|
||||
[//]: # ({x-version-update-end})
|
||||
|
|
@ -92,7 +91,7 @@ add the direct dependency to your project as follows.
|
|||
|
||||
* [Java Development Kit (JDK) with version 8 or above][jdk]
|
||||
* [Azure subscription][azure_subscription]
|
||||
* [Azure AI Search service][search]
|
||||
* [Azure Cognitive Search service][search]
|
||||
* To create a new search service, you can use the [Azure portal][create_search_service_docs],
|
||||
[Azure PowerShell][create_search_service_ps], or the [Azure CLI][create_search_service_cli].
|
||||
Here's an example using the Azure CLI to create a free instance for getting started:
|
||||
|
|
@ -107,20 +106,18 @@ See [choosing a pricing tier](/azure/search/search-sku-tier) for more informatio
|
|||
|
||||
To interact with the Search service, you'll need to create an instance of the appropriate client class: `SearchClient`
|
||||
for searching indexed documents, `SearchIndexClient` for managing indexes, or `SearchIndexerClient` for crawling data
|
||||
sources and loading search documents into an index.
|
||||
|
||||
To instantiate a client object, you'll need an **endpoint** and **Azure roles** or an **API key**. You can refer to the documentation for more information on [supported authenticating approaches](https://learn.microsoft.com/azure/search/search-security-overview#authentication)
|
||||
sources and loading search documents into an index. To instantiate a client object, you'll need an **endpoint** and
|
||||
**API key**. You can refer to the documentation for more information on [supported authenticating approaches](https://learn.microsoft.com/azure/search/search-security-overview#authentication)
|
||||
with the Search service.
|
||||
|
||||
#### Get an API Key
|
||||
|
||||
An API key can be an easier approach to start with because it doesn't require pre-existing role assignments.
|
||||
|
||||
You can get the **endpoint** and an **API key** from the search service in the [Azure portal](https://portal.azure.com/). Please refer the [documentation](/azure/search/search-security-api-keys) for instructions on
|
||||
You can get the **endpoint** and an **API key** from the Search service in the [Azure Portal](https://portal.azure.com/).
|
||||
Please refer the [documentation](/azure/search/search-security-api-keys) for instructions on
|
||||
how to get an API key.
|
||||
|
||||
Alternatively, you can use the following [Azure CLI](https://learn.microsoft.com/cli/azure/) command to retrieve the
|
||||
API key from the search service:
|
||||
API key from the Search service:
|
||||
|
||||
```bash
|
||||
az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>
|
||||
|
|
@ -142,7 +139,7 @@ The SDK provides three clients.
|
|||
|
||||
#### Create a SearchIndexClient
|
||||
|
||||
To create a `SearchIndexClient/SearchIndexAsyncClient`, you will need the values of the Azure AI Search service
|
||||
To create a `SearchIndexClient/SearchIndexAsyncClient`, you will need the values of the Azure Cognitive Search service
|
||||
URL endpoint and admin key.
|
||||
|
||||
```java readme-sample-createIndexClient
|
||||
|
|
@ -163,7 +160,7 @@ SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
|
|||
|
||||
#### Create a SearchIndexerClient
|
||||
|
||||
To create a `SearchIndexerClient/SearchIndexerAsyncClient`, you will need the values of the Azure AI Search service
|
||||
To create a `SearchIndexerClient/SearchIndexerAsyncClient`, you will need the values of the Azure Cognitive Search service
|
||||
URL endpoint and admin key.
|
||||
|
||||
```java readme-sample-createIndexerClient
|
||||
|
|
@ -184,7 +181,7 @@ SearchIndexerAsyncClient searchIndexerAsyncClient = new SearchIndexerClientBuild
|
|||
|
||||
#### Create a SearchClient
|
||||
|
||||
Once you have the values of the Azure AI Search service URL endpoint and
|
||||
Once you have the values of the Azure Cognitive Search service URL endpoint and
|
||||
admin key, you can create the `SearchClient/SearchAsyncClient` with an existing index name:
|
||||
|
||||
```java readme-sample-createSearchClient
|
||||
|
|
@ -205,17 +202,17 @@ SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
|
|||
.buildAsyncClient();
|
||||
```
|
||||
|
||||
#### Create a client using Microsoft Entra ID authentication
|
||||
#### Create a client using Azure Active Directory authentication
|
||||
|
||||
You can also create a `SearchClient`, `SearchIndexClient`, or `SearchIndexerClient` using Microsoft Entra ID
|
||||
You can also create a `SearchClient`, `SearchIndexClient`, or `SearchIndexerClient` using Azure Active Directory (AAD)
|
||||
authentication. Your user or service principal must be assigned the "Search Index Data Reader" role.
|
||||
Using the [DefaultAzureCredential](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.1/sdk/identity/azure-identity/README.md#defaultazurecredential)
|
||||
Using the [DefaultAzureCredential](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.2/sdk/identity/azure-identity/README.md#defaultazurecredential)
|
||||
you 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 the [documentation](https://learn.microsoft.com/azure/search/search-security-rbac?tabs=config-svc-portal%2Croles-portal%2Ctest-portal%2Ccustom-role-portal%2Cdisable-keys-portal)
|
||||
for instructions on how to connect to Azure AI Search using Azure role-based access control (Azure RBAC).
|
||||
for instructions on how to connect to Azure Cognitive Search using Azure role-based access control (Azure RBAC).
|
||||
|
||||
Before you can use the `DefaultAzureCredential`, or any credential type from [Azure.Identity](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.1/sdk/identity/azure-identity/README.md),
|
||||
you'll first need to [install the Azure.Identity package](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.1/sdk/identity/azure-identity/README.md#include-the-package).
|
||||
Before you can use the `DefaultAzureCredential`, or any credential type from [Azure.Identity](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.2/sdk/identity/azure-identity/README.md),
|
||||
you'll first need to [install the Azure.Identity package](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.2/sdk/identity/azure-identity/README.md#include-the-package).
|
||||
|
||||
To use `DefaultAzureCredential` with a client ID and secret, you'll need to set the `AZURE_TENANT_ID`,
|
||||
`AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET` environment variables; alternatively, you can pass those values
|
||||
|
|
@ -247,21 +244,20 @@ SearchClient client = new SearchClientBuilder()
|
|||
|
||||
### Send your first search query
|
||||
|
||||
To get running with Azure AI Search first create an index following this [guide][search-get-started-portal].
|
||||
To get running with Azure Cognitive Search first create an index following this [guide][search-get-started-portal].
|
||||
With an index created you can use the following samples to begin using the SDK.
|
||||
|
||||
## Key concepts
|
||||
|
||||
An Azure AI Search service contains one or more indexes that provide persistent storage of searchable data in
|
||||
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 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:
|
||||
* Searching your indexed documents using [vector queries](https://learn.microsoft.com/azure/search/vector-search-how-to-query),
|
||||
[keyword queries](https://learn.microsoft.com/azure/search/search-query-create)
|
||||
and [hybrid queries](https://learn.microsoft.com/azure/search/hybrid-search-how-to-query)
|
||||
* [Vector query filters](https://learn.microsoft.com/azure/search/vector-search-filters) and [Text query filters](https://learn.microsoft.com/azure/search/search-filters)
|
||||
* [Semantic ranking](https://learn.microsoft.com/azure/search/semantic-how-to-query-request) and [scoring profiles](https://learn.microsoft.com/azure/search/index-add-scoring-profiles) for boosting relevance
|
||||
* [Searching](/azure/search/search-lucene-query-architecture)
|
||||
your indexed documents using
|
||||
[rich queries](/azure/search/search-query-overview)
|
||||
and [powerful data shaping](/azure/search/search-filters)
|
||||
* [Autocompleting](/rest/api/searchservice/autocomplete)
|
||||
partially typed search terms based on documents in the index
|
||||
* [Suggesting](/rest/api/searchservice/suggestions)
|
||||
|
|
@ -278,27 +274,34 @@ tables.)_ The `azure-search-documents` client library exposes operations on thes
|
|||
* [Start indexers to automatically crawl data sources](/rest/api/searchservice/indexer-operations)
|
||||
* [Define AI powered Skillsets to transform and enrich your data](/rest/api/searchservice/skillset-operations)
|
||||
|
||||
Azure AI Search provides two powerful features:
|
||||
Azure Cognitive Search provides two powerful features:
|
||||
|
||||
### Semantic ranking
|
||||
### Semantic Search
|
||||
|
||||
Semantic ranking enhances the quality of search results for text-based queries. By enabling semantic ranking on your search service, you can improve the relevance of search results in two ways:
|
||||
Semantic search enhances 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.
|
||||
- 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 ranking, you can refer to the [documentation](https://learn.microsoft.com/azure/search/vector-search-overview).
|
||||
To learn more about Semantic Search, you can refer to the [documentation](https://learn.microsoft.com/azure/search/vector-search-overview).
|
||||
|
||||
### Vector search
|
||||
### Vector Search
|
||||
|
||||
Vector search is 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 uses algorithms for similarity and concept search. It represents documents and queries as vectors in a high-dimensional space called an embedding. By searching on vector representations of content, a vector query can find relevant matches, even if the exact terms of the query are not present in the index. Moreover, vector search can be applied to various types of content, including images and videos and translated text, not just same-language text.
|
||||
Vector Search is 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 the [sample](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.1/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/VectorSearchExample.java).
|
||||
To learn how to index vector fields and perform vector search, you can refer to the [sample](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.2/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/VectorSearchExample.java).
|
||||
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
|
||||
Additionally, for more comprehensive information about Vector Search, including its concepts and usage, you can refer
|
||||
to the [documentation](https://learn.microsoft.com/azure/search/vector-search-overview). The documentation provides
|
||||
in-depth explanations and guidance on leveraging the power of vector search in Azure AI Search.
|
||||
in-depth explanations and guidance on leveraging the power of Vector Search in Azure Cognitive Search.
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -522,12 +525,12 @@ SearchClient searchClient = new SearchClientBuilder()
|
|||
|
||||
## Troubleshooting
|
||||
|
||||
See our [troubleshooting guide](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.1/sdk/search/azure-search-documents/TROUBLESHOOTING.md)
|
||||
See our [troubleshooting guide](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.2/sdk/search/azure-search-documents/TROUBLESHOOTING.md)
|
||||
for details on how to diagnose various failure scenarios.
|
||||
|
||||
### General
|
||||
|
||||
When you interact with Azure AI Search using this Java client library, errors returned by the service correspond
|
||||
When you interact with Azure Cognitive Search using this Java client library, errors returned by the service correspond
|
||||
to the same HTTP status codes returned for [REST API][rest_api] requests. For example, the service will return a `404`
|
||||
error if you try to retrieve a document that doesn't exist in your index.
|
||||
|
||||
|
|
@ -565,7 +568,8 @@ provides more information on configuring or changing the HTTP client.
|
|||
## Next steps
|
||||
|
||||
* Samples are explained in detail [here][samples_readme].
|
||||
* Read more about the [Azure AI Search service](/azure/search/search-what-is-azure-search)
|
||||
* Watch a [demo or deep dive video](https://azure.microsoft.com/resources/videos/index/?services=search)
|
||||
* Read more about the [Azure Cognitive Search service](/azure/search/search-what-is-azure-search)
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
@ -588,20 +592,20 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m
|
|||
[azure_subscription]: https://azure.microsoft.com/free/java
|
||||
[maven]: https://maven.apache.org/
|
||||
[package]: https://central.sonatype.com/artifact/com.azure/azure-search-documents
|
||||
[samples]: https://github.com/Azure/azure-sdk-for-java/tree/azure-search-documents_11.6.1/sdk/search/azure-search-documents/src/samples/
|
||||
[samples_readme]: https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.1/sdk/search/azure-search-documents/src/samples/README.md
|
||||
[source_code]: https://github.com/Azure/azure-sdk-for-java/tree/azure-search-documents_11.6.1/sdk/search/azure-search-documents/src
|
||||
[samples]: https://github.com/Azure/azure-sdk-for-java/tree/azure-search-documents_11.6.2/sdk/search/azure-search-documents/src/samples/
|
||||
[samples_readme]: https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.2/sdk/search/azure-search-documents/src/samples/README.md
|
||||
[source_code]: https://github.com/Azure/azure-sdk-for-java/tree/azure-search-documents_11.6.2/sdk/search/azure-search-documents/src
|
||||
[logging]: https://github.com/Azure/azure-sdk-for-java/wiki/Logging-with-Azure-SDK
|
||||
[cla]: https://cla.microsoft.com
|
||||
[coc]: https://opensource.microsoft.com/codeofconduct/
|
||||
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
|
||||
[coc_contact]: mailto:opencode@microsoft.com
|
||||
[add_headers_from_context_policy]: https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.1/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/AddHeadersFromContextPolicy.java
|
||||
[add_headers_from_context_policy]: https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.2/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/AddHeadersFromContextPolicy.java
|
||||
[rest_api]: /rest/api/searchservice/http-status-codes
|
||||
[create_search_service_docs]: /azure/search/search-create-service-portal
|
||||
[create_search_service_ps]: /azure/search/search-manage-powershell#create-or-delete-a-service
|
||||
[create_search_service_cli]: /cli/azure/search/service?view=azure-cli-latest#az-search-service-create
|
||||
[HttpResponseException]: https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.1/sdk/core/azure-core/src/main/java/com/azure/core/exception/HttpResponseException.java
|
||||
[HttpResponseException]: https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.2/sdk/core/azure-core/src/main/java/com/azure/core/exception/HttpResponseException.java
|
||||
[status_codes]: /rest/api/searchservice/http-status-codes
|
||||
[search-get-started-portal]: /azure/search/search-get-started-portal
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"Name": "azure-search-documents",
|
||||
"Version": "11.6.1",
|
||||
"Version": "11.6.2",
|
||||
"DevVersion": null,
|
||||
"DirectoryPath": "sdk/search/azure-search-documents",
|
||||
"ServiceDirectory": "search",
|
||||
|
|
@ -10,5 +10,5 @@
|
|||
"SdkType": "client",
|
||||
"IsNewSdk": true,
|
||||
"ArtifactName": "azure-search-documents",
|
||||
"ReleaseStatus": "2023-12-06"
|
||||
"ReleaseStatus": "2024-02-22"
|
||||
}
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче