Package com.couchbase.client.java.search

Class SearchQuery

java.lang.Object
com.couchbase.client.java.search.SearchQuery
@Committed
@Public
public class SearchQuery
extends Object
The FTS API entry point. Describes an FTS query entirely (index, query body and parameters) and can be used at the Bucket level to perform said query. Also has factory methods for all types of fts queries (as in the various types a query body can have: term, match, conjunction, ...).
Since:
2.3.0
Author:
Simon Baslé, Michael Nitschinger

  • Constructor Details

    • SearchQuery

      public SearchQuery​(String indexName, AbstractFtsQuery queryPart)
      Prepare an FTS SearchQuery on an index. Top level query parameters can be set after that by using the fluent API.
      Parameters:
      indexName - the FTS index to search in.
      queryPart - the body of the FTS query (eg. a match phrase query).

  • Method Details

    • indexName

      public String indexName()
      Returns:
      the name of the index targeted by this query.

    • query

      public AbstractFtsQuery query()
      Returns:
      the actual query body.

    • export

      public JsonObject export()
      Exports the whole query as a JsonObject.
      See Also:
      for the part that deals with global parameters, for the part that deals with the "query" entry

    • injectParams

      public void injectParams​(JsonObject queryJson)
      Inject the top level parameters of a query into a prepared JsonObject that represents the root of the query.
      Parameters:
      queryJson - the prepared JsonObject for the whole query.

    • limit

      public SearchQuery limit​(int limit)
      Add a limit to the query on the number of hits it can return.
      Parameters:
      limit - the maximum number of hits to return.
      Returns:
      this SearchQuery for chaining.

    • skip

      public SearchQuery skip​(int skip)
      Set the number of hits to skip (eg. for pagination).
      Parameters:
      skip - the number of results to skip.
      Returns:
      this SearchQuery for chaining.

    • explain

      public SearchQuery explain()
      Activates the explanation of each result hit in the response.
      Returns:
      this SearchQuery for chaining.

    • explain

      public SearchQuery explain​(boolean explain)
      Activates or deactivates the explanation of each result hit in the response, according to the parameter.
      Parameters:
      explain - should the response include an explanation of each hit (true) or not (false)?
      Returns:
      this SearchQuery for chaining.

    • highlight

      public SearchQuery highlight​(HighlightStyle style, String... fields)
      Configures the highlighting of matches in the response. This drives the inclusion of the fragments in each hit. Note that to be highlighted, the fields must be stored in the FTS index.
      Parameters:
      style - the HighlightStyle to apply.
      fields - the optional fields on which to highlight. If none, all fields where there is a match are highlighted.
      Returns:
      this SearchQuery for chaining.

    • highlight

      public SearchQuery highlight​(String... fields)
      Configures the highlighting of matches in the response, for the specified fields and using the server's default highlighting style. This drives the inclusion of the fragments in each hit. Note that to be highlighted, the fields must be stored in the FTS index.
      Parameters:
      fields - the optional fields on which to highlight. If none, all fields where there is a match are highlighted.
      Returns:
      this SearchQuery for chaining.

    • highlight

      public SearchQuery highlight()
      Configures the highlighting of matches in the response for all fields, using the server's default highlighting style. This drives the inclusion of the fragments in each hit. Note that to be highlighted, the fields must be stored in the FTS index.
      Returns:
      this SearchQuery for chaining.

    • clearHighlight

      public SearchQuery clearHighlight()
      Clears any previously configured highlighting.
      Returns:
      this SearchQuery for chaining.
      See Also:
      highlight(HighlightStyle, String...)

    • fields

      public SearchQuery fields​(String... fields)
      Configures the list of fields for which the whole value should be included in the response. If empty, no field values are included. This drives the inclusion of the fields in each hit. Note that to be highlighted, the fields must be stored in the FTS index.
      Parameters:
      fields -
      Returns:
      this SearchQuery for chaining.

    • sort

      public SearchQuery sort​(Object... sort)
      Configures the list of fields (including special fields) which are used for sorting purposes. If empty, the default sorting (descending by score) is used by the server. The list of sort fields can include actual fields (like "firstname" but then they must be stored in the index, configured in the server side mapping). Fields provided first are considered first and in a "tie" case the next sort field is considered. So sorting by "firstname" and then "lastname" will first sort ascending by the firstname and if the names are equal then sort ascending by lastname. Special fields like "_id" and "_score" can also be used. If prefixed with "-" the sort order is set to descending. If no sort is provided, it is equal to sort("-_score"), since the server will sort it by score in descending order.
      Parameters:
      sort - the fields that should take part in the sorting.
      Returns:
      this SearchQuery for chaining.

    • addFacet

      public SearchQuery addFacet​(String facetName, SearchFacet facet)
      Adds one SearchFacet to the query. This is an additive operation (the given facets are added to any facet previously requested), but if an existing facet has the same name it will be replaced. This drives the inclusion of the SearchQueryResult.facets() facets} in the SearchQueryResult. Note that to be faceted, a field's value must be stored in the FTS index.
      Parameters:
      facetName - the name of the facet to add (or replace if one already exists with same name).
      facet - the facet to add.

    • clearFacets

      public SearchQuery clearFacets()
      Clears all previously added SearchFacet.
      Returns:
      this SearchQuery for chaining.
      See Also:
      addFacet(String, SearchFacet)

    • serverSideTimeout

      public SearchQuery serverSideTimeout​(long timeout, TimeUnit unit)
      Sets the server side timeout. By default, the SDK will set this value to the configured searchTimeout from the environment.
      Parameters:
      timeout - the server side timeout to apply.
      unit - the unit for the timeout.
      Returns:
      this SearchQuery for chaining.

    • searchConsistency

      public SearchQuery searchConsistency​(SearchConsistency consistency)
      Sets the unparameterized consistency to consider for this FTS query. This replaces any consistency tuning previously set.
      Parameters:
      consistency - the simple consistency to use.
      Returns:
      this SearchQuery for chaining.

    • consistentWith

      public SearchQuery consistentWith​(Document... docs)
      Sets the consistency to consider for this FTS query to AT_PLUS and uses the mutation information from the given documents to parameterize the consistency. This replaces any consistency tuning previously set.
      Parameters:
      docs - one or mode Document to get mutation state information from.
      Returns:
      this SearchQuery for chaining.

    • consistentWith

      public SearchQuery consistentWith​(DocumentFragment... fragments)
      Sets the consistency to consider for this FTS query to AT_PLUS and uses the mutation information from the given document fragments to parameterize the consistency. This replaces any consistency tuning previously set.
      Parameters:
      fragments - one or mode DocumentFragment to get mutation state information from.
      Returns:
      this SearchQuery for chaining.

    • consistentWith

      public SearchQuery consistentWith​(MutationState mutationState)
      Sets the consistency to consider for this FTS query to AT_PLUS and uses the MutationState directly to parameterize the consistency. This replaces any consistency tuning previously set.
      Parameters:
      mutationState - the MutationState information to work with.
      Returns:
      this SearchQuery for chaining.

    • getLimit

      public Integer getLimit()
      Returns:
      the value of the limit(int) parameter, or null if it was not set.

    • getSkip

      public Integer getSkip()
      Returns:
      the value of the skip(int) parameter, or null if it was not set.

    • getHighlightStyle

      public HighlightStyle getHighlightStyle()
      Returns:
      the value of the highlight style parameter, or null if it was not set.

    • getHighlightFields

      public String[] getHighlightFields()
      Returns:
      the value of the highlight fields parameter, or an empty array if it was not set.

    • getFields

      public String[] getFields()
      Returns:
      the value of the fields(String...) parameter, or an empty array if it was not set.

    • getFacets

      public Map<String,​SearchFacet> getFacets()
      Returns:
      the Map of facets (by name), or an empty Map if it was not set.

    • getServerSideTimeout

      public Long getServerSideTimeout()
      Returns:
      the value of the serverSideTimeout(long, TimeUnit) parameter, or null if it was not set.

    • queryString

      public static QueryStringQuery queryString​(String query)
      Prepare a QueryStringQuery body.

    • match

      public static MatchQuery match​(String match)
      Prepare a MatchQuery body.

    • matchPhrase

      public static MatchPhraseQuery matchPhrase​(String matchPhrase)
      Prepare a MatchPhraseQuery body.

    • prefix

      public static PrefixQuery prefix​(String prefix)
      Prepare a PrefixQuery body.

    • regexp

      public static RegexpQuery regexp​(String regexp)
      Prepare a RegexpQuery body.

    • termRange

      public static TermRangeQuery termRange()
      Prepare a TermRangeQuery body.

    • numericRange

      public static NumericRangeQuery numericRange()
      Prepare a NumericRangeQuery body.

    • dateRange

      public static DateRangeQuery dateRange()
      Prepare a DateRangeQuery body.

    • disjuncts

      public static DisjunctionQuery disjuncts​(AbstractFtsQuery... queries)
      Prepare a DisjunctionQuery body.

    • conjuncts

      public static ConjunctionQuery conjuncts​(AbstractFtsQuery... queries)
      Prepare a ConjunctionQuery body.

    • booleans

      public static BooleanQuery booleans()
      Prepare a BooleanQuery body.

    • wildcard

      public static WildcardQuery wildcard​(String wildcard)
      Prepare a WildcardQuery body.

    • docId

      public static DocIdQuery docId​(String... docIds)
      Prepare a DocIdQuery body.

    • booleanField

      public static BooleanFieldQuery booleanField​(boolean value)
      Prepare a BooleanFieldQuery body.

    • term

      public static TermQuery term​(String term)
      Prepare a TermQuery body.

    • phrase

      public static PhraseQuery phrase​(String... terms)
      Prepare a PhraseQuery body.

    • matchAll

      public static MatchAllQuery matchAll()
      Prepare a MatchAllQuery body.

    • matchNone

      public static MatchNoneQuery matchNone()
      Prepare a MatchNoneQuery body.

    • geoBoundingBox

      public static GeoBoundingBoxQuery geoBoundingBox​(double topLeftLon, double topLeftLat, double bottomRightLon, double bottomRightLat)
      Prepare a GeoBoundingBoxQuery body.

    • geoDistance

      public static GeoDistanceQuery geoDistance​(double locationLon, double locationLat, String distance)
      Prepare a GeoDistanceQuery body.

    • geoPolygon

      @Experimental public static GeoPolygonQuery geoPolygon​(List<Coordinate> points)
      Prepare a GeoPolygonQuery body.