more detail about the response

Author: HeidiSteen

articles/search/vector-search-how-to-create-index.md

@@ -7,7 +7,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: cognitive-search
 ms.topic: how-to
-ms.date: 07/07/2023
+ms.date: 07/14/2023
 ---
 
 # Add vector fields to a search index
@@ -39,7 +39,7 @@ Prior to indexing, assemble a document payload that includes vector data. The do
 
 1. Provide any other fields with alphanumeric content for any nonvector queries you want to support, as well as for hybrid query scenarios that include full text search or semantic ranking in the same request. 
 
-Your search index should include fields and content for all of the query scenarios you want to support. Suppose you want to search or filter over product names, versions, metadata, or addresses. In this case, similarity search isn't especially helpful and keyword search, geo-search, or filters would be a better choice. A search index that includes a comprehensive field collection of vector and non-vector data provides maximum flexibility for query construction.
+Your search index should include fields and content for all of the query scenarios you want to support. Suppose you want to search or filter over product names, versions, metadata, or addresses. In this case, similarity search isn't especially helpful. Keyword search, geo-search, or filters would be a better choice. A search index that includes a comprehensive field collection of vector and non-vector data provides maximum flexibility for query construction and response composition.
 
 ## Add a vector field to the fields collection
 
@@ -71,14 +71,18 @@ The schema must include fields for the document key, vector fields, and any othe
     }
    ```
 
-1. Add vector fields to the fields collection. You can store one generated embedding per document field. For each field:
+1. Add fields that define the substance and structure of the content you're indexing. At a minimum, you need a document key. 
 
-   + Assign the `Collection(Edm.Single)` data type
+   You should also add fields that are useful in the query response. The example below shows vector fields for title and content ("titleVector", "contentVector"). It also provides fields for equivalent textual content ("title", "content") that users can read in a search result.
+
+1. Add vector fields to the fields collection. You can store one generated embedding per document field. For each vector field:
+
+   + Assign the `Collection(Edm.Single)` data type.
+   + For `Collection(Edm.Single)`, the "filterable", "facetable", "sortable" attributes are "false" by default. Don't set them to "true" because those behaviors don't apply within the context of vector fields and the request will fail.
    + Provide the name of the vector search algorithm configuration.
    + Provide the number of dimensions generated by the embedding model.
    + "searchable" must be "true".
    + "retrievable" set to "true" allows you to display the raw vectors (for example, as a verification step), but doing so will increase storage usage. Set to "false" if you don't need to return raw vectors.
-   + For `Collection(Edm.Single)`, the "filterable", "facetable", "sortable" attributes are "false" by default. Don't set them to "true" because those behaviors don't apply within the context of vector fields and the request will fail.
 
     ```http
     PUT https://my-search-service.search.windows.net/indexes/my-index?api-version=2023-07-01-Preview&allowIndexDowntime=true
@@ -97,6 +101,8 @@ The schema must include fields for the document key, vector fields, and any othe
                 "name": "title",
                 "type": "Edm.String",
                 "searchable": true,
+                "filterable": true,
+                "sortable": true,
                 "retrievable": true
             },
             {

articles/search/vector-search-how-to-query.md

@@ -17,7 +17,7 @@ ms.date: 07/14/2023
 
 In Azure Cognitive Search, if you added vector fields to a search index, this article explains how to query those fields. It also explains how to combine vector queries with full text search and semantic search for hybrid query combination scenarios.
 
-Query execution in Cognitive Search doesn't include vector conversion. Encoding (text-to-vector) must be performed external to a search service. For both indexing and querying, your application code should call the same embedding model. To retrieve the text associated with a vector, remember that a query response can include non-vector fields in your search index. This allows you to query on a vector field (descriptionVector) but return the text field (description) in the response.
+Query execution in Cognitive Search doesn't include vector conversion. Encoding (text-to-vector) of the query string requires that you pass the text to an embedding model for vectorization. The output of the call to the embedding model is then passed to the search engine for similarity search over vector fields.
 
 ## Prerequisites
 
@@ -31,13 +31,13 @@ Query execution in Cognitive Search doesn't include vector conversion. Encoding
 
 ## Check your index for vector fields
 
-In the index schema, check for:
+If you aren't sure whether your search index already has vector fields, look for:
 
-+ A `vectorSearch` algorithm configuration.
++ A `vectorSearch` algorithm configuration embedded in the index schema.
 
 + In the fields collection, look for fields of type `Collection(Edm.Single)`, with a `dimensions` attribute and a `vectorSearchConfiguration` set to the name of the `vectorSearch` algorithm configuration used by the field.
 
-Search documents containing vector data have fields containing many hundreds of floating point values.
+You can also send an empty query (`search=*`) against the index. Search documents containing vector data have fields containing many hundreds of floating point values.
 
 ## Convert query input into a vector
 
@@ -54,7 +54,7 @@ api-key: {{admin-api-key}}
 }
 ```
 
-The expected response is 202 for a successful call to the deployed model. The body of the response provides the vector representation of the "input". The vector for the query is in the "embedding" field. For testing purposes, you would copy the embedding value into "vector.value" in a query request, using syntax from the next sections. Note that the actual response for this query included 1536 embeddings, trimmed here for brevity.
+The expected response is 202 for a successful call to the deployed model. The body of the response provides the vector representation of the "input". The vector for the query is in the "embedding" field. For testing purposes, you would copy the value of the "embedding" array into "vector.value" in a query request, using syntax shown in the next several sections. The actual response for this call to the deployment model includes 1536 embeddings, trimmed here for brevity.
 
 ```json
 {
@@ -79,6 +79,20 @@ The expected response is 202 for a successful call to the deployed model. The bo
 }
 ```
 
+## Design a query response
+
+When you're setting up the vector query, think about how you want to structure the response. Search results are composed of either all "retrievable" fields (a REST API default) or the fields explicitly listed in a "select" parameter. In the query examples that follow, each one includes a "select" parameter that specifies text (non-vector) content for the response.
+
+Vector fields themselves aren't human readable, so avoid returning them in the response. Instead, choose non-vector fields that provide equivalent information from the same search document. For example, if the query is on a vector field ("descriptionVector"), return an equivalent text field ("description") in the response.
+
+The quantity of results are determines by query parameters. Quantity is either: 
+
++ `"k": n` results for vector-only queries
++ `"top": n` results for hybrid queries
+
+> [!NOTE]
+> If you're familiar with full text search in Cognitive Search, you already know that a term or keyword, synonym, or filter criteria must match in order for a document to qualify as a match. Similarity search is less exacting because it's comparing vector compositions. It's possible for the HNSW model to sometimes return matches that don't seem especially relevant.
+
 ## Query syntax for vector search
 
 In this vector query, which is shortened for brevity, the "value" contains the vectorized text of the query input. The "fields" property specifies which vector fields are searched. The "k" property specifies the number of nearest neighbors to return as top hits.
@@ -107,6 +121,8 @@ api-key: {{admin-api-key}}
 
 The response includes 5 matches, and each result provides a search score, title, content, and category. In a similarity search, the response always includes "k" matches, even if the similarity is weak. For indexes that have fewer than "k" documents, only those number of documents will be returned.
 
+Notice that "select" returns textual fields from the index. Although the vector field is "retrievable" in this example, its content isn't usable as a search result.
+
 ## Query syntax for hybrid search
 
 A hybrid query combines full text search and vector search. The search engine runs full text and vector queries in parallel. All matches are evaluated for relevance using Reciprocal Rank Fusion (RRF) and a single result set is returned in the response.
@@ -145,7 +161,7 @@ api-key: {{admin-api-key}}
 
 ## Query syntax for vector query over multiple fields
 
-You can set "vector.fields" property to multiple vector fields. For example, the Postman collection has vector fields named titleVector and contentVector. Your vector query executes over both the titleVector and contentVector fields, which must have the same embedding space since they share the same query vector.
+You can set "vector.fields" property to multiple vector fields. For example, the Postman collection has vector fields named "titleVector" and "contentVector". Your vector query executes over both the "titleVector" and "contentVector" fields, which must have the same embedding space since they share the same query vector.
 
 ```http
 POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
@@ -170,7 +186,7 @@ api-key: {{admin-api-key}}
 
 ## Query syntax for multiple vector queries
 
-You can issue a search request containing multiple query vectors using the `vectors` query parameter. The queries execute concurrently in the search index, each one looking for similarities in the target vector fields. The result set is a union of the documents that matched both vector queries. A common example of this query request is when using models such as [CLIP](https://openai.com/research/clip) for a multi-modal vector search where the same model can vectorize image and non-image content.
+You can issue a search request containing multiple query vectors using the "vectors" query parameter. The queries execute concurrently in the search index, each one looking for similarities in the target vector fields. The result set is a union of the documents that matched both vector queries. A common example of this query request is when using models such as [CLIP](https://openai.com/research/clip) for a multi-modal vector search where the same model can vectorize image and non-image content.
 
 You must use REST for this scenario. Currently, there isn't support for multiple vector queries in the alpha SDKs.