alfresco-ng2-components/docs/content-services/services/search-query-builder.service.md

Title, Added, Status, Last reviewed

Title	Added	Status	Last reviewed
Search Query Builder service	v2.3.0	Active	2026-06-29

Search Query Builder service

Stores information from all the custom search and faceted search widgets, compiles and runs the final search query.

Class members

Properties

Name	Type	Description
userQuery	string	The raw query string typed by the user. Setting it stores the value, records it in filterRawParams and recomputes parsedQuery according to the current searchMode.
parsedQuery	string (read-only)	The query derived from userQuery. In regular mode the user terms are expanded against the configured fields (see app:fields) and optionally wildcarded; in formula mode it is identical to userQuery.
searchMode	'regular' | 'formula'	Controls how userQuery is turned into parsedQuery. regular (default) parses the user input into a field query; formula uses the user input verbatim as an AFTS expression.
selectedConfigurationId	string	Id of the currently active search configuration. Setting it also records the value in filterRawParams.
encodedQuery	string (read-only)	The Base64-encoded filterRawParams, produced by encodeQuery() and written to the q route query parameter.
wildcardsEnabled	boolean (read-only)	Reads the search-wildcards-enabled app config flag (default true). When enabled, query terms are suffixed with * so partial matches are returned.

Methods

• addFilterQuery(query: string)
  Adds a filter query to the current query.

  • query: string - Query string to add

• addUserFacetBucket(field: FacetField, bucket: FacetFieldBucket)
  Adds a facet bucket to a field.

  • field: FacetField - The target field
  • bucket: FacetFieldBucket - Bucket to add

• buildQuery(): SearchRequest
  Builds the current query.

  • Returns SearchRequest - The finished query

• encodeQuery()
  Encodes query shards stored in filterRawParams property.

• execute(updateQueryParams: boolean = true, queryBody?: SearchRequest)
  Builds and executes the current query, then emits the result on the executed stream.

  • updateQueryParams: boolean - (Optional) When true (default) the encoded query is written to the q route query parameter. Pass false to execute without updating the URL.
  • queryBody: SearchRequest - (Optional) Pre-built query to execute instead of building one from the current state.

• getDefaultConfiguration(): SearchConfiguration|undefined
  

  • Returns SearchConfiguration|undefined -

• getFacetField(label: string): FacetField
  Gets a facet field by label.

  • label: string - Label of the facet field
  • Returns FacetField - Facet field data

• getFacetQuery(label: string): FacetQuery
  Gets a facet query by label.

  • label: string - Label of the query
  • Returns FacetQuery - Facet query data

• getPrimarySorting(): SearchSortingDefinition
  Gets the primary sorting definition.

  • Returns SearchSortingDefinition - The primary sorting definition

• getQueryGroup(query: any): any
  Gets the query group.

  • query: any - Target query
  • Returns any - Query group

• getScope(): RequestScope
  

  • Returns RequestScope -

• getSearchFormDetails(): SearchForm[]
  

  • Returns SearchForm[] -

• getSortingOptions(): SearchSortingDefinition[]
  Gets all pre-configured sorting options that users can choose from.

  • Returns SearchSortingDefinition[] - Pre-configured sorting options

• getSupportedLabel(configLabel: string): string
  Encloses a label name with double quotes if it contains whitespace characters.

  • configLabel: string - Original label text
  • Returns string - Label, possibly with quotes if it contains spaces

• getUserFacetBuckets(field: string): FacetFieldBucket[]
  Gets the buckets currently added to a field

  • field: string - The target fields
  • Returns FacetFieldBucket[] - Bucket array

• isFilterServiceActive(): boolean
  

  • Returns boolean -

• isOperator(input: string): boolean
  Checks whether the supplied string is a logical AND or OR operator. Used when parsing a multi-word user query in regular search mode.

  • input: string - String to check
  • Returns boolean - true if the trimmed string is AND or OR, otherwise false

• loadConfiguration(): SearchConfiguration
  

  • Returns SearchConfiguration -

• navigateToSearch(query: string, searchUrl: string)
  Updates user query, executes existing search configuration, encodes the query and navigates to searchUrl.

  • query: string - The query to use as user query
  • searchUrl: string - Search url to navigate to

• removeFilterQuery(query: string)
  Removes an existing filter query.

  • query: string - The query to remove

• removeUserFacetBucket(field: FacetField, bucket: FacetFieldBucket)
  Removes an existing bucket from a field.

  • field: FacetField - The target field
  • bucket: FacetFieldBucket - Bucket to remove

• resetToDefaults(withNavigate: boolean = false, resetUserQuery: boolean = true)
  Resets the query builder back to the default search configuration.

  • withNavigate: boolean - (Optional) When true, clears the q route query parameter while resetting. Defaults to false.
  • resetUserQuery: boolean - (Optional) When true (default), the userQuery and its parsed form are cleared. Pass false to keep the current user query while resetting the rest of the options.

• search(queryBody: SearchRequest): Observable<ResultSetPaging>
  

  • queryBody: SearchRequest -
  • Returns Observable<ResultSetPaging> -

• setScope(scope: RequestScope)
  

  • scope: RequestScope -

• updateSearchQueryParams()
  Encodes the query and navigates to existing search route adding encoded query as a search param.

• updateSelectedConfiguration(id: string, resetFilters: boolean = true, shouldExecute: boolean = true)
  Switches the active search configuration to the one matching the supplied id (only relevant when multiple configurations are provided).

  • id: string - Id of the configuration to select
  • resetFilters: boolean - (Optional) When true (default), the current search options are reset before applying the new configuration. Pass false to keep them.
  • shouldExecute: boolean - (Optional) When true (default), the query is executed immediately after switching configuration.

Details

See the Search filter component page for full details about the format of queries, facet fields, and sorting options.

The Query Builder is UI agnostic and does not rely on Angular components. You can reuse it with multiple component implementations.

You can use custom widgets to populate and edit the following parts of the resulting query:

• categories
• query fragments that form a query expression
• include fields
• scope settings
• filter queries
• facet fields
• range queries

constructor(queryBuilder: SearchQueryBuilderService) {

    queryBuilder.executed.subscribe(data => {
        this.onDataLoaded(data);
    });

}

To run a search, build the query state (for example by setting userQuery or by letting a search widget update queryFragments) and then call execute(). The result is delivered through the executed stream.

this.queryBuilder.userQuery = 'invoice';
void this.queryBuilder.execute();

Note: Earlier versions exposed an updated stream and an update() method that built the query and emitted it so that a subscriber could call execute(). Both have been removed; build the query state and call execute() directly instead.

Search modes

The builder supports two search modes, selected through the searchMode property:

• regular (default) - the text in userQuery is treated as user input and parsed into a field query. The query is split into terms, each term is matched against the fields listed in the app:fields search configuration entry (falling back to cm:name), and a * wildcard is appended when wildcards are enabled. Bare AND/OR words are preserved as operators.
• formula - the text in userQuery is used verbatim as an AFTS expression, allowing callers that already build their own query syntax to bypass parsing.

Note: From ADF 3.0.0, the query contains the "facetFormat": "V2" parameter so that all the responses have the same structure whether they come from search queries containing facetFields, facetQueries, grouped facetQueries or facetIntervals.

Runtime Configuration

You can provide search configuration at runtime using the ADF_SEARCH_CONFIGURATION injection token. The value should expose the SearchConfiguration interface.

@NgModule({
    providers: [
        { provide: ADF_SEARCH_CONFIGURATION, useValue: {/*...*/} }
    ]
})
class AppModule {}

See also

• Search Configuration Guide
• Search filter component
• Search filter chips component
• Search Form Component
• Search Widget interface
• Search check list component
• Search date range tabbed component
• Search number range component
• Search radio component
• Search slider component
• Search text component
• Search input component