diff --git a/docs/features/search/search-engines.md b/docs/features/search/search-engines.md index a5ff780c8a..ecd8a85109 100644 --- a/docs/features/search/search-engines.md +++ b/docs/features/search/search-engines.md @@ -59,10 +59,38 @@ configured and make the following changes to your backend: // Initialize a connection to a search engine. const searchEngine = (await PgSearchEngine.supported(env.database)) - ? await PgSearchEngine.from({ database: env.database }) + ? await PgSearchEngine.fromConfig(env.config, { database: env.database }) : new LunrSearchEngine({ logger: env.logger }); ``` +## Optional Configuration + +The following is an example of the optional configuration that can be applied when using Postgres as the search backend. Currently this is mostly for just the highlight feature: + +```yaml +search: + pg: + highlightOptions: + useHighlight: true # Used to enable to disable the highlight feature. The default value is true + maxWord: 35 # Used to set the longest headlines to output. The default value is 35. + minWord: 15 # Used to set the shortest headlines to output. The default value is 15. + shortWord: 3 # Words of this length or less will be dropped at the start and end of a headline, unless they are query terms. The default value of three (3) eliminates common English articles. + highlightAll: false # If true the whole document will be used as the headline, ignoring the preceding three parameters. The default is false. + maxFragments: 0 # Maximum number of text fragments to display. The default value of zero selects a non-fragment-based headline generation method. A value greater than zero selects fragment-based headline generation (see the linked documentation above for more details). + fragmentDelimiter: ' ... ' # Delimiter string used to concatenate fragments. Defaults to " ... ". +``` + +**Note:** the highlight search term feature uses `ts_headline` which has been known to potentially impact performance. You only need this minimal config to disable it should you have issues: + +```yaml +search: + pg: + highlightOptions: + useHighlight: false +``` + +The Postgres documentation on [Highlighting Results](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-HEADLINE) has more details. + ## ElasticSearch Backstage supports ElasticSearch search engine connections, indexing and diff --git a/packages/backend/src/plugins/search.ts b/packages/backend/src/plugins/search.ts index 51ab665026..c478ecdd05 100644 --- a/packages/backend/src/plugins/search.ts +++ b/packages/backend/src/plugins/search.ts @@ -39,9 +39,8 @@ async function createSearchEngine( } if (await PgSearchEngine.supported(env.database)) { - return await PgSearchEngine.fromConfig({ + return await PgSearchEngine.fromConfig(env.config, { database: env.database, - config: env.config, }); } diff --git a/plugins/search-backend-module-pg/api-report.md b/plugins/search-backend-module-pg/api-report.md index cd47df837c..f7a188a14e 100644 --- a/plugins/search-backend-module-pg/api-report.md +++ b/plugins/search-backend-module-pg/api-report.md @@ -79,6 +79,7 @@ export interface DatabaseStore { // // @public (undocumented) export class PgSearchEngine implements SearchEngine { + // @deprecated constructor(databaseStore: DatabaseStore, config: Config); // @deprecated (undocumented) static from(options: { @@ -86,10 +87,10 @@ export class PgSearchEngine implements SearchEngine { config: Config; }): Promise; // (undocumented) - static fromConfig({ - config, - database, - }: PgSearchOptions): Promise; + static fromConfig( + config: Config, + options: PgSearchOptions, + ): Promise; // (undocumented) getIndexer(type: string): Promise; // (undocumented) @@ -142,7 +143,6 @@ export type PgSearchHighlightOptions = { // @public export type PgSearchOptions = { - config: Config; database: PluginDatabaseManager; }; diff --git a/plugins/search-backend-module-pg/src/PgSearchEngine/PgSearchEngine.ts b/plugins/search-backend-module-pg/src/PgSearchEngine/PgSearchEngine.ts index 3f4d419fab..abf7cdbf5c 100644 --- a/plugins/search-backend-module-pg/src/PgSearchEngine/PgSearchEngine.ts +++ b/plugins/search-backend-module-pg/src/PgSearchEngine/PgSearchEngine.ts @@ -60,7 +60,6 @@ export type PgSearchQueryTranslator = ( * @public */ export type PgSearchOptions = { - config: Config; database: PluginDatabaseManager; }; @@ -82,6 +81,10 @@ export type PgSearchHighlightOptions = { export class PgSearchEngine implements SearchEngine { private readonly highlightOptions: PgSearchHighlightOptions; + + /** + * @deprecated This will be marked as private in a future release, please us fromConfig instead + */ constructor(private readonly databaseStore: DatabaseStore, config: Config) { const uuidTag = uuid(); const highlightConfig = config.getOptionalConfig( @@ -117,9 +120,9 @@ export class PgSearchEngine implements SearchEngine { ); } - static async fromConfig({ config, database }: PgSearchOptions) { + static async fromConfig(config: Config, options: PgSearchOptions) { return new PgSearchEngine( - await DatabaseDocumentStore.create(await database.getClient()), + await DatabaseDocumentStore.create(await options.database.getClient()), config, ); } diff --git a/plugins/search-backend-module-pg/src/database/DatabaseDocumentStore.ts b/plugins/search-backend-module-pg/src/database/DatabaseDocumentStore.ts index 040145f7b8..8e73c0f16f 100644 --- a/plugins/search-backend-module-pg/src/database/DatabaseDocumentStore.ts +++ b/plugins/search-backend-module-pg/src/database/DatabaseDocumentStore.ts @@ -135,6 +135,7 @@ export class DatabaseDocumentStore implements DatabaseStore { searchQuery: PgSearchQuery, ): Promise { const { types, pgTerm, fields, offset, limit, options } = searchQuery; + // TODO(awanlin): We should make the language a parameter so that we can support more then just english // Builds a query like: // SELECT ts_rank_cd(body, query) AS rank, type, document, // ts_headline('english', document, query) AS highlight