diff --git a/.changeset/search-es-new-client-docs.md b/.changeset/search-es-new-client-docs.md new file mode 100644 index 0000000000..b0a1025938 --- /dev/null +++ b/.changeset/search-es-new-client-docs.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-search-backend-module-elasticsearch': patch +--- + +Improved documentation on the `ElasticSearchSearchEngine.newClient()` method. diff --git a/docs/features/search/search-engines.md b/docs/features/search/search-engines.md index 2e7341a0d7..d06e401847 100644 --- a/docs/features/search/search-engines.md +++ b/docs/features/search/search-engines.md @@ -133,17 +133,25 @@ used internally by the Elasticsearch engine plugin. For example: ```typescript import { isOpenSearchCompatible } from '@backstage/plugin-search-backend-module-elasticsearch'; -import { Client as ElasticClient } from '@elastic/elastic-search'; +import { Client as ElasticClient } from '@elastic/elasticsearch'; import { Client as OpenSearchClient } from '@opensearch-project/opensearch'; -const client = searchEngine.newClient(options => { - // In reality, you would only import / instantiate one of the following, but - // for illustrative purposes, here are both: - if (isOpenSearchCompatible(options)) { - return new OpenSearchClient(options); - } else { +// Return an Elasticsearch client +const esClient = searchEngine.newClient(options => { + if (!isOpenSearchCompatible(options)) { return new ElasticClient(options); } + + throw new Error('Incompatible options'); +}); + +// Return an OpenSearch client +const osClient = searchEngine.newClient(options => { + if (isOpenSearchCompatible(options)) { + return new OpenSearchClient(options); + } + + throw new Error('Incompatible options'); }); ``` diff --git a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts index 0a2c2ce7df..9edad973de 100644 --- a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts +++ b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts @@ -171,9 +171,23 @@ export class ElasticSearchSearchEngine implements SearchEngine { } /** - * Create a custom search client from the derived elastic search - * configuration. This need not be the same client that the engine uses - * internally. + * Create a custom search client from the derived search client configuration. + * This need not be the same client that the engine uses internally. + * + * @example Instantiate an instance of an Elasticsearch client. + * ```ts + * import { isOpenSearchCompatible } from '@backstage/plugin-search-backend-module-elasticsearch'; + * import { Client } from '@elastic/elasticsearch'; + * + * const client = searchEngine.newClient(options => { + * // This typeguard ensures options are compatible with either OpenSearch + * // or Elasticsearch client constructors. + * if (!isOpenSearchCompatible(options)) { + * return new Client(options); + * } + * throw new Error('Incompatible options provided'); + * }); + * ``` */ newClient(create: (options: ElasticSearchClientOptions) => T): T { return create(this.elasticSearchClientOptions);