Skip to content

Latest commit

 

History

History
112 lines (82 loc) · 5.58 KB

search-documents.md

File metadata and controls

112 lines (82 loc) · 5.58 KB

Search Documents

API Version: 2023-07-01-preview

This article supplements Search Documents (preview API) on learn.microsoft.com with content created for vector search scenarios. Limiting the amount of information makes it easier to find the new additions.

2023-07-01-preview adds:

  • "vector" queries

A query request targets the documents collection of a single index on a search service. It includes parameters that define the match criteria, and parameters that shape the response.

You must use POST for this preview.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?api-version=2023-07-01-preview  
  Content-Type: application/json  
  api-key: [admin or query key]

The size limit for POST is approximately 16 MB.

URI Parameters

Parameter Description
[service name] Required. Set this name to the unique, user-defined name of your search service.
[index name]/docs Required. Specifies the documents collection of a named index. The name of an index alias can also be used in place of the index name.
[query parameters] Query parameters are specified on the URI for GET requests and in the request body for POST requests.
api-version Required. Use 2023-07-01-preview for this preview.

Request Headers

The following table describes the required and optional request headers.

Fields Description
Content-Type Required. Set this to "application/json"
api-key Optional if you're using Azure roles and a bearer token is provided on the request, otherwise a key is required. An api-key is a unique, system-generated string that authenticates the request to your search service. Query requests against the documents collection can specify either an admin-key or query-key as the API key. The query-key is used for read-only operations against the documents collection. See Connect to Cognitive Search using key authentication for details.

Request Body

{  
     "answers": "none" (default) | "extractive", 
     "count": true | false (default),
     "captions": "none" (default) | "extractive",
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "featuresMode" : "disabled" (default) | "enabled",
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",
     "queryLanguage": "en-us" (default) | (a supported language code), 
     "queryType": "simple" (default) | "full" | "semantic",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" (default) | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "semanticConfiguration": "semantic_configuration_name",
     "sessionId" : "session_id",
     "skip": # (default 0), 
     "speller": "none" (default) | "lexicon",  
     "top": #  
   }

Query Parameters

Multiple query parameters (facet, $orderby,$count and $skip) aren't currently supported for vector search. See Preview limitations for the full list.

Name Type Description
queryType string Optional. This value is ignored for vector search, but applies to text search in hybrid scenarios.
search string Optional. This value is ignored for vector search, but applies to text search in hybrid scenarios.
vector object The query parameters for vector and hybrid search queries.
value array The vector representation of a search query. This representation must be formed externally. Cognitive Search does not create embeddings.
k Int The number of nearest neighbors to return as top hits.
fields string Vector fields of type Collection(Edm.Single) to be included in the query. This is conceptually similar to "searchFields" used to scope a query to specific fields in the index.

Response

Status Code: 200 OK is returned for a successful response.

Examples

Definitions

This section provides details about parameters that are too complex to cover in the main table.

Link Description
queryLanguage List of the supported languages for speller and semantic search.

See also