Skip to content

Commit

Permalink
Update readme and changelog for preview 3 release (#10672)
Browse files Browse the repository at this point in the history
  • Loading branch information
@sima-zhu
sima-zhu authored May 1, 2020
1 parent 9ef0e46 commit 3872410
Show file tree
Hide file tree
Showing 3 changed files with 40 additions and 35 deletions.
7 changes: 5 additions & 2 deletions sdk/search/azure-search-documents/CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
# Release History

## 1.0.0-beta.3 (Unreleased)
- Change `createOrUpdate*` and `delete*` APIs in `SearchServiceClient` to use boolean `onlyIfUnchanged` instead of `MatchConditioans`.
## 1.0.0-beta.3 (2020-05-05)
- Replaced `isRetrievable` API with `isHidden`, parameter name changed from `retrievable` to `hidden`.
- Changed Azure Search service version from `2019-05-06` to `2019-05-06-Preview`
- Changed `createOrUpdate` and `delete` APIs in `SearchServiceClient` to use boolean `onlyIfUnchanged` instead of `MatchConditions`.
- Updated reactor core to `3.3.5.RELEASE`.

## 1.0.0-beta.2 (2020-04-06)

Expand Down
46 changes: 24 additions & 22 deletions sdk/search/azure-search-documents/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,14 +23,14 @@ create and manage indexes, load data, implement search features, execute queries

### Prerequisites

- Java Development Kit (JDK) with version 8 or above
- [Java Development Kit (JDK) with version 8 or above][jdk]
- [Azure subscription][azure_subscription]
- [Cognitive Search service][search]
- [Azure Cognitive Search service][search]

### Authenticate the client

In order to interact with the Cognitive Search service you'll need to create an instance of the Search Client class.
To make this possible you will need an [api-key of the Cognitive Search service](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys).
In order to interact with the Azure Cognitive Search service you'll need to create an instance of the Search Client class.
To make this possible you will need an [api-key of the Azure Cognitive Search service](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys).

The SDK provides two clients.

Expand All @@ -39,12 +39,12 @@ The SDK provides two clients.

#### Create a SearchServiceClient

Once you have the values of the Cognitive Search Service [URL endpoint](https://docs.microsoft.com/en-us/azure/search/search-create-service-portal#get-a-key-and-url-endpoint)
and [admin key](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys) you can create the Search Service client:
Once you have the values of the Azure Cognitive Search service [URL endpoint](https://docs.microsoft.com/en-us/azure/search/search-create-service-portal#get-a-key-and-url-endpoint)
and [admin key](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys) you can create the SearchServiceClient:

<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L40-L43 -->
```Java
SearchServiceClient client = new SearchServiceClientBuilder()
SearchServiceClient searchServiceClient = new SearchServiceClientBuilder()
.endpoint(endpoint)
.credential(new AzureKeyCredential(adminKey))
.buildClient();
Expand All @@ -54,22 +54,22 @@ or

<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L47-L50 -->
```Java
SearchServiceAsyncClient client = new SearchServiceClientBuilder()
SearchServiceAsyncClient searchServiceAsyncClient = new SearchServiceClientBuilder()
.endpoint(endpoint)
.credential(new AzureKeyCredential(adminKey))
.buildAsyncClient();
```

#### Create a SearchIndexClient

To create a SearchIndexClient, you will need an existing index name as well as the values of the Cognitive Search Service
To create a SearchIndexClient, you will need an existing index name as well as the values of the Azure Cognitive Search service
[URL endpoint](https://docs.microsoft.com/en-us/azure/search/search-create-service-portal#get-a-key-and-url-endpoint) and
[query key](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys).
Note that you will need an admin key to index documents (query keys only work for queries).

<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L54-L58 -->
```Java
SearchIndexClient client = new SearchIndexClientBuilder()
SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
.endpoint(endpoint)
.credential(new AzureKeyCredential(apiKey))
.indexName(indexName)
Expand All @@ -80,7 +80,7 @@ or

<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L62-L66 -->
```Java
SearchIndexAsyncClient client = new SearchIndexClientBuilder()
SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
.endpoint(endpoint)
.credential(new AzureKeyCredential(apiKey))
.indexName(indexName)
Expand All @@ -89,7 +89,7 @@ SearchIndexAsyncClient client = new SearchIndexClientBuilder()

## Key concepts

Azure Cognitive Search has the concepts of search services and indexes and documents, where a search service contains
Azure Cognitive Search service has the concepts of search services and indexes and documents, where a search service contains
one or more indexes that provides persistent storage of searchable data, and data is loaded in the form of JSON documents.
Data can be pushed to an index from an external data source, but if you use an indexer, it's possible to crawl a data
source to extract and load data into an index.
Expand All @@ -106,7 +106,7 @@ There are several types of operations that can be executed against the service:

### Create an index

Create Index using `SearchIndexClient` create in above [section](Create-a-SearchIndexClient)
Create Index using `searchIndexClient` instantiated in [Create a SearchServiceClient](#create-a-searchserviceclient)

<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L96-L107 -->
```java
Expand All @@ -121,11 +121,11 @@ Index newIndex = new Index()
.setName("Cuisine")
.setType(DataType.EDM_STRING)));
// Create index.
searchClient.createIndex(newIndex);
searchServiceClient.createIndex(newIndex);
```
### Upload a Document

Upload hotel document to Search Index.
Upload hotel document to Search Index using `searchIndexClient` instantiated [Create a SearchIndexClient](#create-a-searchindexclient)

<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L111-L116 -->
```java
Expand All @@ -134,17 +134,17 @@ hotels.add(new Hotel().setHotelId("100"));
hotels.add(new Hotel().setHotelId("200"));
hotels.add(new Hotel().setHotelId("300"));
// Upload hotel.
indexClient.uploadDocuments(hotels);
searchIndexClient.uploadDocuments(hotels);
```

### Search on hotel name

Search hotel using keyword.
Search hotel using keyword using `searchIndexClient` instantiated in [Create a SearchIndexClient](#create-a-searchindexclient)

<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L120-L130 -->
```java
// Perform a text-based search
for (SearchResult result : indexClient.search("luxury hotel",
for (SearchResult result : searchIndexClient.search("luxury hotel",
new SearchOptions(), new RequestOptions(), Context.NONE)) {

// Each result is a dynamic Map
Expand All @@ -156,6 +156,8 @@ for (SearchResult result : indexClient.search("luxury hotel",
}
```

- Samples are explained in detail [here][samples_readme].

## Troubleshooting

### General
Expand Down Expand Up @@ -195,10 +197,10 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m
or contact [[email protected]][coc_contact] with any additional questions or comments.

<!-- LINKS -->

[jdk]: https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable
[api_documentation]: https://aka.ms/java-docs
[search]: https://azure.microsoft.com/en-us/services/search/
[search_docs]: https://docs.microsoft.com/en-us/azure/search/
[search]: https://azure.microsoft.com/services/search/
[search_docs]: https://docs.microsoft.com/azure/search/
[azure_subscription]: https://azure.microsoft.com/free
[maven]: https://maven.apache.org/
[package]: https://search.maven.org/artifact/com.azure/azure-search-documents
Expand All @@ -211,6 +213,6 @@ or contact [[email protected]][coc_contact] with any additional questions o
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
[coc_contact]: mailto:[email protected]
[add_headers_from_context_policy]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/AddHeadersFromContextPolicy.java
[rest_api]: https://docs.microsoft.com/en-us/rest/api/searchservice/http-status-codes
[rest_api]: https://docs.microsoft.com/rest/api/searchservice/http-status-codes

![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fsearch%2Fazure-search-documents%2FREADME.png)
22 changes: 11 additions & 11 deletions ...rch/azure-search-documents/src/samples/java/com/azure/search/documents/ReadmeSamples.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,33 +33,33 @@ public class ReadmeSamples {
private String adminKey = "admin key";
private String apiKey = "api key";
private String indexName = "index name";
private SearchServiceClient searchClient = new SearchServiceClientBuilder().buildClient();
private SearchIndexClient indexClient = new SearchIndexClientBuilder().buildClient();
private SearchServiceClient searchServiceClient = new SearchServiceClientBuilder().buildClient();
private SearchIndexClient searchIndexClient = new SearchIndexClientBuilder().buildClient();

public void createSearchClient() {
SearchServiceClient client = new SearchServiceClientBuilder()
SearchServiceClient searchServiceClient = new SearchServiceClientBuilder()
.endpoint(endpoint)
.credential(new AzureKeyCredential(adminKey))
.buildClient();
}

public void createAsyncSearchClient() {
SearchServiceAsyncClient client = new SearchServiceClientBuilder()
SearchServiceAsyncClient searchServiceAsyncClient = new SearchServiceClientBuilder()
.endpoint(endpoint)
.credential(new AzureKeyCredential(adminKey))
.buildAsyncClient();
}

public void createIndexClient() {
SearchIndexClient client = new SearchIndexClientBuilder()
SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
.endpoint(endpoint)
.credential(new AzureKeyCredential(apiKey))
.indexName(indexName)
.buildClient();
}

public void createAsyncIndexClient() {
SearchIndexAsyncClient client = new SearchIndexClientBuilder()
SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
.endpoint(endpoint)
.credential(new AzureKeyCredential(apiKey))
.indexName(indexName)
Expand All @@ -73,7 +73,7 @@ public void customHeaders() {
headers.put("my-header3", "my-header3-value");
// Call API by passing headers in Context.
Index index = new Index().setName(indexName);
searchClient.createIndexWithResponse(
searchServiceClient.createIndexWithResponse(
index,
new RequestOptions(),
new Context(AddHeadersFromContextPolicy.AZURE_REQUEST_HTTP_HEADERS_KEY, headers));
Expand All @@ -82,7 +82,7 @@ public void customHeaders() {

public void handleErrorsWithSyncClient() {
try {
Iterable<SearchResult> results = indexClient.search("hotel");
Iterable<SearchResult> results = searchIndexClient.search("hotel");
} catch (HttpResponseException ex) {
// The exception contains the HTTP status code and the detailed message
// returned from the search service
Expand All @@ -104,7 +104,7 @@ public void createIndexWithSyncClient() {
.setName("Cuisine")
.setType(DataType.EDM_STRING)));
// Create index.
searchClient.createIndex(newIndex);
searchServiceClient.createIndex(newIndex);
}

public void uploadDocumentWithSyncClient() {
Expand All @@ -113,12 +113,12 @@ public void uploadDocumentWithSyncClient() {
hotels.add(new Hotel().setHotelId("200"));
hotels.add(new Hotel().setHotelId("300"));
// Upload hotel.
indexClient.uploadDocuments(hotels);
searchIndexClient.uploadDocuments(hotels);
}

public void searchTextWithSyncClient() {
// Perform a text-based search
for (SearchResult result : indexClient.search("luxury hotel",
for (SearchResult result : searchIndexClient.search("luxury hotel",
new SearchOptions(), new RequestOptions(), Context.NONE)) {

// Each result is a dynamic Map
Expand Down

0 comments on commit 3872410

Please sign in to comment.