Package lumis.portal.bigdata.query

Class SearchQuery

  • @StableMinor(version="17.0",
             sinceVersion="9.0")
public class SearchQuery
extends java.lang.Object
    Represents search criteria used to find matching information by a searcher.
    Since:
    8.1.0
    Version:
    $Revision: 26587 $ $Date: 2024-08-26 21:09:17 -0300 (Mon, 26 Aug 2024) $
    See Also:
    IBigDataSearcher

    • Constructor Detail

      • SearchQuery

        public SearchQuery()
        Constructs a SearchQuery object with neither user query and attributes.
        Since:
        8.1.0

      • SearchQuery

        public SearchQuery​(java.lang.String query)
        Constructs a SearchQuery object with the given user query and no attributes.
        Parameters:
        query - user query
        Since:
        8.1.0

    • Method Detail

      • getUserQuery

        public java.lang.String getUserQuery()
        Returns the user query, which is the user-defined portion of the query, usually entered by the final user using front-end interfaces.

        The searcher can and usually perform a tokenization in the user query in the same way they do in the contents during the indexing process.

        Returns:
        the user query
        Since:
        8.1.0

      • setUserQuery

        public SearchQuery setUserQuery​(java.lang.String query)
        Sets the user query.
        Parameters:
        query - the user query. If the given user query is a blank string or null, it is equivalent to not having an user query.
        Since:
        8.1.0

      • getMaxRows

        public int getMaxRows()
        Returns the maximum number of hits to be returned by the query execution.

        Usually this setting is used to paginate the search results.

        Returns:
        the maximum number of hits
        Since:
        8.1.0

      • getStartAt

        public int getStartAt()
        Returns the number of the first hit to be returned by the query execution.

        Usually this setting is used to paginate the search results.
        This number is 1-based (the first result is the result number 1).

        Returns:
        the number of the first hit
        Since:
        8.1.0

      • getControlFilter

        public ISearchQueryFilter getControlFilter()
        Returns a query filter to be applied to the search.
        Returns:
        the query filter, or null if none was specified.
        Since:
        8.1.0
        See Also:
        #getControlQuery()

      • setControlFilter

        public SearchQuery setControlFilter​(ISearchQueryFilter controlFilter)
        Sets the query filter to be applied to the search.
        Parameters:
        the - query filter.
        Since:
        8.1.0
        See Also:
        #setControlQuery(String)

      • getUserQuerySemanticScoreWeight

        public double getUserQuerySemanticScoreWeight()
        Returns the weight applied for score based on user query semantic similarity with documents.
        Returns:
        the weight value.
        Since:
        16.1.0
        See Also:
        setUserQuerySemanticScoreWeight(double)

      • setUserQuerySemanticScoreWeight

        public SearchQuery setUserQuerySemanticScoreWeight​(double userQuerySemanticScoreWeight)
        Sets the weight applied for score based on user query semantic similarity with documents.

        Must be a value between zero and one. The default value is zero.

        The final score is calculated as the sum of the score generated by the semantic similarity multiplied by userQuerySemanticScoreWeight and the score of traditional keywords scoring multiplied by (1 - userQuerySemanticScoreWeight).

        So a value of one would use a score based on semantic similarity only, while a value of zero would use a score based on traditional keywords scoring only. While values between zero and one would use a score based on both scoring types.

        The use of semantic search depends on the AI being enabled on LumisXP. If it is disabled, this property is ignored.

        Note that, to use semantic similarity, other configurations in this search query must also be set.

        Parameters:
        userQuerySemanticScoreWeight - the value to set.
        Returns:
        this search query for method chaining.
        Throws:
        java.lang.IllegalArgumentException - if the value is not between zero and one inclusive.
        Since:
        16.1.0
        See Also:
        setUserQuery(java.lang.String), setUserQuerySemanticMaxResults(int), setUserQuerySemanticMinSimiliarity(double)

      • getUserQuerySemanticMaxResults

        public int getUserQuerySemanticMaxResults()
        Returns the maximum number of results to try to obtain for a user query based on semantic search.
        Returns:
        the maximum number of results based on semantic search.
        Since:
        16.1.0
        See Also:
        setUserQuerySemanticMaxResults(int)

      • setUserQuerySemanticMaxResults

        public SearchQuery setUserQuerySemanticMaxResults​(int userQuerySemanticMaxResults)
        Sets the maximum number of results to try to obtain for a user query based on semantic search.

        Default value is 0.

        Note that this refers only to results based on semantic, the results based on traditional keywords search will still be returned. Use setMaxRows(int) to limit the total number of results returned.

        The use of semantic search depends on the AI being enabled on LumisXP. If it is disabled, this property is ignored.

        Note that, to use semantic similarity, other configurations in this search query must also be set.

        Parameters:
        max - Results the maximum number of results to try to obtain using semantic search.
        Returns:
        this search query for method chaining.
        Throws:
        java.lang.IllegalArgumentException - if the value is negative.
        Since:
        16.1.0
        See Also:
        setUserQuery(java.lang.String), setUserQuerySemanticScoreWeight(double), setUserQuerySemanticMinSimiliarity(double), setMaxRows(int)

      • getUserQuerySemanticMinSimiliarity

        public double getUserQuerySemanticMinSimiliarity()
        Returns the minimum similarity a item must have with the user query to be included in the search results due to semantic search. This does not affect items added to the search results due to traditional keywords search.
        Returns:
        the minimum similarity.
        Since:
        16.1.0
        See Also:
        setUserQuerySemanticMinSimiliarity(double)

      • setUserQuerySemanticMinSimiliarity

        public void setUserQuerySemanticMinSimiliarity​(double userQuerySemanticMinSimiliarity)
        Sets the minimum similarity a item must have with the user query to be included in the search results due to semantic search. This does not affect items added to the search results due to traditional keywords search.

        Default value is 0.78.

        The use of semantic search depends on the AI being enabled on LumisXP. If it is disabled, this property is ignored.

        Note that, to use semantic similarity, other configurations in this search query must also be set.

        Parameters:
        userQuerySemanticMinSimiliarity - the minimum similarity.
        Since:
        16.1.0
        See Also:
        setUserQuery(java.lang.String), setUserQuerySemanticScoreWeight(double), setUserQuerySemanticMaxResults(int)

      • addSort

        public SearchQuery addSort​(ISearchQuerySort sort)
        Adds a sort definition in this search.
        Parameters:
        sort - the sort definition.
        Since:
        8.1.0

      • getSorts

        public java.util.List<ISearchQuerySort> getSorts()
        Returns an unmodifiable list of added sorts.
        Returns:
        an unmodifiable list of added sorts.
        Since:
        8.1.0

      • setHighlight

        public SearchQuery setHighlight​(HighlightConfig highlight)
        Sets the highlight configuration.
        Parameters:
        highlight - the highlight configuration.
        Returns:
        this search query.
        Since:
        8.1.0

      • getHighlight

        public HighlightConfig getHighlight()
        Returns the highlight configuration.
        Returns:
        the highlight configuration.
        Since:
        8.1.0

      • addAggregation

        public SearchQuery addAggregation​(IAggregation aggregation)
        Adds the given aggregation in this search query. Returns this search query.
        Parameters:
        aggregation - the aggregation.
        Returns:
        this search query.
        Since:
        9.0.0

      • addAggregations

        public SearchQuery addAggregations​(IAggregation... aggregations)
        Adds the given aggregations in this search query. Returns this search query.
        Parameters:
        aggregations - the aggregations.
        Returns:
        this search query.
        Since:
        9.0.0

      • addAggregations

        public SearchQuery addAggregations​(java.util.List<IAggregation> aggregations)
        Adds the given aggregations in this search query. Returns this search query.
        Parameters:
        aggregations - the aggregations.
        Returns:
        this search query.
        Since:
        9.0.0

      • getAggregations

        public java.util.List<IAggregation> getAggregations()
        Returns an unmodifiable list of the added aggregations.
        Returns:
        an unmodifiable list of the added aggregations.
        Since:
        9.0.0

      • addFieldBoost

        public SearchQuery addFieldBoost​(java.lang.String fieldId,
                                 float boost)
                          throws PortalObjectNotFoundException
        Adds a field boost to search. This configuration is only used when a user query is present in search query.
        Parameters:
        fieldId - the identifier of the field to be boosted.
        boost - the boost value.
        Returns:
        this search query.
        Throws:
        PortalObjectNotFoundException - if no field with the given identifier could be found.
        Since:
        11.1.0

      • addFieldBoost

        public SearchQuery addFieldBoost​(DocumentTypeField documentTypeField,
                                 float boost)
        Adds a field boost to search. This configuration is only used when a user query is present in search query.
        Parameters:
        documentTypeField - the field to be boosted.
        boost - the boost value.
        Returns:
        this search query.
        Throws:
        PortalObjectNotFoundException - if no field with the given identifier could be found.
        java.lang.IllegalArgumentException - if the field is not indexed.
        java.lang.IllegalArgumentException - if the boost value is not positive.
        Since:
        11.1.0
        See Also:
        DocumentTypeField.getIndexMode()

      • addDocumentTypes

        public SearchQuery addDocumentTypes​(DocumentType... documentTypes)
        Adds the given document types to the scope for this search query.

        By default a search query searches in all existing document types, but if any document type is added to the search query, it will limit its search to the added document types.

        Parameters:
        documentTypes - the document types to add.
        Returns:
        this search query for chaining operation.
        Since:
        12.5.0

      • addDocumentTypes

        public SearchQuery addDocumentTypes​(java.util.Collection<? extends DocumentType> documentTypes)
        Adds the given document types to the scope for this search query.

        By default a search query searches in all existing document types, but if any document type is added to the search query, it will limit its search to the added document types.

        Parameters:
        documentTypes - the document types to add.
        Returns:
        this search query for chaining operation.
        Since:
        12.5.0

      • addDocumentTypeIds

        public SearchQuery addDocumentTypeIds​(java.lang.String... documentTypes)
        Adds the given document types to the scope for this search query.

        By default a search query searches in all existing document types, but if any document type is added to the search query, it will limit its search to the added document types.

        Parameters:
        documentTypeIds - the identifiers of document types to add.
        Returns:
        this search query for chaining operation.
        Since:
        12.5.0

      • addDocumentTypeIds

        public SearchQuery addDocumentTypeIds​(java.util.Collection<java.lang.String> documentTypeIds)
        Adds the given document types to the scope for this search query.

        By default a search query searches in all existing document types, but if any document type is added to the search query, it will limit its search to the added document types.

        Parameters:
        documentTypeIds - the identifiers of document types to add.
        Returns:
        this search query for chaining operation.
        Since:
        12.5.0

      • getDocumentTypeIds

        public java.util.Set<java.lang.String> getDocumentTypeIds()
        Returns the identifiers of document types set as the scope for this search query.
        Returns:
        a unmodifiable set with the document type identifiers. If no document type was set as the scope for this search query then an empty set is returned.
        Since:
        12.5.0

      • getFieldsBoost

        public java.util.Map<DocumentTypeField,​java.lang.Float> getFieldsBoost()
        Returns the field boosting configuration.
        Returns:
        the field boosting configuration.
        Since:
        11.1.0