Quickstart: Vector search by using REST
Learn how to use the Search REST APIs to create, load, and query vectors in Azure AI Search.
In Azure AI Search, a vector store has an index schema that defines vector and nonvector fields, a vector configuration for algorithms that create the embedding space, and settings on vector field definitions that are used in query requests. The Create Index API creates the vector store.
If you don't have an Azure subscription, create a trial subscription before you begin.
Note
This quickstart omits the vectorization step and provides embeddings in sample documents. If you want to add built-in data chunking and vectorization over your own content, try the Import and vectorize data wizard for an end-to-end walkthrough.
Prerequisites
Visual Studio Code with a REST client. If you need help with getting started, see Quickstart: Text search using REST.
Azure AI Search, in any region and on any tier. You can use the Free tier for this quickstart, but Basic or higher is recommended for larger data files. Create or find an existing Azure AI Search resource under your current subscription.
Most existing services support vector search. For a small subset of services created prior to January 2019, an index that contains vector fields fails on creation. In this situation, a new service must be created.
Optionally, an Azure OpenAI resource with a deployment of
text-embedding-ada-002. The source.restfile includes an optional step for generating new text embeddings, but we provide pregenerated embeddings so that you can omit this dependency.
Download files
Download a REST sample from GitHub to send the requests in this quickstart. For more information, see Downloading files from GitHub.
You can also start a new file on your local system and create requests manually by using the instructions in this article.
Get a search service endpoint
You can find the search service endpoint in the Azure portal.
Sign in to the Azure portal and find your search service.
On the Overview home page, find the URL. An example endpoint might look like
https://mydemo.search.azure.cn.
You're pasting this endpoint into the .rest or .http file in a later step.
Configure access
Requests to the search endpoint must be authenticated and authorized. You can use API keys or roles for this task. Keys are easier to start with, but roles are more secure.
For a role-based connection, the following instructions have you connecting to Azure AI Search under your identity, not the identity of a client app.
Option 1: Use keys
Select Settings > Keys and then copy an admin key. Admin keys are used to add, modify, and delete objects. There are two interchangeable admin keys. Copy either one. For more information, see Connect to Azure AI Search using key authentication.
You're pasting this key into the .rest or .http file in a later step.
Option 2: Use roles
Make sure your search service is configured for role-based access. You must have preconfigured role-assignments for developer access. Your role assignments must grant permission to create, load, and query a search index.
In this section, obtain your personal identity token using either the Azure CLI, Azure PowerShell, or the Azure portal.
Sign in to Azure CLI.
az cloud set -n AzureChinaCloud az login # az cloud set -n AzureCloud //means return to Public Azure.Get your personal identity token.
az account get-access-token --scope https://search.azure.com/.default
You're pasting your personal identity token into the .rest or .http file in a later step.
Note
This section assumes you're using a local client that connects to Azure AI Search on your behalf. An alternative approach is getting a token for the client app, assuming your application is registered with Microsoft Entra ID.
Create a vector index
Create Index (REST) creates a vector index and sets up the physical data structures on your search service.
The index schema is organized around hotel content. Sample data consists of vector and nonvector names and descriptions of seven fictitious hotels. This schema includes configurations for vector indexing and queries, and for semantic ranking.
Open a new text file in Visual Studio Code.
Set variables to the values you collected earlier. This example uses a personal identity token.
@baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERESave the file with a
.restor.httpfile extension.Paste in the following example to create the
hotels-vector-quickstartindex on your search service.### Create a new index POST {{baseUrl}}/indexes?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "name": "hotels-vector-quickstart", "fields": [ { "name": "HotelId", "type": "Edm.String", "searchable": false, "filterable": true, "retrievable": true, "sortable": false, "facetable": false, "key": true }, { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "sortable": true, "facetable": false }, { "name": "HotelNameVector", "type": "Collection(Edm.Single)", "searchable": true, "retrievable": true, "dimensions": 1536, "vectorSearchProfile": "my-vector-profile" }, { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "sortable": false, "facetable": false }, { "name": "DescriptionVector", "type": "Collection(Edm.Single)", "searchable": true, "retrievable": true, "dimensions": 1536, "vectorSearchProfile": "my-vector-profile" }, { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true }, { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "retrievable": true, "sortable": false, "facetable": true }, { "name": "Address", "type": "Edm.ComplexType", "fields": [ { "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true }, { "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true } ] }, { "name": "Location", "type": "Edm.GeographyPoint", "searchable": false, "filterable": true, "retrievable": true, "sortable": true, "facetable": false } ], "vectorSearch": { "algorithms": [ { "name": "my-hnsw-vector-config-1", "kind": "hnsw", "hnswParameters": { "m": 4, "efConstruction": 400, "efSearch": 500, "metric": "cosine" } }, { "name": "my-hnsw-vector-config-2", "kind": "hnsw", "hnswParameters": { "m": 4, "metric": "euclidean" } }, { "name": "my-eknn-vector-config", "kind": "exhaustiveKnn", "exhaustiveKnnParameters": { "metric": "cosine" } } ], "profiles": [ { "name": "my-vector-profile", "algorithm": "my-hnsw-vector-config-1" } ] } }Select Send request. Recall that you need the REST client to send requests. You should have an
HTTP/1.1 201 Createdresponse. The response body should include the JSON representation of the index schema.Key points:
- The
fieldscollection includes a required key field and text and vector fields (such asDescriptionandDescriptionVector) for text and vector search. Colocating vector and nonvector fields in the same index enables hybrid queries. For instance, you can combine filters, text search with semantic ranking, and vectors into a single query operation. - Vector fields must be
type: Collection(Edm.Single)withdimensionsandvectorSearchProfileproperties. - The
vectorSearchsection is an array of approximate nearest neighbor algorithm configurations and profiles. Supported algorithms include hierarchical navigable small world and exhaustive k-nearest neighbor. For more information, see Relevance scoring in vector search.
- The
Upload documents
Creating and loading the index are separate steps. In Azure AI Search, the index contains all searchable data and queries run on the search service. For REST calls, the data is provided as JSON documents. Use Documents- Index REST API for this task.
The URI is extended to include the docs collection and the index operation.
Important
The following example isn't runnable code. For readability, we excluded vector values because each one contains 1,536 embeddings, which is too long for this article. If you want to try this step, copy runnable code from the sample on GitHub.
### Upload documents
POST {{baseUrl}}/indexes/hotels-quickstart-vectors/docs/index?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}
{
"value": [
{
"@search.action": "mergeOrUpload",
"HotelId": "1",
"HotelName": "Stay-Kay City Hotel",
"HotelNameVector": [VECTOR ARRAY OMITTED],
"Description":
"The hotel is ideally located on the main commercial artery of the city
in the heart of Beijing.",
"DescriptionVector": [VECTOR ARRAY OMITTED],
"Category": "Boutique",
"Tags": [
"pool",
"air conditioning",
"concierge"
],
},
{
"@search.action": "mergeOrUpload",
"HotelId": "2",
"HotelName": "Old Century Hotel",
"HotelNameVector": [VECTOR ARRAY OMITTED],
"Description":
"The hotel is situated in a nineteenth century plaza, which has been
expanded and renovated to the highest architectural standards to create a modern,
functional and first-class hotel in which art and unique historical elements
coexist with the most modern comforts.",
"DescriptionVector": [VECTOR ARRAY OMITTED],
"Category": "Boutique",
"Tags": [
"pool",
"air conditioning",
"free wifi",
"concierge"
]
},
{
"@search.action": "mergeOrUpload",
"HotelId": "3",
"HotelName": "Gastronomic Landscape Hotel",
"HotelNameVector": [VECTOR ARRAY OMITTED],
"Description":
"The Hotel stands out for its gastronomic excellence under the management of
William Dough, who advises on and oversees all of the Hotel's restaurant services.",
"DescriptionVector": [VECTOR ARRAY OMITTED],
"Category": "Resort and Spa",
"Tags": [
"air conditioning",
"bar",
"continental breakfast"
]
}
{
"@search.action": "mergeOrUpload",
"HotelId": "4",
"HotelName": "Sublime Palace Hotel",
"HotelNameVector": [VECTOR ARRAY OMITTED],
"Description":
"Sublime Palace Hotel is located in the heart of the historic center of
Sublime in an extremely vibrant and lively area within short walking distance to
the sites and landmarks of the city and is surrounded by the extraordinary beauty
of churches, buildings, shops and monuments.
Sublime Palace is part of a lovingly restored 1800 palace.",
"DescriptionVector": [VECTOR ARRAY OMITTED],
"Category": "Boutique",
"Tags": [
"concierge",
"view",
"24-hour front desk service"
]
},
{
"@search.action": "mergeOrUpload",
"HotelId": "13",
"HotelName": "Luxury Lion Resort",
"HotelNameVector": [VECTOR ARRAY OMITTED],
"Description":
"Unmatched Luxury. Visit our downtown hotel to indulge in luxury
accommodations. Moments from the stadium, we feature the best in comfort",
"DescriptionVector": [VECTOR ARRAY OMITTED],
"Category": "Resort and Spa",
"Tags": [
"view",
"free wifi",
"pool"
]
},
{
"@search.action": "mergeOrUpload",
"HotelId": "48",
"HotelName": "Nordick's Valley Motel",
"HotelNameVector": [VECTOR ARRAY OMITTED],
"Description":
"Only 90 miles (about 2 hours) from the nation's capital and nearby
most everything the historic valley has to offer. Hiking? Wine Tasting? Exploring
the caverns? It's all nearby and we have specially priced packages to help make
our B&B your home base for fun while visiting the valley.",
"DescriptionVector": [VECTOR ARRAY OMITTED],
"Category": "Boutique",
"Tags": [
"continental breakfast",
"air conditioning",
"free wifi"
],
},
{
"@search.action": "mergeOrUpload",
"HotelId": "49",
"HotelName": "Swirling Currents Hotel",
"HotelNameVector": [VECTOR ARRAY OMITTED],
"Description":
"Spacious rooms, glamorous suites and residences, rooftop pool, walking
access to shopping, dining, entertainment and the city center.",
"DescriptionVector": [VECTOR ARRAY OMITTED],
"Category": "Luxury",
"Tags": [
"air conditioning",
"laundry service",
"24-hour front desk service"
]
}
]
}
Key points:
- Documents in the payload consist of fields defined in the index schema.
- Vector fields contain floating point values. The dimensions attribute has a minimum of 2 and a maximum of 3,072 floating point values each. This quickstart sets the dimensions attribute to 1,536 because that's the size of embeddings generated by the Azure OpenAI text-embedding-ada-002 model.
Run queries
Now that documents are loaded, you can issue vector queries against them by using Documents - Search Post (REST).
There are several queries to demonstrate various patterns:
The vector queries in this section are based on two strings:
- Search string:
historic hotel walk to restaurants and shopping - Vector query string (vectorized into a mathematical representation):
classic lodging near running trails, eateries, retail
Important
The following examples aren't runnable code. For readability, we excluded vector values because each array contains 1,536 embeddings, which is too long for this article. If you want to try these queries, copy runnable code from the sample on GitHub.
Single vector search
Paste in a POST request to query the search index. Then select Send request. The URI is extended to include the
/docs/searchoperator.### Run a query POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "count": true, "select": "HotelId, HotelName, Description, Category", "vectorQueries": [ { "vector"": [0.01944167, 0.0040178085 . . . TRIMMED FOR BREVITY 010858015, -0.017496133], "k": 7, "fields": "DescriptionVector", "kind": "vector", "exhaustive": true } ] }This vector query is shortened for brevity. The
vectorQueries.vectorcontains the vectorized text of the query input,fieldsdetermines which vector fields are searched, andkspecifies the number of nearest neighbors to return.The vector query string is
classic lodging near running trails, eateries, retail, which is vectorized into 1,536 embeddings for this query.Review the response. The response for the vector equivalent of
classic lodging near running trails, eateries, retailincludes seven results. Each result provides a search score and the fields listed inselect. In a similarity search, the response always includeskresults ordered by the value similarity score.{ "@odata.context": "https://my-demo-search.search.azure.cn/indexes('hotels-vector-quickstart')/$metadata#docs(*)", "@odata.count": 7, "value": [ { "@search.score": 0.857736, "HotelName": "Nordick's Valley Motel", "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer. Hiking? Wine Tasting? Exploring the caverns? It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley." }, { "@search.score": 0.8399129, "HotelName": "Swirling Currents Hotel", "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center." }, { "@search.score": 0.8383954, "HotelName": "Luxury Lion Resort", "Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort" }, { "@search.score": 0.8254346, "HotelName": "Sublime Palace Hotel", "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace." }, { "@search.score": 0.82380056, "HotelName": "Stay-Kay City Hotel", "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of Beijing." }, { "@search.score": 0.81514084, "HotelName": "Old Century Hotel", "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts." }, { "@search.score": 0.8133763, "HotelName": "Gastronomic Landscape Hotel", "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services." } ] }
Single vector search with filter
You can add filters, but the filters are applied to the nonvector content in your index. In this example, the filter applies to the Tags field to filter out any hotels that don't provide free Wi-Fi.
Paste in a POST request to query the search index.
### Run a vector query with a filter POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "count": true, "select": "HotelId, HotelName, Category, Tags, Description", "filter": "Tags/any(tag: tag eq 'free wifi')", "vectorFilterMode": "postFilter", "vectorQueries": [ { "vector": [ VECTOR OMITTED ], "k": 7, "fields": "DescriptionVector", "kind": "vector", "exhaustive": true }, ] }Review the response. The query is the same as the previous example, but it includes a post-processing exclusion filter and returns only the three hotels that have free Wi-Fi.
{ "@odata.count": 3, "value": [ { "@search.score": 0.857736, "HotelName": "Nordick's Valley Motel", "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer. Hiking? Wine Tasting? Exploring the caverns? It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.", "Tags": [ "continental breakfast", "air conditioning", "free wifi" ] }, { "@search.score": 0.8383954, "HotelName": "Luxury Lion Resort", "Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort", "Tags": [ "view", "free wifi", "pool" ] }, { "@search.score": 0.81514084, "HotelName": "Old Century Hotel", "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.", "Tags": [ "pool", "free wifi", "concierge" ] } ] }
Hybrid search
Hybrid search consists of keyword queries and vector queries in a single search request. This example runs the vector query and full text search concurrently:
- Search string:
historic hotel walk to restaurants and shopping - Vector query string (vectorized into a mathematical representation):
classic lodging near running trails, eateries, retail
Paste in a POST request to query the search index. Then select Send request.
### Run a hybrid query POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "count": true, "search": "historic hotel walk to restaurants and shopping", "select": "HotelName, Description", "top": 7, "vectorQueries": [ { "vector": [ VECTOR OMITTED], "k": 7, "fields": "DescriptionVector", "kind": "vector", "exhaustive": true } ] }Because this is a hybrid query, results are ranked by Reciprocal Rank Fusion (RRF). RRF evaluates search scores of multiple search results, takes the inverse, and then merges and sorts the combined results. The
topnumber of results are returned.Review the response.
{ "@odata.count": 7, "value": [ { "@search.score": 0.03279569745063782, "HotelName": "Luxury Lion Resort", "Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort" }, { "@search.score": 0.03226646035909653, "HotelName": "Sublime Palace Hotel", "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace." }, { "@search.score": 0.03226646035909653, "HotelName": "Swirling Currents Hotel", "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center." }, { "@search.score": 0.03205128386616707, "HotelName": "Nordick's Valley Motel", "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer. Hiking? Wine Tasting? Exploring the caverns? It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley." }, { "@search.score": 0.03128054738044739, "HotelName": "Gastronomic Landscape Hotel", "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services." }, { "@search.score": 0.03100961446762085, "HotelName": "Old Century Hotel", "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts." }, { "@search.score": 0.03077651560306549, "HotelName": "Stay-Kay City Hotel", "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of Beijing." } ] }Because RRF merges results, it helps to review the inputs. The following results are from only the full-text query. The top two results are Sublime Palace Hotel and History Lion Resort. The Sublime Palace Hotel has a stronger BM25 relevance score.
{ "@search.score": 2.2626662, "HotelName": "Sublime Palace Hotel", "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace." }, { "@search.score": 0.86421645, "HotelName": "Luxury Lion Resort", "Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort" },In the vector-only query, which uses HNSW for finding matches, the Sublime Palace Hotel drops to fourth position. Historic Lion, which was second in the full-text search and third in the vector search, doesn't experience the same range of fluctuation, so it appears as a top match in a homogenized result set.
"value": [ { "@search.score": 0.857736, "HotelId": "48", "HotelName": "Nordick's Valley Motel", "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer. Hiking? Wine Tasting? Exploring the caverns? It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.", "Category": "Boutique" }, { "@search.score": 0.8399129, "HotelId": "49", "HotelName": "Swirling Currents Hotel", "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.", "Category": "Luxury" }, { "@search.score": 0.8383954, "HotelId": "13", "HotelName": "Luxury Lion Resort", "Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort", "Category": "Resort and Spa" }, { "@search.score": 0.8254346, "HotelId": "4", "HotelName": "Sublime Palace Hotel", "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.", "Category": "Boutique" }, { "@search.score": 0.82380056, "HotelId": "1", "HotelName": "Stay-Kay City Hotel", "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of Beijing.", "Category": "Boutique" }, { "@search.score": 0.81514084, "HotelId": "2", "HotelName": "Old Century Hotel", "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.", "Category": "Boutique" }, { "@search.score": 0.8133763, "HotelId": "3", "HotelName": "Gastronomic Landscape Hotel", "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services.", "Category": "Resort and Spa" } ]
Clean up
When you're working in your own subscription, it's a good idea at the end of a project to identify whether you still need the resources you created. Resources left running can cost you money. You can delete resources individually or delete the resource group to delete the entire set of resources.
You can find and manage resources in the portal by using the All resources or Resource groups link in the leftmost pane.
You can also try this DELETE command:
### Delete an index
DELETE {{baseUrl}}/indexes/hotels-vector-quickstart?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}
Next steps
As a next step, we recommend that you review the demo code for Python, C#, or JavaScript.