@azure/search-documents 11.3.1 → 12.0.0-alpha.20230306.2

package/dist-esm/src/searchClient.js

@@ -1,19 +1,17 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 import { __asyncDelegator, __asyncGenerator, __asyncValues, __await, __rest } from "tslib";
-/// <reference lib="esnext.asynciterable" />
-import { createPipelineFromOptions, operationOptionsToRequestOptionsBase, bearerTokenAuthenticationPolicy } from "@azure/core-http";
+import { bearerTokenAuthenticationPolicy } from "@azure/core-rest-pipeline";
 import { SearchClient as GeneratedClient } from "./generated/data/searchClient";
 import { isTokenCredential } from "@azure/core-auth";
 import { createSearchApiKeyCredentialPolicy } from "./searchApiKeyCredentialPolicy";
 import { SDK_VERSION } from "./constants";
 import { logger } from "./logger";
 import { createSpan } from "./tracing";
-import { SpanStatusCode } from "@azure/core-tracing";
 import { deserialize, serialize } from "./serialization";
-import { odataMetadataPolicy } from "./odataMetadataPolicy";
+import { createOdataMetadataPolicy } from "./odataMetadataPolicy";
 import { IndexDocumentsBatch } from "./indexDocumentsBatch";
-import { encode, decode } from "./base64";
+import { decode, encode } from "./base64";
 import * as utils from "./serviceUtils";
 import { KnownSearchAudience } from "./searchAudience";
 /**
@@ -32,21 +30,45 @@ export class SearchClient {
      * const client = new SearchClient(
      *   "<endpoint>",
      *   "<indexName>",
-     *   new AzureKeyCredential("<Admin Key>");
+     *   new AzureKeyCredential("<Admin Key>")
      * );
      * ```
+     *
+     * Optionally, the type of the model can be used to enable strong typing and type hints:
+     * ```ts
+     * type Model = {
+     *   keyName: string;
+     *   field1?: string | null;
+     *   field2?: { anotherField?: string | null } | null;
+     * };
+     *
+     * const client = new SearchClient<Model>(
+     *   ...
+     * );
+     * ```
+     *
      * @param endpoint - The endpoint of the search service
      * @param indexName - The name of the index
      * @param credential - Used to authenticate requests to the service.
      * @param options - Used to configure the Search client.
+     *
+     * @typeParam Model - An optional type that represents the documents stored in
+     * the search index. For the best typing experience, all non-key fields should
+     * be marked optional and nullable, and the key property should have the
+     * non-nullable type `string`.
      */
     constructor(endpoint, indexName, credential, options = {}) {
         /// Maintenance note: when updating supported API versions,
         /// the ContinuationToken logic will need to be updated below.
+        /**
+         *  The service version to use when communicating with the service.
+         */
+        this.serviceVersion = utils.defaultServiceVersion;
         /**
          * The API version to use when communicating with the service.
+         * @deprecated use {@Link serviceVersion} instead
          */
-        this.apiVersion = "2020-06-30-Preview";
+        this.apiVersion = utils.defaultServiceVersion;
         this.endpoint = endpoint;
         this.indexName = indexName;
         const libInfo = `azsdk-js-search-documents/${SDK_VERSION}`;
@@ -59,37 +81,44 @@ export class SearchClient {
         else {
             options.userAgentOptions.userAgentPrefix = libInfo;
         }
-        const internalPipelineOptions = Object.assign(Object.assign({}, options), {
+        const internalClientPipelineOptions = Object.assign(Object.assign({}, options), {
             loggingOptions: {
                 logger: logger.info,
-                allowedHeaderNames: [
+                additionalAllowedHeaderNames: [
                     "elapsed-time",
                     "Location",
                     "OData-MaxVersion",
                     "OData-Version",
                     "Prefer",
-                    "throttle-reason"
-                ]
-            }
+                    "throttle-reason",
+                ],
+            },
         });
-        const scope = options.audience
-            ? `${options.audience}/.default`
-            : `${KnownSearchAudience.AzurePublicCloud}/.default`;
-        const requestPolicyFactory = isTokenCredential(credential)
-            ? bearerTokenAuthenticationPolicy(credential, scope)
-            : createSearchApiKeyCredentialPolicy(credential);
-        const pipeline = createPipelineFromOptions(internalPipelineOptions, requestPolicyFactory);
-        if (Array.isArray(pipeline.requestPolicyFactories)) {
-            pipeline.requestPolicyFactories.unshift(odataMetadataPolicy("none"));
-        }
-        let apiVersion = this.apiVersion;
         if (options.apiVersion) {
-            if (!["2020-06-30-Preview", "2020-06-30"].includes(options.apiVersion)) {
+            if (!utils.serviceVersions.includes(options.apiVersion)) {
                 throw new Error(`Invalid Api Version: ${options.apiVersion}`);
             }
-            apiVersion = options.apiVersion;
+            this.serviceVersion = options.apiVersion;
+            this.apiVersion = options.apiVersion;
         }
-        this.client = new GeneratedClient(this.endpoint, this.indexName, apiVersion, pipeline);
+        if (options.serviceVersion) {
+            if (!utils.serviceVersions.includes(options.serviceVersion)) {
+                throw new Error(`Invalid Service Version: ${options.serviceVersion}`);
+            }
+            this.serviceVersion = options.serviceVersion;
+            this.apiVersion = options.serviceVersion;
+        }
+        this.client = new GeneratedClient(this.endpoint, this.indexName, this.serviceVersion, internalClientPipelineOptions);
+        if (isTokenCredential(credential)) {
+            const scope = options.audience
+                ? `${options.audience}/.default`
+                : `${KnownSearchAudience.AzurePublicCloud}/.default`;
+            this.client.pipeline.addPolicy(bearerTokenAuthenticationPolicy({ credential, scopes: scope }));
+        }
+        else {
+            this.client.pipeline.addPolicy(createSearchApiKeyCredentialPolicy(credential));
+        }
+        this.client.pipeline.addPolicy(createOdataMetadataPolicy("none"));
     }
     /**
      * Retrieves the number of documents in the index.
@@ -98,13 +127,19 @@ export class SearchClient {
     async getDocumentsCount(options = {}) {
         const { span, updatedOptions } = createSpan("SearchClient-getDocumentsCount", options);
         try {
-            const result = await this.client.documents.count(operationOptionsToRequestOptionsBase(updatedOptions));
-            return Number(result._response.bodyAsText);
+            let documentsCount = 0;
+            await this.client.documents.count(Object.assign(Object.assign({}, updatedOptions), { onResponse: (rawResponse, flatResponse) => {
+                    documentsCount = Number(rawResponse.bodyAsText);
+                    if (updatedOptions.onResponse) {
+                        updatedOptions.onResponse(rawResponse, flatResponse);
+                    }
+                } }));
+            return documentsCount;
         }
         catch (e) {
             span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: e.message
+                status: "error",
+                error: e.message,
             });
             throw e;
         }
@@ -118,6 +153,33 @@ export class SearchClient {
      * @param searchText - The search text on which to base autocomplete results.
      * @param suggesterName - The name of the suggester as specified in the suggesters collection that's part of the index definition.
      * @param options - Options to the autocomplete operation.
+     * @example
+     * ```ts
+     * import {
+     *   AzureKeyCredential,
+     *   SearchClient,
+     *   SelectFields,
+     * } from "@azure/search-documents";
+     *
+     * type Model = {
+     *   key: string;
+     *   azure?: { sdk: string | null } | null;
+     * };
+     *
+     * const client = new SearchClient<Model>(
+     *   "endpoint.azure",
+     *   "indexName",
+     *   new AzureKeyCredential("key")
+     * );
+     *
+     * const searchFields: SelectFields<Model>[] = ["azure/sdk"];
+     *
+     * const autocompleteResult = await client.autocomplete(
+     *   "searchText",
+     *   "suggesterName",
+     *   { searchFields }
+     * );
+     * ```
      */
     async autocomplete(searchText, suggesterName, options = {}) {
         const { operationOptions, restOptions } = this.extractOperationOptions(Object.assign({}, options));
@@ -131,13 +193,13 @@ export class SearchClient {
         }
         const { span, updatedOptions } = createSpan("SearchClient-autocomplete", operationOptions);
         try {
-            const result = await this.client.documents.autocompletePost(fullOptions, operationOptionsToRequestOptionsBase(updatedOptions));
+            const result = await this.client.documents.autocompletePost(fullOptions, updatedOptions);
             return result;
         }
         catch (e) {
             span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: e.message
+                status: "error",
+                error: e.message,
             });
             throw e;
         }
@@ -147,26 +209,27 @@ export class SearchClient {
     }
     async searchDocuments(searchText, options = {}, nextPageParameters = {}) {
         const { operationOptions, restOptions } = this.extractOperationOptions(Object.assign({}, options));
-        const { select, searchFields, orderBy } = restOptions, nonFieldOptions = __rest(restOptions, ["select", "searchFields", "orderBy"]);
-        const fullOptions = Object.assign(Object.assign({ searchFields: this.convertSearchFields(searchFields), select: this.convertSelect(select), orderBy: this.convertOrderBy(orderBy) }, nonFieldOptions), nextPageParameters);
+        const { select, searchFields, orderBy, semanticFields } = restOptions, nonFieldOptions = __rest(restOptions, ["select", "searchFields", "orderBy", "semanticFields"]);
+        const fullOptions = Object.assign(Object.assign({ searchFields: this.convertSearchFields(searchFields), semanticFields: this.convertSemanticFields(semanticFields), select: this.convertSelect(select) || "*", orderBy: this.convertOrderBy(orderBy) }, nonFieldOptions), nextPageParameters);
         const { span, updatedOptions } = createSpan("SearchClient-searchDocuments", operationOptions);
         try {
-            const result = await this.client.documents.searchPost(Object.assign(Object.assign({}, fullOptions), { includeTotalResultCount: fullOptions.includeTotalCount, searchText: searchText }), operationOptionsToRequestOptionsBase(updatedOptions));
-            const { results, count, coverage, facets, nextLink } = result;
+            const result = await this.client.documents.searchPost(Object.assign(Object.assign({}, fullOptions), { includeTotalResultCount: fullOptions.includeTotalCount, searchText: searchText }), updatedOptions);
+            const { results, count, coverage, facets, answers, nextLink } = result;
             const modifiedResults = utils.generatedSearchResultToPublicSearchResult(results);
             const converted = {
                 results: modifiedResults,
                 count,
                 coverage,
                 facets,
-                continuationToken: this.encodeContinuationToken(nextLink, result.nextPageParameters)
+                answers,
+                continuationToken: this.encodeContinuationToken(nextLink, result.nextPageParameters),
             };
             return deserialize(converted);
         }
         catch (e) {
             span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: e.message
+                status: "error",
+                error: e.message,
             });
             throw e;
         }
@@ -195,7 +258,7 @@ export class SearchClient {
             if (firstPage.continuationToken) {
                 try {
                     for (var _b = __asyncValues(this.listSearchResultsPage(searchText, options, {
-                        continuationToken: firstPage.continuationToken
+                        continuationToken: firstPage.continuationToken,
                     })), _c; _c = yield __await(_b.next()), !_c.done;) {
                         const page = _c.value;
                         yield __await(yield* __asyncDelegator(__asyncValues(page.results)));
@@ -222,7 +285,7 @@ export class SearchClient {
             },
             byPage: (settings = {}) => {
                 return this.listSearchResultsPage(searchText, options, settings);
-            }
+            },
         };
     }
     /**
@@ -230,23 +293,51 @@ export class SearchClient {
      * the specified arguments.
      * @param searchText - Text to search
      * @param options - Options for the search operation.
+     * @example
+     * ```ts
+     * import {
+     *   AzureKeyCredential,
+     *   SearchClient,
+     *   SelectFields,
+     * } from "@azure/search-documents";
+     *
+     * type Model = {
+     *   key: string;
+     *   azure?: { sdk: string | null } | null;
+     * };
+     *
+     * const client = new SearchClient<Model>(
+     *   "endpoint.azure",
+     *   "indexName",
+     *   new AzureKeyCredential("key")
+     * );
+     *
+     * const select = ["azure/sdk"] as const;
+     * const searchFields: SelectFields<Model>[] = ["azure/sdk"];
+     *
+     * const searchResult = await client.search("searchText", {
+     *   select,
+     *   searchFields,
+     * });
+     * ```
      */
-    async search(searchText, options = {}) {
+    async search(searchText, options) {
         const { span, updatedOptions } = createSpan("SearchClient-search", options);
         try {
             const pageResult = await this.searchDocuments(searchText, updatedOptions);
-            const { count, coverage, facets } = pageResult;
+            const { count, coverage, facets, answers } = pageResult;
             return {
                 count,
                 coverage,
                 facets,
-                results: this.listSearchResults(pageResult, searchText, updatedOptions)
+                answers,
+                results: this.listSearchResults(pageResult, searchText, updatedOptions),
             };
         }
         catch (e) {
             span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: e.message
+                status: "error",
+                error: e.message,
             });
             throw e;
         }
@@ -260,6 +351,33 @@ export class SearchClient {
      * @param searchText - The search text to use to suggest documents. Must be at least 1 character, and no more than 100 characters.
      * @param suggesterName - The name of the suggester as specified in the suggesters collection that's part of the index definition.
      * @param options - Options for the suggest operation
+     * @example
+     * ```ts
+     * import {
+     *   AzureKeyCredential,
+     *   SearchClient,
+     *   SelectFields,
+     * } from "@azure/search-documents";
+     *
+     * type Model = {
+     *   key: string;
+     *   azure?: { sdk: string | null } | null;
+     * };
+     *
+     * const client = new SearchClient<Model>(
+     *   "endpoint.azure",
+     *   "indexName",
+     *   new AzureKeyCredential("key")
+     * );
+     *
+     * const select = ["azure/sdk"] as const;
+     * const searchFields: SelectFields<Model>[] = ["azure/sdk"];
+     *
+     * const suggestResult = await client.suggest("searchText", "suggesterName", {
+     *   select,
+     *   searchFields,
+     * });
+     * ```
      */
     async suggest(searchText, suggesterName, options = {}) {
         const { operationOptions, restOptions } = this.extractOperationOptions(Object.assign({}, options));
@@ -273,14 +391,14 @@ export class SearchClient {
         }
         const { span, updatedOptions } = createSpan("SearchClient-suggest", operationOptions);
         try {
-            const result = await this.client.documents.suggestPost(fullOptions, operationOptionsToRequestOptionsBase(updatedOptions));
+            const result = await this.client.documents.suggestPost(fullOptions, updatedOptions);
             const modifiedResult = utils.generatedSuggestDocumentsResultToPublicSuggestDocumentsResult(result);
             return deserialize(modifiedResult);
         }
         catch (e) {
             span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: e.message
+                status: "error",
+                error: e.message,
             });
             throw e;
         }
@@ -296,13 +414,13 @@ export class SearchClient {
     async getDocument(key, options = {}) {
         const { span, updatedOptions } = createSpan("SearchClient-getDocument", options);
         try {
-            const result = await this.client.documents.get(key, operationOptionsToRequestOptionsBase(updatedOptions));
-            return deserialize(result.body);
+            const result = await this.client.documents.get(key, Object.assign(Object.assign({}, updatedOptions), { selectedFields: updatedOptions.selectedFields }));
+            return deserialize(result);
         }
         catch (e) {
             span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: e.message
+                status: "error",
+                error: e.message,
             });
             throw e;
         }
@@ -325,16 +443,22 @@ export class SearchClient {
     batch, options = {}) {
         const { span, updatedOptions } = createSpan("SearchClient-indexDocuments", options);
         try {
-            const result = await this.client.documents.index({ actions: serialize(batch.actions) }, operationOptionsToRequestOptionsBase(updatedOptions));
-            if (options.throwOnAnyFailure && result._response.status === 207) {
+            let status = 0;
+            const result = await this.client.documents.index({ actions: serialize(batch.actions) }, Object.assign(Object.assign({}, updatedOptions), { onResponse: (rawResponse, flatResponse) => {
+                    status = rawResponse.status;
+                    if (updatedOptions.onResponse) {
+                        updatedOptions.onResponse(rawResponse, flatResponse);
+                    }
+                } }));
+            if (options.throwOnAnyFailure && status === 207) {
                 throw result;
             }
             return result;
         }
         catch (e) {
             span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: e.message
+                status: "error",
+                error: e.message,
             });
             throw e;
         }
@@ -356,8 +480,8 @@ export class SearchClient {
         }
         catch (e) {
             span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: e.message
+                status: "error",
+                error: e.message,
             });
             throw e;
         }
@@ -380,8 +504,8 @@ export class SearchClient {
         }
         catch (e) {
             span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: e.message
+                status: "error",
+                error: e.message,
             });
             throw e;
         }
@@ -404,8 +528,8 @@ export class SearchClient {
         }
         catch (e) {
             span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: e.message
+                status: "error",
+                error: e.message,
             });
             throw e;
         }
@@ -427,8 +551,8 @@ export class SearchClient {
         }
         catch (e) {
             span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: e.message
+                status: "error",
+                error: e.message,
             });
             throw e;
         }
@@ -443,7 +567,7 @@ export class SearchClient {
         const payload = JSON.stringify({
             apiVersion: this.apiVersion,
             nextLink,
-            nextPageParameters
+            nextPageParameters,
         });
         return encode(payload);
     }
@@ -459,7 +583,7 @@ export class SearchClient {
             }
             return {
                 nextLink: result.nextLink,
-                nextPageParameters: result.nextPageParameters
+                nextPageParameters: result.nextPageParameters,
             };
         }
         catch (e) {
@@ -473,9 +597,9 @@ export class SearchClient {
             operationOptions: {
                 abortSignal,
                 requestOptions,
-                tracingOptions
+                tracingOptions,
             },
-            restOptions
+            restOptions,
         };
     }
     convertSelect(select) {
@@ -490,6 +614,12 @@ export class SearchClient {
         }
         return searchFields;
     }
+    convertSemanticFields(semanticFields) {
+        if (semanticFields) {
+            return semanticFields.join(",");
+        }
+        return semanticFields;
+    }
     convertOrderBy(orderBy) {
         if (orderBy) {
             return orderBy.join(",");