Skip to content

Commit 74bd041

Browse files
haileytaphaileytap
committed
Restructured REST and PowerShell pivots
1 parent 8da1cf2 commit 74bd041

File tree

2 files changed

+143
-275
lines changed

2 files changed

+143
-275
lines changed

‎articles/search/includes/quickstarts/full-text-powershell.md

Lines changed: 63 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ author: haileytap
44
ms.author: haileytapia
55
ms.service: azure-ai-search
66
ms.topic: include
7-
ms.date: 06/26/2025
7+
ms.date: 06/30/2025
88
---
99

1010
In this quickstart, you use PowerShell and the [Azure AI Search REST APIs](/rest/api/searchservice/) to create, load, and query a search index for [full-text search](../../search-lucene-query-architecture.md). Full-text search uses Apache Lucene for indexing and queries and the BM25 ranking algorithm for scoring results.
@@ -95,30 +95,30 @@ To connect to your search service:
9595
$url = "<YOUR-SEARCH-SERVICE>/indexes?api-version=2024-07-01&`$select=name"
9696
```
9797
98-
1. Run `Invoke-RestMethod` to send a GET request to your search service and verify the connection. Include `ConvertTo-Json` to view responses from the service.
98+
1. Run `Invoke-RestMethod` to send a GET request to your search service. Include `ConvertTo-Json` to view responses from the service.
9999
100100
```powershell
101101
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
102102
```
103103
104104
If your service is empty and has no indexes, the response is similar to the following example. Otherwise, you see a JSON representation of index definitions.
105105
106-
```
106+
```json
107107
{
108108
"@odata.context": "https://my-service.search.windows.net/$metadata#indexes",
109109
"value": [
110110
111111
]
112112
}
113-
```
113+
```json
114114
115-
## Create, load, and query a search index
115+
## Create a search index
116116
117-
In this section, you make REST API calls to create a search index, upload documents to the index, and query the indexed documents. Responses to `Invoke-RestMethod` are displayed in the PowerShell console. For more information about each step, see [Explaining the code](#explaining-the-code).
117+
Before you add content to Azure AI Search, you must create an index to define how the content is stored and structured. An index is conceptually similar to a table in a relational database, but it's specifically designed for search operations, such as full-text search.
118118
119-
Run the following commands in the same PowerShell session you started in the previous section. For each command that updates the `$url` object, replace `<YOUR-SEARCH-SERVICE>` with the value you obtained in [Get endpoint](#get-endpoint).
119+
Run the following commands in the same PowerShell session you started in the previous section.
120120
121-
To create, load, and query an index:
121+
To create an index:
122122
123123
1. Create a `$body` object to define the index schema.
124124
@@ -149,20 +149,42 @@ To create, load, and query an index:
149149
"@
150150
```
151151
152-
1. Update the `$url` object to target the new index.
152+
2. Update the `$url` object to target the new index. Replace `<YOUR-SEARCH-SERVICE>` with the value you obtained in [Get endpoint](#get-endpoint).
153153
154154
```powershell
155155
$url = "<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart?api-version=2024-07-01"
156156
```
157157
158-
1. Run `Invoke-RestMethod` to create the index on your search service.
158+
3. Run `Invoke-RestMethod` to create the index on your search service.
159159
160160
```powershell
161161
Invoke-RestMethod -Uri $url -Headers $headers -Method Put -Body $body | ConvertTo-Json
162162
```
163163
164164
The response should contain the JSON representation of the index schema.
165165
166+
### About the create index request
167+
168+
This quickstart calls [Indexes - Create (REST API)](/rest/api/searchservice/indexes/create) to build a search index named `hotels-quickstart` and its physical data structures on your search service.
169+
170+
Within the index schema, the `fields` collection defines the structure of hotel documents. Each field has a `name`, data `type`, and attributes that determine its behavior during indexing and queries. The `HotelId` field is marked as the key, which Azure AI Search requires to uniquely identify each document in an index.
171+
172+
Key points about the index schema:
173+
174+
+ Use string fields (`Edm.String`) to make numeric data full-text searchable. Other [supported data types](/rest/api/searchservice/supported-data-types), such as `Edm.Int32`, are filterable, sortable, facetable, and retrievable but aren't searchable.
175+
176+
+ Most of our fields are simple data types, but you can define complex types to represent nested data, such as the `Address` field.
177+
178+
+ Field attributes determine allowed actions. The REST APIs allow [many actions by default](/rest/api/searchservice/indexes/create#request-body). For example, all strings are searchable and retrievable. With the REST APIs, you might only use attributes if you need to disable a behavior.
179+
180+
## Load the index
181+
182+
Newly created indexes are empty. To populate an index and make it searchable, you must upload JSON documents that conform to the index schema.
183+
184+
In Azure AI Search, documents serve as both inputs for indexing and outputs for queries. For simplicity, this quickstart provides sample hotel documents as inline JSON. In production scenarios, however, content is often pulled from connected data sources and transformed into JSON using [indexers](../../search-indexer-overview.md).
185+
186+
To upload documents to your index:
187+
166188
1. Create a `$body` object to store the JSON payload of four sample documents.
167189
168190
```powershell
@@ -250,163 +272,73 @@ To create, load, and query an index:
250272
"@
251273
```
252274
253-
1. Update the `$url` object to target the `docs/index` endpoint of your index.
275+
2. Update the `$url` object to target the indexing endpoint. Replace `<YOUR-SEARCH-SERVICE>` with the value you obtained in [Get endpoint](#get-endpoint).
254276
255277
```powershell
256278
$url = "<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs/index?api-version=2024-07-01"
257279
```
258280
259-
1. Run `Invoke-RestMethod` to upload the documents to your index.
281+
3. Run `Invoke-RestMethod` to send the upload request to your search service.
260282
261283
```powershell
262284
Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body | ConvertTo-Json
263285
```
264286
265287
The response should contain the key and status of each uploaded document.
266288
267-
1. Update the `$url` object to target the `docs` endpoint of your index and specify a query.
268-
269-
```powershell
270-
$url = '<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=attached restaurant&searchFields=Description,Tags&$select=HotelId,HotelName,Tags,Description&$count=true'
271-
```
272-
273-
1. Run `Invoke-RestMethod` to query the documents in your index.
274-
275-
```powershell
276-
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
277-
```
278-
279-
The response should contain the document that matched your query, its relevance score, and its selected fields.
280-
281-
## Explaining the code
282-
283-
This section explains the REST API calls that you made to:
284-
285-
+ [Create an index](#create-an-index)
286-
+ [Load documents into the index](#load-documents-into-the-index)
287-
+ [Query the index](#query-the-index)
288-
289-
### Create an index
290-
291-
Before you add content to Azure AI Search, you must create an index to define how the content is stored and structured. An index is conceptually similar to a table in a relational database, but it's specifically designed for search operations, such as full-text search.
292-
293-
This quickstart calls [Indexes - Create (REST API)](/rest/api/searchservice/indexes/create) to build a search index named `hotels-quickstart` and its physical data structures on your search service.
289+
### About the upload request
294290
295-
```powershell
296-
$body = @"
297-
{
298-
"name": "hotels-quickstart",
299-
"fields": [
300-
{"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
301-
{"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
302-
{"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
303-
{"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
304-
{"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
305-
{"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
306-
{"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
307-
{"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
308-
{"name": "Address", "type": "Edm.ComplexType",
309-
"fields": [
310-
{"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
311-
{"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
312-
{"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
313-
{"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
314-
{"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
315-
]
316-
}
317-
]
318-
}
319-
"@
320-
321-
$url = "<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart?api-version=2024-07-01"
322-
```
291+
This quickstart calls [Documents - Index (REST API)](/rest/api/searchservice/documents/) to add four sample hotel documents to your index. Compared to the previous request, the URI is extended to include the `docs` collection and `index` operation.
323292
324-
Within our index schema, the `fields` collection defines the structure of hotel documents. Each field has a `name`, data `type`, and attributes that determine its behavior during indexing and queries. The `HotelId` field is marked as the key, which Azure AI Search requires to uniquely identify each document in an index.
293+
Each document in the `value` array represents a hotel and contains fields that match the index schema. The `@search.action` parameter specifies the operation to perform for each document. Our example uses `upload`, which adds the document if it doesn't exist or updates the document if it does exist.
325294
326-
Key points about the index schema:
295+
## Query the index
327296
328-
+ Use string fields (`Edm.String`) to make numeric data full-text searchable. Other [supported data types](/rest/api/searchservice/supported-data-types), such as `Edm.Int32`, are filterable, sortable, facetable, and retrievable but aren't searchable.
297+
Now that documents are loaded into your index, you can use full-text search to find specific terms or phrases within their fields.
329298
330-
+ Most of our fields are simple data types, but you can define complex types to represent nested data, such as the `Address` field.
299+
To run a full-text query against your index:
331300
332-
+ Field attributes determine allowed actions. The REST APIs allow [many actions by default](/rest/api/searchservice/indexes/create#request-body). For example, all strings are searchable and retrievable. With the REST APIs, you might only use attributes if you need to disable a behavior.
301+
1. Update the `$url` object to specify search parameters. Replace `<YOUR-SEARCH-SERVICE>` with the value you obtained in [Get endpoint](#get-endpoint).
333302
334-
### Load documents into the index
303+
```powershell
304+
$url = '<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=attached restaurant&searchFields=Description,Tags&$select=HotelId,HotelName,Tags,Description&$count=true'
305+
```
335306
336-
Newly created indexes are empty. To populate an index and make it searchable, you must upload JSON documents that conform to the index schema.
307+
2. Run `Invoke-RestMethod` to send the query request to your search service.
337308
338-
In Azure AI Search, documents serve as both inputs for indexing and outputs for queries. For simplicity, this quickstart provides sample hotel documents as inline JSON. In production scenarios, however, content is often pulled from connected data sources and transformed into JSON using [indexers](../../search-indexer-overview.md).
309+
```powershell
310+
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
311+
```
339312
340-
This quickstart calls [Documents - Index (REST API)](/rest/api/searchservice/documents/) to add four sample hotel documents to your index.
313+
The response should be similar to the following example, which shows one matching hotel document, its relevance score, and its selected fields.
341314
342-
```powershell
343-
$body = @"
315+
```json
344316
{
345-
"value": [
317+
"@odata.context": "https://my-service.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)",
318+
"@odata.count": 1,
319+
"value": [
346320
{
347-
"@search.action": "upload",
348-
"HotelId": "1",
349-
"HotelName": "Stay-Kay City Hotel",
350-
"Description": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
351-
"Category": "Boutique",
352-
"Tags": [ "view", "air conditioning", "concierge" ],
353-
"ParkingIncluded": false,
354-
"LastRenovationDate": "2022-01-18T00:00:00Z",
355-
"Rating": 3.60,
356-
"Address":
357-
{
358-
"StreetAddress": "677 5th Ave",
359-
"City": "New York",
360-
"StateProvince": "NY",
361-
"PostalCode": "10022",
362-
"Country": "USA"
363-
}
364-
},
365-
// OTHER DOCUMENTS OMITTED FOR BREVITY
321+
"@search.score": 0.5575875,
322+
"HotelId": "3",
323+
"HotelName": "Gastronomic Landscape Hotel",
324+
"Description": "The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services.",
325+
"Tags": "restaurant bar continental breakfast"
326+
}
366327
]
367328
}
368-
"@
369-
370-
$url = "<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs/index?api-version=2024-07-01"
371-
```
372-
373-
Each document in the `value` array represents a hotel and contains fields that match the index schema. The `@search.action` parameter specifies the operation to perform for each document. Our example uses `upload`, which adds the document if it doesn't exist or updates the document if it does exist.
374-
375-
### Query the index
376-
377-
Now that documents are loaded into your index, you can issue full-text queries against them.
329+
```
378330
379-
This quickstart calls [Documents - Search Post (REST API)](/rest/api/searchservice/documents/search-post) to find hotel documents that match your search criteria.
331+
### About the query request
380332
381-
```powershell
382-
$url = '<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=attached restaurant&searchFields=Description,Tags&$select=HotelId,HotelName,Tags,Description&$count=true'
383-
```
333+
This quickstart calls [Documents - Search Post (REST API)](/rest/api/searchservice/documents/search-post) to find hotel documents that match your search criteria. The URI still targets the `docs` collection but no longer includes the `index` operation.
384334
385335
Full-text search requests always include a `search` parameter that contains the query text. The query text can include one or more terms, phrases, or operators. In addition to `search`, you can specify other parameters to refine the search behavior and results.
386336
387337
Our query searches for the terms "attached restaurant" in the `Description` and `Tags` fields of each hotel document. The `$select` parameter limits the fields returned in the response to `HotelId`, `HotelName`, `Tags`, and `Description`. The `$count` parameter requests the total number of matching documents.
388338
389-
The response should be similar to the following example, which shows one matching hotel document, its relevance score, and its selected fields.
390-
391-
```
392-
{
393-
"@odata.context": "https://my-service.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)",
394-
"@odata.count": 1,
395-
"value": [
396-
{
397-
"@search.score": 0.5575875,
398-
"HotelId": "3",
399-
"HotelName": "Gastronomic Landscape Hotel",
400-
"Description": "The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
401-
"Tags": "restaurant bar continental breakfast"
402-
}
403-
]
404-
}
405-
```
406-
407339
#### Other query examples
408340
409-
Run the following commands to explore the query syntax. You can perform string searches, use `$filter` expressions, limit result sets, select specific fields, and more.
341+
Run the following commands to explore the query syntax. You can perform string searches, use `$filter` expressions, limit result sets, select specific fields, and more. Remember to replace `<YOUR-SEARCH-SERVICE>` with the value you obtained in [Get endpoint](#get-endpoint).
410342
411343
```powershell
412344
# Query example 1

0 commit comments

Comments
 (0)