Skip to content

Commit d459eeb

Browse files
HeidiSteenHeidiSteen
committed
checkpoint, staging the rev'd java doc
1 parent 9f5f55f commit d459eeb

File tree

3 files changed

+1143
-4
lines changed

3 files changed

+1143
-4
lines changed

‎articles/search/TOC.yml

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@
3131
href: search-get-started-dotnet.md
3232
- name: Java
3333
href: search-get-started-java.md
34+
- name: Java (New)
35+
href: search-get-started-java-new.md
3436
- name : JavaScript
3537
href: search-get-started-javascript.md
3638
- name: REST
@@ -143,8 +145,6 @@
143145
href: search-query-overview.md
144146
- name: Relevance scoring
145147
href: index-similarity-and-scoring.md
146-
- name: Semantic ranking
147-
href: semantic-ranking.md
148148
- name: Indexing
149149
items:
150150
- name: Search indexes
@@ -458,9 +458,11 @@
458458
href: search-normalizers.md
459459
- name: Relevance
460460
items:
461-
- name: Configure scoring
461+
- name: Similarity ranking
462462
href: index-ranking-similarity.md
463-
- name: Add a scoring profile
463+
- name: Semantic ranking
464+
href: semantic-ranking.md
465+
- name: Scoring profiles
464466
href: index-add-scoring-profiles.md
465467
- name: Performance and monitoring
466468
items:

‎articles/search/search-get-started-java-new-1.md

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
---
2+
title: 'Quickstart: Create a search index in Java'
3+
titleSuffix: Azure Cognitive Search
4+
description: In this Java quickstart, learn how to create an index, load data, and run queries using the Azure Cognitive Search client library for Java.
5+
manager: nitinme
6+
author: HeidiSteen
7+
ms.author: heidist
8+
ms.devlang: java
9+
ms.service: cognitive-search
10+
ms.topic: quickstart
11+
ms.date: 10/17/2022
12+
13+
---
14+
15+
# Quickstart: Create an Azure Cognitive Search index in Java
16+
17+
In this quickstart, you'll learn how to use the [Azure.Search.Documents (version 11) client library](/java/api/overview/azure/search-documents-readme) to create a console application in Java that creates, loads, and queries a search index.
18+
19+
You can [download the source code](https://github.com/Azure-Samples/azure-search-java-samples) to start with a finished project or follow the steps in this article to create your own.
20+
21+
## Prerequisites
22+
23+
Azure subscription - Create one for free
24+
Azure Cognitive Search
25+
Visual Studio Code with the Java Extension Pack
26+
[Apache Maven](https://maven.apache.org/install.html)
27+
28+
## Get a key and URL
29+
30+
Calls to the service require a URL endpoint and an access key on every request. A search service is created with both, so if you added Azure Cognitive Search to your subscription, follow these steps to get the necessary information:
31+
32+
1. [Sign in to the Azure portal](https://portal.azure.com/), and in your search service **Overview** page, get the URL. An example endpoint might look like `https://mydemo.search.windows.net`.
33+
34+
1. In **Settings** > **Keys**, get an admin key for full rights on the service. There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.
35+
36+
:::image type="content" source="media/search-get-started-rest/get-url-key.png" alt-text="Get the service name and admin and query keys" border="false":::
37+
38+
Every request sent to your service requires an API key. Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.
39+
40+
## Set up the environment
41+
42+
TBD
43+
44+
1. Confirm Java and Maven installations. At a command prompt, enter `java -version` followed by `mvn -version`. If you don't see version and location, check the prerequisites.
45+
46+
1. Start Visual Studio Code and create a new folder to store your project files.
47+
48+
1. Create a new `pom.xml` file in the root of your project, and copy the following into it:
49+
50+
```xml
51+
<?xml version="1.0" encoding="UTF-8"?>
52+
<project xmlns="http://maven.apache.org/POM/4.0.0"
53+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
54+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
55+
<modelVersion>4.0.0</modelVersion>
56+
57+
<parent>
58+
<groupId>com.azure</groupId>
59+
<artifactId>azure-client-sdk-parent</artifactId>
60+
<version>1.7.0</version><!-- {x-version-update;com.azure:azure-client-sdk-parent;current} -->
61+
<relativePath>../../parents/azure-client-sdk-parent</relativePath>
62+
</parent>
63+
64+
<name>Microsoft Azure Cognitive Search client for Java</name>
65+
<description>This package contains client functionality for Microsoft Azure Cognitive Search</description>
66+
67+
<groupId>com.azure</groupId>
68+
<artifactId>azure-search-documents</artifactId>
69+
<version>11.5.1</version> <!-- {x-version-update;com.azure:azure-search-documents;current} -->
70+
<packaging>jar</packaging>
71+
72+
<properties>
73+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
74+
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
75+
<jacoco.min.linecoverage>0.70</jacoco.min.linecoverage>
76+
<jacoco.min.branchcoverage>0.60</jacoco.min.branchcoverage>
77+
<!-- Configures the Java 9+ run to perform the required module exports, opens, and reads that are necessary for testing but shouldn't be part of the module-info. -->
78+
<javaModulesSurefireArgLine>
79+
--add-exports com.azure.core/com.azure.core.implementation.http=ALL-UNNAMED
80+
--add-exports com.azure.core/com.azure.core.implementation.jackson=ALL-UNNAMED
81+
--add-opens com.azure.core/com.azure.core.util=ALL-UNNAMED
82+
--add-opens com.azure.search.documents/com.azure.search.documents=ALL-UNNAMED
83+
--add-opens com.azure.search.documents/com.azure.search.documents.indexes=ALL-UNNAMED
84+
--add-opens com.azure.search.documents/com.azure.search.documents.models=ALL-UNNAMED
85+
--add-opens com.azure.search.documents/com.azure.search.documents.implementation=ALL-UNNAMED
86+
--add-opens com.azure.search.documents/com.azure.search.documents.implementation.models=ALL-UNNAMED
87+
--add-opens com.azure.search.documents/com.azure.search.documents.test.environment.models=com.fasterxml.jackson.databind
88+
--add-opens com.azure.search.documents/com.azure.search.documents.test.environment.models=ALL-UNNAMED
89+
--add-reads com.azure.search.documents=com.azure.core.serializer.json.jackson
90+
--add-reads com.azure.core=ALL-UNNAMED
91+
--add-reads com.azure.core.test=ALL-UNNAMED
92+
--add-reads com.azure.core.http.netty=ALL-UNNAMED
93+
</javaModulesSurefireArgLine>
94+
</properties>
95+
96+
<dependencies>
97+
<dependency>
98+
<groupId>com.azure</groupId>
99+
<artifactId>azure-core</artifactId>
100+
<version>1.33.0</version> <!-- {x-version-update;com.azure:azure-core;dependency} -->
101+
</dependency>
102+
<dependency>
103+
<groupId>com.azure</groupId>
104+
<artifactId>azure-core-http-netty</artifactId>
105+
<version>1.12.6</version> <!-- {x-version-update;com.azure:azure-core-http-netty;dependency} -->
106+
</dependency>
107+
<dependency>
108+
<groupId>com.azure</groupId>
109+
<artifactId>azure-core-serializer-json-jackson</artifactId>
110+
<version>1.2.22</version> <!-- {x-version-update;com.azure:azure-core-serializer-json-jackson;dependency} -->
111+
</dependency>
112+
113+
<!-- Added this dependency to include necessary annotations used by reactor core.
114+
Without this dependency, javadoc throws a warning as it cannot find enum When.MAYBE
115+
which is used in @Nullable annotation in reactor core classes -->
116+
<dependency>
117+
<groupId>com.google.code.findbugs</groupId>
118+
<artifactId>jsr305</artifactId>
119+
<version>3.0.2</version> <!-- {x-version-update;com.google.code.findbugs:jsr305;external_dependency} -->
120+
<scope>provided</scope>
121+
</dependency>
122+
</dependencies>
123+
</project>
124+
```
125+
126+
1. Install the Azure.Search.Documents package and dependencies.
127+
128+
```console
129+
mvn clean dependency:copy-dependencies
130+
```
131+
132+
### Set environment variables
133+
134+
Your client code must be authenticated to access Azure Cognitive Search.
135+
136+
For this quickstart, you'll copy in an API key and search endpoint from Azure portal. For production, use a secure way of storing and accessing your credentials. For example, you could use Azure Active Directory roles or encrypt an API key in Azure Key Vault.
137+
138+
> [!NOTE]
139+
> Don't include the key directly in your code, and never post it publicly.
140+
141+
Open a console window and run the following commands, substituting valid values for the placeholders.
142+
143+
First, set the API key:
144+
145+
```bash
146+
set AZURE_COGNITIVE_SEARCH_API_KEY <your-search-admin-api-key>
147+
```
148+
149+
Next, provide a URL to your search service:
150+
151+
```bash
152+
set AZURE_COGNITIVE_SEARCH_ENDPOINT <fully-qualified-url>
153+
```
154+
155+
## Create a search index
156+
157+
Follow these steps to create a new console application that creates, loads, and queries an index.
158+
159+
1. Create a new file named `CreateIndex.java` in the same project root directory.
160+
1. Copy the following code into `CreateIndex.java`:
161+
162+
```java
163+
package com.azure.search.documents.indexes;
164+
165+
import com.azure.core.credential.AzureKeyCredential;
166+
import com.azure.core.util.Configuration;
167+
import com.azure.search.documents.indexes.models.LexicalAnalyzerName;
168+
import com.azure.search.documents.indexes.models.SearchField;
169+
import com.azure.search.documents.indexes.models.SearchFieldDataType;
170+
import com.azure.search.documents.indexes.models.SearchIndex;
171+
172+
import java.util.Arrays;
173+
174+
public class CreateIndexExample {
175+
/**
176+
* From the Azure portal, get your Azure Cognitive Search service name and API key and populate ADMIN_KEY and
177+
* SEARCH_SERVICE_NAME.
178+
*/
179+
private static final String ENDPOINT = Configuration.getGlobalConfiguration().get("AZURE_COGNITIVE_SEARCH_ENDPOINT");
180+
private static final String ADMIN_KEY = Configuration.getGlobalConfiguration().get("AZURE_COGNITIVE_SEARCH_API_KEY");
181+
182+
public static void main(String[] args) {
183+
// Create the SearchIndex client.
184+
SearchIndexClient client = new SearchIndexClientBuilder()
185+
.endpoint(ENDPOINT)
186+
.credential(new AzureKeyCredential(ADMIN_KEY))
187+
.buildClient();
188+
189+
// Configure the index using SearchFields
190+
String indexName = "hotels";
191+
SearchIndex newIndex = new SearchIndex(indexName, Arrays.asList(
192+
new SearchField("hotelId", SearchFieldDataType.STRING)
193+
.setKey(true)
194+
.setFilterable(true)
195+
.setSortable(true),
196+
new SearchField("hotelName", SearchFieldDataType.STRING)
197+
.setSearchable(true)
198+
.setFilterable(true)
199+
.setSortable(true),
200+
new SearchField("description", SearchFieldDataType.STRING)
201+
.setSearchable(true)
202+
.setAnalyzerName(LexicalAnalyzerName.EN_LUCENE),
203+
new SearchField("descriptionFr", SearchFieldDataType.STRING)
204+
.setSearchable(true)
205+
.setAnalyzerName(LexicalAnalyzerName.FR_LUCENE),
206+
new SearchField("tags", SearchFieldDataType.collection(SearchFieldDataType.STRING))
207+
.setSearchable(true)
208+
.setFilterable(true)
209+
.setFacetable(true),
210+
new SearchField("address", SearchFieldDataType.COMPLEX)
211+
.setFields(
212+
new SearchField("streetAddress", SearchFieldDataType.STRING)
213+
.setSearchable(true),
214+
new SearchField("city", SearchFieldDataType.STRING)
215+
.setFilterable(true)
216+
.setSortable(true)
217+
.setFacetable(true),
218+
new SearchField("stateProvince", SearchFieldDataType.STRING)
219+
.setSearchable(true)
220+
.setFilterable(true)
221+
.setSortable(true)
222+
.setFacetable(true),
223+
new SearchField("country", SearchFieldDataType.STRING)
224+
.setSearchable(true)
225+
.setSynonymMapNames("synonymMapName")
226+
.setFilterable(true)
227+
.setSortable(true)
228+
.setFacetable(true),
229+
new SearchField("postalCode", SearchFieldDataType.STRING)
230+
.setSearchable(true)
231+
.setFilterable(true)
232+
.setSortable(true)
233+
.setFacetable(true))
234+
));
235+
236+
// Create index.
237+
client.createIndex(newIndex);
238+
239+
// Cleanup index resource.
240+
client.deleteIndex(indexName);
241+
}
242+
}
243+
```
244+
245+
Run your new console application to start speech synthesis to the default speaker.
246+
247+
```console
248+
javac CreateIndex.java -cp ".;target\dependency\*"
249+
java -cp ".;target\dependency\*" CreateIndex
250+
```
251+
252+
## Clean up resources
253+
254+
When you're working in your own subscription, at the end of a project, it's a good idea to remove the resources that you no longer need. Resources left running can cost you money. You can delete resources individually or delete the resource group to delete the entire set of resources.
255+
256+
You can find and manage resources in the portal, using the **All resources** or **Resource groups** link in the left-navigation pane.
257+
258+
If you are using a free service, remember that you are limited to three indexes, indexers, and data sources. You can delete individual items in the portal to stay under the limit.
259+
260+
## Next steps
261+
262+
In this Java quickstart, you worked through a series of tasks to create an index, load it with documents, and run queries. If you are comfortable with the basic concepts, we recommend the following article that lists indexer operations in REST.
263+
264+
> [!div class="nextstepaction"]
265+
> [Indexer operations](/rest/api/searchservice/indexer-operations)

0 commit comments

Comments
 (0)