Share via

SearchClient class

  • Reference
Package:
@azure/search-documents

Class used to perform operations against a search index, including querying documents in the index as well as adding, updating, and removing them.

Constructors

SearchClient<TModel>(string, string, KeyCredential | TokenCredential, SearchClientOptions)

Creates an instance of SearchClient.

Example usage:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<Admin Key>")
);

Optionally, the type of the model can be used to enable strong typing and type hints:

type TModel = {
  keyName: string;
  field1?: string | null;
  field2?: { anotherField?: string | null } | null;
};

const client = new SearchClient<TModel>(
  ...
);

Properties

apiVersion

The API version to use when communicating with the service.
endpoint

The endpoint of the search service
indexName

The name of the index
serviceVersion

The service version to use when communicating with the service.

Methods

autocomplete(string, string, AutocompleteOptions<TModel>)

Based on a partial searchText from the user, return a list of potential completion strings based on a specified suggester.

Example

import {
  AzureKeyCredential,
  SearchClient,
  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 }
);
deleteDocuments(keyof TModel, string[], IndexDocumentsOptions)

Delete a set of documents.
deleteDocuments(TModel[], IndexDocumentsOptions)

Delete a set of documents.
getDocument<TFields>(string, GetDocumentOptions<TModel, TFields>)

Retrieve a particular document from the index by key.
getDocumentsCount(OperationOptions)

Retrieves the number of documents in the index.
indexDocuments(IndexDocumentsBatch<TModel>, IndexDocumentsOptions)

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://docs.microsoft.com/en-us/rest/api/searchservice/AddUpdate-or-Delete-Documents
mergeDocuments(TModel[], IndexDocumentsOptions)

Update a set of documents in the index. For more details about how merging works, see https://docs.microsoft.com/en-us/rest/api/searchservice/AddUpdate-or-Delete-Documents
mergeOrUploadDocuments(TModel[], IndexDocumentsOptions)

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://docs.microsoft.com/en-us/rest/api/searchservice/AddUpdate-or-Delete-Documents
search<TFields>(string, SearchOptions<TModel, TFields>)

Performs a search on the current index given the specified arguments.

Example

import {
  AzureKeyCredential,
  SearchClient,
  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,
});
suggest<TFields>(string, string, SuggestOptions<TModel, TFields>)

Returns a short list of suggestions based on the searchText and specified suggester.

Example

import {
  AzureKeyCredential,
  SearchClient,
  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,
});
uploadDocuments(TModel[], IndexDocumentsOptions)

Upload an array of documents to the index.

Constructor Details

SearchClient<TModel>(string, string, KeyCredential | TokenCredential, SearchClientOptions)

Creates an instance of SearchClient.

Example usage:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<Admin Key>")
);

Optionally, the type of the model can be used to enable strong typing and type hints:

type TModel = {
  keyName: string;
  field1?: string | null;
  field2?: { anotherField?: string | null } | null;
};

const client = new SearchClient<TModel>(
  ...
);

new SearchClient(endpoint: string, indexName: string, credential: KeyCredential | TokenCredential, options?: SearchClientOptions)

Parameters

endpoint

string

The endpoint of the search service

indexName

string

The name of the index

credential

KeyCredential | TokenCredential

Used to authenticate requests to the service.

options
SearchClientOptions

Used to configure the Search client.

Property Details

apiVersion

Warning

This API is now deprecated.

use {@Link serviceVersion} instead

The API version to use when communicating with the service.

apiVersion: string

Property Value

string

endpoint

The endpoint of the search service

endpoint: string

Property Value

string

indexName

The name of the index

indexName: string

Property Value

string

serviceVersion

The service version to use when communicating with the service.

serviceVersion: string

Property Value

string

Method Details

autocomplete(string, string, AutocompleteOptions<TModel>)

Based on a partial searchText from the user, return a list of potential completion strings based on a specified suggester.

Example

import {
  AzureKeyCredential,
  SearchClient,
  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 }
);

function autocomplete(searchText: string, suggesterName: string, options?: AutocompleteOptions<TModel>): Promise<AutocompleteResult>

Parameters

searchText

string

The search text on which to base autocomplete results.

suggesterName

string

The name of the suggester as specified in the suggesters collection that's part of the index definition.

options

AutocompleteOptions<TModel>

Options to the autocomplete operation.

Returns

Promise<AutocompleteResult>

deleteDocuments(keyof TModel, string[], IndexDocumentsOptions)

Delete a set of documents.

function deleteDocuments(keyName: keyof TModel, keyValues: string[], options?: IndexDocumentsOptions): Promise<IndexDocumentsResult>

Parameters

keyName

keyof TModel

The name of their primary key in the index.

keyValues

string[]

The primary key values of documents to delete.

options
IndexDocumentsOptions

Additional options.

Returns

Promise<IndexDocumentsResult>

deleteDocuments(TModel[], IndexDocumentsOptions)

Delete a set of documents.

function deleteDocuments(documents: TModel[], options?: IndexDocumentsOptions): Promise<IndexDocumentsResult>

Parameters

documents

TModel[]

Documents to be deleted.

options
IndexDocumentsOptions

Additional options.

Returns

Promise<IndexDocumentsResult>

getDocument<TFields>(string, GetDocumentOptions<TModel, TFields>)

Retrieve a particular document from the index by key.

function getDocument<TFields>(key: string, options?: GetDocumentOptions<TModel, TFields>): Promise<NarrowedModel<TModel, TFields>>

Parameters

key

string

The primary key value of the document

options

GetDocumentOptions<TModel, TFields>

Additional options

Returns

Promise<NarrowedModel<TModel, TFields>>

getDocumentsCount(OperationOptions)

Retrieves the number of documents in the index.

function getDocumentsCount(options?: OperationOptions): Promise<number>

Parameters

options
OperationOptions

Options to the count operation.

Returns

Promise<number>

indexDocuments(IndexDocumentsBatch<TModel>, IndexDocumentsOptions)

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://docs.microsoft.com/en-us/rest/api/searchservice/AddUpdate-or-Delete-Documents

function indexDocuments(batch: IndexDocumentsBatch<TModel>, options?: IndexDocumentsOptions): Promise<IndexDocumentsResult>

Parameters

batch

IndexDocumentsBatch<TModel>

An array of actions to perform on the index.

options
IndexDocumentsOptions

Additional options.

Returns

Promise<IndexDocumentsResult>

mergeDocuments(TModel[], IndexDocumentsOptions)

Update a set of documents in the index. For more details about how merging works, see https://docs.microsoft.com/en-us/rest/api/searchservice/AddUpdate-or-Delete-Documents

function mergeDocuments(documents: TModel[], options?: IndexDocumentsOptions): Promise<IndexDocumentsResult>

Parameters

documents

TModel[]

The updated documents.

options
IndexDocumentsOptions

Additional options.

Returns

Promise<IndexDocumentsResult>

mergeOrUploadDocuments(TModel[], IndexDocumentsOptions)

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://docs.microsoft.com/en-us/rest/api/searchservice/AddUpdate-or-Delete-Documents

function mergeOrUploadDocuments(documents: TModel[], options?: IndexDocumentsOptions): Promise<IndexDocumentsResult>

Parameters

documents

TModel[]

The updated documents.

options
IndexDocumentsOptions

Additional options.

Returns

Promise<IndexDocumentsResult>

Performs a search on the current index given the specified arguments.

Example

import {
  AzureKeyCredential,
  SearchClient,
  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,
});

function search<TFields>(searchText?: string, options?: SearchOptions<TModel, TFields>): Promise<SearchDocumentsResult<TModel, TFields>>

Parameters

searchText

string

Text to search

options

SearchOptions<TModel, TFields>

Options for the search operation.

Returns

Promise<SearchDocumentsResult<TModel, TFields>>

suggest<TFields>(string, string, SuggestOptions<TModel, TFields>)

Returns a short list of suggestions based on the searchText and specified suggester.

Example

import {
  AzureKeyCredential,
  SearchClient,
  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,
});

function suggest<TFields>(searchText: string, suggesterName: string, options?: SuggestOptions<TModel, TFields>): Promise<SuggestDocumentsResult<TModel, TFields>>

Parameters

searchText

string

The search text to use to suggest documents. Must be at least 1 character, and no more than 100 characters.

suggesterName

string

The name of the suggester as specified in the suggesters collection that's part of the index definition.

options

SuggestOptions<TModel, TFields>

Options for the suggest operation

Returns

Promise<SuggestDocumentsResult<TModel, TFields>>

uploadDocuments(TModel[], IndexDocumentsOptions)

Upload an array of documents to the index.

function uploadDocuments(documents: TModel[], options?: IndexDocumentsOptions): Promise<IndexDocumentsResult>

Parameters

documents

TModel[]

The documents to upload.

options
IndexDocumentsOptions

Additional options.

Returns

Promise<IndexDocumentsResult>