@azure/search-documents 12.2.0-beta.1 → 12.2.0-beta.3

package/dist/commonjs/searchClient.js

@@ -0,0 +1,729 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchClient = void 0;
+const tslib_1 = require("tslib");
+const core_auth_1 = require("@azure/core-auth");
+const core_rest_pipeline_1 = require("@azure/core-rest-pipeline");
+const base64_js_1 = require("./base64.js");
+const searchClient_js_1 = require("./generated/data/searchClient.js");
+const indexDocumentsBatch_js_1 = require("./indexDocumentsBatch.js");
+const logger_js_1 = require("./logger.js");
+const odataMetadataPolicy_js_1 = require("./odataMetadataPolicy.js");
+const searchApiKeyCredentialPolicy_js_1 = require("./searchApiKeyCredentialPolicy.js");
+const searchAudience_js_1 = require("./searchAudience.js");
+const serialization_js_1 = require("./serialization.js");
+const utils = tslib_1.__importStar(require("./serviceUtils.js"));
+const tracing_js_1 = require("./tracing.js");
+/**
+ * Class used to perform operations against a search index,
+ * including querying documents in the index as well as
+ * adding, updating, and removing them.
+ */
+class SearchClient {
+    /// 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.
+     */
+    serviceVersion = utils.defaultServiceVersion;
+    /**
+     * The API version to use when communicating with the service.
+     * @deprecated use {@Link serviceVersion} instead
+     */
+    apiVersion = utils.defaultServiceVersion;
+    /**
+     * The endpoint of the search service
+     */
+    endpoint;
+    /**
+     * The name of the index
+     */
+    indexName;
+    /**
+     * @hidden
+     * A reference to the auto-generated SearchClient
+     */
+    client;
+    /**
+     * A reference to the internal HTTP pipeline for use with raw requests
+     */
+    pipeline;
+    /**
+     * Creates an instance of SearchClient.
+     *
+     * Example usage:
+     * ```ts snippet:ReadmeSampleSearchClient
+     * import { SearchClient, AzureKeyCredential } from "@azure/search-documents";
+     *
+     * const searchClient = new SearchClient(
+     *   "<endpoint>",
+     *   "<indexName>",
+     *   new AzureKeyCredential("<apiKey>"),
+     * );
+     * ```
+     *
+     * Optionally, the type of the model can be used to enable strong typing and type hints:
+     * ```ts snippet:ReadmeSampleSearchClientWithModel
+     * import { SearchClient, AzureKeyCredential } from "@azure/search-documents";
+     *
+     * type TModel = {
+     *   keyName: string;
+     *   field1?: string | null;
+     *   field2?: {
+     *     anotherField?: string | null;
+     *   } | null;
+     * };
+     *
+     * const searchClient = new SearchClient<TModel>(
+     *   "<endpoint>",
+     *   "<indexName>",
+     *   new AzureKeyCredential("<apiKey>"),
+     * );
+     * ```
+     *
+     * @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 TModel - 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 = {}) {
+        this.endpoint = endpoint;
+        this.indexName = indexName;
+        const internalClientPipelineOptions = {
+            ...options,
+            ...{
+                loggingOptions: {
+                    logger: logger_js_1.logger.info,
+                    additionalAllowedHeaderNames: [
+                        "elapsed-time",
+                        "Location",
+                        "OData-MaxVersion",
+                        "OData-Version",
+                        "Prefer",
+                        "throttle-reason",
+                    ],
+                },
+            },
+        };
+        this.serviceVersion =
+            options.serviceVersion ?? options.apiVersion ?? utils.defaultServiceVersion;
+        this.apiVersion = this.serviceVersion;
+        this.client = new searchClient_js_1.SearchClient(this.endpoint, this.indexName, this.serviceVersion, internalClientPipelineOptions);
+        this.pipeline = this.client.pipeline;
+        if ((0, core_auth_1.isTokenCredential)(credential)) {
+            const scope = options.audience
+                ? `${options.audience}/.default`
+                : `${searchAudience_js_1.KnownSearchAudience.AzurePublicCloud}/.default`;
+            this.client.pipeline.addPolicy((0, core_rest_pipeline_1.bearerTokenAuthenticationPolicy)({ credential, scopes: scope }));
+        }
+        else {
+            this.client.pipeline.addPolicy((0, searchApiKeyCredentialPolicy_js_1.createSearchApiKeyCredentialPolicy)(credential));
+        }
+        this.client.pipeline.addPolicy((0, odataMetadataPolicy_js_1.createOdataMetadataPolicy)("none"));
+    }
+    /**
+     * Retrieves the number of documents in the index.
+     * @param options - Options to the count operation.
+     */
+    // eslint-disable-next-line @azure/azure-sdk/ts-naming-options
+    async getDocumentsCount(options = {}) {
+        const { span, updatedOptions } = (0, tracing_js_1.createSpan)("SearchClient-getDocumentsCount", options);
+        try {
+            let documentsCount = 0;
+            await this.client.documents.count({
+                ...updatedOptions,
+                onResponse: (rawResponse, flatResponse) => {
+                    documentsCount = Number(rawResponse.bodyAsText);
+                    if (updatedOptions.onResponse) {
+                        updatedOptions.onResponse(rawResponse, flatResponse);
+                    }
+                },
+            });
+            return documentsCount;
+        }
+        catch (e) {
+            span.setStatus({
+                status: "error",
+                error: e.message,
+            });
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Based on a partial searchText from the user, return a list of potential completion strings
+     * based on a specified suggester.
+     * @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 snippet:ReadmeSampleAutocomplete
+     * import { SearchClient, AzureKeyCredential, SearchFieldArray } from "@azure/search-documents";
+     *
+     * type TModel = {
+     *   key: string;
+     *   azure?: {
+     *     sdk: string | null;
+     *   } | null;
+     * };
+     *
+     * const client = new SearchClient<TModel>(
+     *   "endpoint.azure",
+     *   "indexName",
+     *   new AzureKeyCredential("key"),
+     * );
+     *
+     * const searchFields: SearchFieldArray<TModel> = ["azure/sdk"];
+     *
+     * const autocompleteResult = await client.autocomplete("searchText", "suggesterName", {
+     *   searchFields,
+     * });
+     * ```
+     */
+    async autocomplete(searchText, suggesterName, options = {}) {
+        const { searchFields, ...nonFieldOptions } = options;
+        const fullOptions = {
+            searchText: searchText,
+            suggesterName: suggesterName,
+            searchFields: this.convertSearchFields(searchFields),
+            ...nonFieldOptions,
+        };
+        if (!fullOptions.searchText) {
+            throw new RangeError("searchText must be provided.");
+        }
+        if (!fullOptions.suggesterName) {
+            throw new RangeError("suggesterName must be provided.");
+        }
+        const { span, updatedOptions } = (0, tracing_js_1.createSpan)("SearchClient-autocomplete", options);
+        try {
+            const result = await this.client.documents.autocompletePost(fullOptions, updatedOptions);
+            return result;
+        }
+        catch (e) {
+            span.setStatus({
+                status: "error",
+                error: e.message,
+            });
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    }
+    async searchDocuments(searchText, options = {}, nextPageParameters = {}) {
+        const { includeTotalCount, orderBy, searchFields, select, vectorSearchOptions, semanticSearchOptions, hybridSearch, ...restOptions } = options;
+        const { semanticFields, configurationName, errorMode, answers, captions, debugMode, queryRewrites, ...restSemanticOptions } = semanticSearchOptions ?? {};
+        const { queries, filterMode, ...restVectorOptions } = vectorSearchOptions ?? {};
+        const fullOptions = {
+            ...restSemanticOptions,
+            ...restVectorOptions,
+            ...restOptions,
+            ...nextPageParameters,
+            searchFields: this.convertSearchFields(searchFields),
+            semanticFields: this.convertSemanticFields(semanticFields),
+            select: this.convertSelect(select) || "*",
+            orderBy: this.convertOrderBy(orderBy),
+            includeTotalResultCount: includeTotalCount,
+            vectorQueries: queries?.map(this.convertVectorQuery.bind(this)),
+            answers: this.convertQueryAnswers(answers),
+            captions: this.convertQueryCaptions(captions),
+            semanticErrorHandling: errorMode,
+            semanticConfigurationName: configurationName,
+            debug: debugMode,
+            queryRewrites: this.convertQueryRewrites(queryRewrites),
+            vectorFilterMode: filterMode,
+            hybridSearch: hybridSearch,
+        };
+        const { span, updatedOptions } = (0, tracing_js_1.createSpan)("SearchClient-searchDocuments", options);
+        try {
+            const result = await this.client.documents.searchPost({
+                ...fullOptions,
+                searchText: searchText,
+            }, updatedOptions);
+            const { results, nextLink, nextPageParameters: resultNextPageParameters, semanticPartialResponseReason: semanticErrorReason, semanticPartialResponseType: semanticSearchResultsType, ...restResult } = result;
+            const modifiedResults = utils.generatedSearchResultToPublicSearchResult(results);
+            const converted = {
+                ...restResult,
+                results: modifiedResults,
+                semanticErrorReason,
+                semanticSearchResultsType,
+                continuationToken: this.encodeContinuationToken(nextLink, resultNextPageParameters),
+            };
+            return (0, serialization_js_1.deserialize)(converted);
+        }
+        catch (e) {
+            span.setStatus({
+                status: "error",
+                error: e.message,
+            });
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    }
+    async *listSearchResultsPage(searchText, options = {}, settings = {}) {
+        let decodedContinuation = this.decodeContinuationToken(settings.continuationToken);
+        let result = await this.searchDocuments(searchText, options, decodedContinuation?.nextPageParameters);
+        yield result;
+        // Technically, we should also leverage nextLink, but the generated code
+        // doesn't support this yet.
+        while (result.continuationToken) {
+            decodedContinuation = this.decodeContinuationToken(result.continuationToken);
+            result = await this.searchDocuments(searchText, options, decodedContinuation?.nextPageParameters);
+            yield result;
+        }
+    }
+    async *listSearchResultsAll(firstPage, searchText, options = {}) {
+        yield* firstPage.results;
+        if (firstPage.continuationToken) {
+            for await (const page of this.listSearchResultsPage(searchText, options, {
+                continuationToken: firstPage.continuationToken,
+            })) {
+                yield* page.results;
+            }
+        }
+    }
+    listSearchResults(firstPage, searchText, options = {}) {
+        const iter = this.listSearchResultsAll(firstPage, searchText, options);
+        return {
+            next() {
+                return iter.next();
+            },
+            [Symbol.asyncIterator]() {
+                return this;
+            },
+            byPage: (settings = {}) => {
+                return this.listSearchResultsPage(searchText, options, settings);
+            },
+        };
+    }
+    /**
+     * Performs a search on the current index given
+     * the specified arguments.
+     * @param searchText - Text to search
+     * @param options - Options for the search operation.
+     * @example
+     * ```ts snippet:ReadmeSampleSearchTModel
+     * import { SearchClient, AzureKeyCredential, SearchFieldArray } from "@azure/search-documents";
+     *
+     * type TModel = {
+     *   key: string;
+     *   azure?: {
+     *     sdk: string | null;
+     *   } | null;
+     * };
+     *
+     * const client = new SearchClient<TModel>(
+     *   "endpoint.azure",
+     *   "indexName",
+     *   new AzureKeyCredential("key"),
+     * );
+     *
+     * const select = ["azure/sdk"] as const;
+     * const searchFields: SearchFieldArray<TModel> = ["azure/sdk"];
+     *
+     * const searchResult = await client.search("searchText", {
+     *   select,
+     *   searchFields,
+     * });
+     * ```
+     */
+    async search(searchText, options) {
+        const { span, updatedOptions } = (0, tracing_js_1.createSpan)("SearchClient-search", options);
+        try {
+            const pageResult = await this.searchDocuments(searchText, updatedOptions);
+            return {
+                ...pageResult,
+                results: this.listSearchResults(pageResult, searchText, updatedOptions),
+            };
+        }
+        catch (e) {
+            span.setStatus({
+                status: "error",
+                error: e.message,
+            });
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Returns a short list of suggestions based on the searchText and specified suggester.
+     * @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 snippet:ReadmeSampleSuggest
+     * import { SearchClient, AzureKeyCredential, SearchFieldArray } from "@azure/search-documents";
+     *
+     * type TModel = {
+     *   key: string;
+     *   azure?: {
+     *     sdk: string | null;
+     *   } | null;
+     * };
+     *
+     * const client = new SearchClient<TModel>(
+     *   "endpoint.azure",
+     *   "indexName",
+     *   new AzureKeyCredential("key"),
+     * );
+     *
+     * const select = ["azure/sdk"] as const;
+     * const searchFields: SearchFieldArray<TModel> = ["azure/sdk"];
+     *
+     * const suggestResult = await client.suggest("searchText", "suggesterName", {
+     *   select,
+     *   searchFields,
+     * });
+     * ```
+     */
+    async suggest(searchText, suggesterName, options = {}) {
+        const { select, searchFields, orderBy, ...nonFieldOptions } = options;
+        const fullOptions = {
+            searchText: searchText,
+            suggesterName: suggesterName,
+            searchFields: this.convertSearchFields(searchFields),
+            select: this.convertSelect(select),
+            orderBy: this.convertOrderBy(orderBy),
+            ...nonFieldOptions,
+        };
+        if (!fullOptions.searchText) {
+            throw new RangeError("searchText must be provided.");
+        }
+        if (!fullOptions.suggesterName) {
+            throw new RangeError("suggesterName must be provided.");
+        }
+        const { span, updatedOptions } = (0, tracing_js_1.createSpan)("SearchClient-suggest", options);
+        try {
+            const result = await this.client.documents.suggestPost(fullOptions, updatedOptions);
+            const modifiedResult = utils.generatedSuggestDocumentsResultToPublicSuggestDocumentsResult(result);
+            return (0, serialization_js_1.deserialize)(modifiedResult);
+        }
+        catch (e) {
+            span.setStatus({
+                status: "error",
+                error: e.message,
+            });
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Retrieve a particular document from the index by key.
+     * @param key - The primary key value of the document
+     * @param options - Additional options
+     */
+    async getDocument(key, options = {}) {
+        const { span, updatedOptions } = (0, tracing_js_1.createSpan)("SearchClient-getDocument", options);
+        try {
+            const result = await this.client.documents.get(key, {
+                ...updatedOptions,
+                selectedFields: updatedOptions.selectedFields,
+            });
+            return (0, serialization_js_1.deserialize)(result);
+        }
+        catch (e) {
+            span.setStatus({
+                status: "error",
+                error: e.message,
+            });
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Perform a set of index modifications (upload, merge, mergeOrUpload, delete)
+     * for the given set of documents.
+     * This operation may partially succeed and not all document operations will
+     * be reflected in the index. If you would like to treat this as an exception,
+     * set the `throwOnAnyFailure` option to true.
+     * For more details about how merging works, see: https://learn.microsoft.com/rest/api/searchservice/AddUpdate-or-Delete-Documents
+     * @param batch - An array of actions to perform on the index.
+     * @param options - Additional options.
+     */
+    async indexDocuments(
+    // eslint-disable-next-line @azure/azure-sdk/ts-use-interface-parameters
+    batch, options = {}) {
+        const { span, updatedOptions } = (0, tracing_js_1.createSpan)("SearchClient-indexDocuments", options);
+        try {
+            let status = 0;
+            const result = await this.client.documents.index({ actions: (0, serialization_js_1.serialize)(batch.actions) }, {
+                ...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({
+                status: "error",
+                error: e.message,
+            });
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Upload an array of documents to the index.
+     * @param documents - The documents to upload.
+     * @param options - Additional options.
+     */
+    async uploadDocuments(documents, options = {}) {
+        const { span, updatedOptions } = (0, tracing_js_1.createSpan)("SearchClient-uploadDocuments", options);
+        const batch = new indexDocumentsBatch_js_1.IndexDocumentsBatch();
+        batch.upload(documents);
+        try {
+            return await this.indexDocuments(batch, updatedOptions);
+        }
+        catch (e) {
+            span.setStatus({
+                status: "error",
+                error: e.message,
+            });
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Update a set of documents in the index.
+     *
+     * For more details about how merging works, see
+     * https://learn.microsoft.com/rest/api/searchservice/AddUpdate-or-Delete-Documents
+     * @param documents - The updated documents.
+     * @param options - Additional options.
+     */
+    async mergeDocuments(documents, options = {}) {
+        const { span, updatedOptions } = (0, tracing_js_1.createSpan)("SearchClient-mergeDocuments", options);
+        const batch = new indexDocumentsBatch_js_1.IndexDocumentsBatch();
+        batch.merge(documents);
+        try {
+            return await this.indexDocuments(batch, updatedOptions);
+        }
+        catch (e) {
+            span.setStatus({
+                status: "error",
+                error: e.message,
+            });
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Update a set of documents in the index or upload them if they don't exist.
+     *
+     * For more details about how merging works, see
+     * https://learn.microsoft.com/rest/api/searchservice/AddUpdate-or-Delete-Documents
+     * @param documents - The updated documents.
+     * @param options - Additional options.
+     */
+    async mergeOrUploadDocuments(documents, options = {}) {
+        const { span, updatedOptions } = (0, tracing_js_1.createSpan)("SearchClient-mergeDocuments", options);
+        const batch = new indexDocumentsBatch_js_1.IndexDocumentsBatch();
+        batch.mergeOrUpload(documents);
+        try {
+            return await this.indexDocuments(batch, updatedOptions);
+        }
+        catch (e) {
+            span.setStatus({
+                status: "error",
+                error: e.message,
+            });
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    }
+    async deleteDocuments(keyNameOrDocuments, keyValuesOrOptions, options = {}) {
+        const { span, updatedOptions } = (0, tracing_js_1.createSpan)("SearchClient-deleteDocuments", options);
+        const batch = new indexDocumentsBatch_js_1.IndexDocumentsBatch();
+        if (typeof keyNameOrDocuments === "string") {
+            batch.delete(keyNameOrDocuments, keyValuesOrOptions);
+        }
+        else {
+            batch.delete(keyNameOrDocuments);
+        }
+        try {
+            return await this.indexDocuments(batch, updatedOptions);
+        }
+        catch (e) {
+            span.setStatus({
+                status: "error",
+                error: e.message,
+            });
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    }
+    encodeContinuationToken(nextLink, nextPageParameters) {
+        if (!nextLink || !nextPageParameters) {
+            return undefined;
+        }
+        const payload = JSON.stringify({
+            apiVersion: this.apiVersion,
+            nextLink,
+            nextPageParameters,
+        });
+        return (0, base64_js_1.encode)(payload);
+    }
+    decodeContinuationToken(token) {
+        if (!token) {
+            return undefined;
+        }
+        const decodedToken = (0, base64_js_1.decode)(token);
+        try {
+            const result = JSON.parse(decodedToken);
+            if (result.apiVersion !== this.apiVersion) {
+                throw new RangeError(`Continuation token uses unsupported apiVersion "${this.apiVersion}"`);
+            }
+            return {
+                nextLink: result.nextLink,
+                nextPageParameters: result.nextPageParameters,
+            };
+        }
+        catch (e) {
+            throw new Error(`Corrupted or invalid continuation token: ${decodedToken}`);
+        }
+    }
+    convertSelect(select) {
+        if (select) {
+            return select.join(",");
+        }
+        return select;
+    }
+    convertVectorQueryFields(fields) {
+        if (fields) {
+            return fields.join(",");
+        }
+        return fields;
+    }
+    convertSearchFields(searchFields) {
+        if (searchFields) {
+            return searchFields.join(",");
+        }
+        return searchFields;
+    }
+    convertSemanticFields(semanticFields) {
+        if (semanticFields) {
+            return semanticFields.join(",");
+        }
+        return semanticFields;
+    }
+    convertOrderBy(orderBy) {
+        if (orderBy) {
+            return orderBy.join(",");
+        }
+        return orderBy;
+    }
+    convertQueryAnswers(answers) {
+        if (!answers) {
+            return answers;
+        }
+        const config = [];
+        const { answerType: output, count, threshold, maxAnswerLength } = answers;
+        if (count) {
+            config.push(`count-${count}`);
+        }
+        if (threshold) {
+            config.push(`threshold-${threshold}`);
+        }
+        if (maxAnswerLength) {
+            config.push(`maxcharlength-${maxAnswerLength}`);
+        }
+        if (config.length) {
+            return output + `|${config.join(",")}`;
+        }
+        return output;
+    }
+    convertQueryCaptions(captions) {
+        if (!captions) {
+            return captions;
+        }
+        const config = [];
+        const { captionType: output, highlight, maxCaptionLength } = captions;
+        if (highlight !== undefined) {
+            config.push(`highlight-${highlight}`);
+        }
+        if (maxCaptionLength) {
+            config.push(`maxcharlength-${maxCaptionLength}`);
+        }
+        if (config.length) {
+            return output + `|${config.join(",")}`;
+        }
+        return output;
+    }
+    convertVectorQuery(vectorQuery) {
+        switch (vectorQuery.kind) {
+            case "text": {
+                const { fields, queryRewrites, ...restFields } = vectorQuery;
+                return {
+                    ...restFields,
+                    fields: this.convertVectorQueryFields(fields),
+                    queryRewrites: this.convertQueryRewrites(queryRewrites),
+                };
+            }
+            case "vector":
+            case "imageUrl":
+            case "imageBinary": {
+                return { ...vectorQuery, fields: this.convertVectorQueryFields(vectorQuery?.fields) };
+            }
+            default: {
+                logger_js_1.logger.warning("Unknown vector query kind; sending without serialization");
+                return vectorQuery;
+            }
+        }
+    }
+    convertQueryRewrites(queryRewrites) {
+        if (!queryRewrites) {
+            return queryRewrites;
+        }
+        const { rewritesType: baseOutput } = queryRewrites;
+        switch (baseOutput) {
+            case "generative": {
+                const { count } = queryRewrites;
+                const config = [...(count === undefined ? [] : [`count-${count}`])];
+                if (config.length)
+                    return baseOutput + `|${config.join(",")}`;
+                return baseOutput;
+            }
+            default:
+                return baseOutput;
+        }
+    }
+}
+exports.SearchClient = SearchClient;
+//# sourceMappingURL=searchClient.js.map