Package ai.vectros.resources.search.requests

Class SearchRequest.Builder

java.lang.Object
ai.vectros.resources.search.requests.SearchRequest.Builder
All Implemented Interfaces:
SearchRequest._FinalStage, SearchRequest.QueryStage
Enclosing class:
SearchRequest
public static final class SearchRequest.Builder extends Object implements SearchRequest.QueryStage, SearchRequest._FinalStage

  • Method Details

    • from

      public SearchRequest.Builder from(SearchRequest other)
      Specified by:
      from in interface SearchRequest.QueryStage

    • query

      public SearchRequest._FinalStage query(@NotNull @NotNull String query)

      The search query, expressed in natural language or as keywords. Required.

      The search query, expressed in natural language or as keywords. Required.

      Specified by:
      query in interface SearchRequest.QueryStage
      Returns:
      Reference to this so that method calls can be chained together.

    • requireComplete

      public SearchRequest._FinalStage requireComplete(Boolean requireComplete)

      A fail-closed override. When true, the request returns HTTP 503 instead of partial results if one of the search engines is unavailable. Defaults to false, in which case an outage degrades to the surviving engine and the response carries degraded: true along with the failed engines in degradedLegs. Set this to true only when complete results are required and a degraded answer is unacceptable.

      Specified by:
      requireComplete in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • requireComplete

      public SearchRequest._FinalStage requireComplete(Optional<Boolean> requireComplete)

      A fail-closed override. When true, the request returns HTTP 503 instead of partial results if one of the search engines is unavailable. Defaults to false, in which case an outage degrades to the surviving engine and the response carries degraded: true along with the failed engines in degradedLegs. Set this to true only when complete results are required and a degraded answer is unacceptable.

      Specified by:
      requireComplete in interface SearchRequest._FinalStage

    • createdBefore

      public SearchRequest._FinalStage createdBefore(String createdBefore)

      Restrict results to content created at or before this ISO-8601 UTC timestamp. Pair it with createdAfter to define a window, or use it alone to find content older than a cutoff (for example, in archival or cleanup workflows).

      Specified by:
      createdBefore in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • createdBefore

      public SearchRequest._FinalStage createdBefore(Optional<String> createdBefore)

      Restrict results to content created at or before this ISO-8601 UTC timestamp. Pair it with createdAfter to define a window, or use it alone to find content older than a cutoff (for example, in archival or cleanup workflows).

      Specified by:
      createdBefore in interface SearchRequest._FinalStage

    • createdAfter

      public SearchRequest._FinalStage createdAfter(String createdAfter)

      Restrict results to content created at or after this ISO-8601 UTC timestamp. Useful for incremental queries (for example, finding anything ingested in the last hour), for isolating just-created content from older history, and for time-bounded analytics. Pair it with createdBefore to define a window.

      Specified by:
      createdAfter in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • createdAfter

      public SearchRequest._FinalStage createdAfter(Optional<String> createdAfter)

      Restrict results to content created at or after this ISO-8601 UTC timestamp. Useful for incremental queries (for example, finding anything ingested in the last hour), for isolating just-created content from older history, and for time-bounded analytics. Pair it with createdBefore to define a window.

      Specified by:
      createdAfter in interface SearchRequest._FinalStage

    • typeName

      public SearchRequest._FinalStage typeName(String typeName)

      Restrict results to records of a specific schema type (for example patient or intake_form). Has no effect on documents — it only narrows record results. Setting it implicitly limits the results to records, unless you also include documents via contentTypes.

      Specified by:
      typeName in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • typeName

      public SearchRequest._FinalStage typeName(Optional<String> typeName)

      Restrict results to records of a specific schema type (for example patient or intake_form). Has no effect on documents — it only narrows record results. Setting it implicitly limits the results to records, unless you also include documents via contentTypes.

      Specified by:
      typeName in interface SearchRequest._FinalStage

    • rootFolderId

      public SearchRequest._FinalStage rootFolderId(String rootFolderId)

      Restrict results to content (documents or records) anywhere under this folder subtree — the folder itself and all of its descendants. Provide the Vectros-assigned UUID of a top-level (root) folder. Applies to documents and records alike. Use folderId instead to match a single exact folder.

      Specified by:
      rootFolderId in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • rootFolderId

      public SearchRequest._FinalStage rootFolderId(Optional<String> rootFolderId)

      Restrict results to content (documents or records) anywhere under this folder subtree — the folder itself and all of its descendants. Provide the Vectros-assigned UUID of a top-level (root) folder. Applies to documents and records alike. Use folderId instead to match a single exact folder.

      Specified by:
      rootFolderId in interface SearchRequest._FinalStage

    • folderId

      public SearchRequest._FinalStage folderId(String folderId)

      Restrict results to content (documents or records) in this EXACT folder. Folders hold a mix of documents and records. Provide the Vectros-assigned UUID of a folder; use GET /v1/folders to list your folders. To match a folder AND all of its descendants, use rootFolderId instead.

      Specified by:
      folderId in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • folderId

      public SearchRequest._FinalStage folderId(Optional<String> folderId)

      Restrict results to content (documents or records) in this EXACT folder. Folders hold a mix of documents and records. Provide the Vectros-assigned UUID of a folder; use GET /v1/folders to list your folders. To match a folder AND all of its descendants, use rootFolderId instead.

      Specified by:
      folderId in interface SearchRequest._FinalStage

    • contentTypes

      public SearchRequest._FinalStage contentTypes(List<SearchRequestContentTypesItem> contentTypes)

      Narrow results to specific content types. When omitted, empty, or set to both values, the search returns all content (documents and records) in a single unified result set, which is the default behavior. Each returned result carries a sourceType discriminator so you can tell documents and records apart. Pass ["documents"] for documents only, or ["records"] for records only.

      Specified by:
      contentTypes in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • contentTypes

      public SearchRequest._FinalStage contentTypes(Optional<List<SearchRequestContentTypesItem>> contentTypes)

      Narrow results to specific content types. When omitted, empty, or set to both values, the search returns all content (documents and records) in a single unified result set, which is the default behavior. Each returned result carries a sourceType discriminator so you can tell documents and records apart. Pass ["documents"] for documents only, or ["records"] for records only.

      Specified by:
      contentTypes in interface SearchRequest._FinalStage

    • uniqueDocuments

      public SearchRequest._FinalStage uniqueDocuments(Boolean uniqueDocuments)

      When true, returns at most one chunk per source item, so a single document or record cannot appear more than once in the results.

      Specified by:
      uniqueDocuments in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • uniqueDocuments

      public SearchRequest._FinalStage uniqueDocuments(Optional<Boolean> uniqueDocuments)

      When true, returns at most one chunk per source item, so a single document or record cannot appear more than once in the results.

      Specified by:
      uniqueDocuments in interface SearchRequest._FinalStage

    • slop

      public SearchRequest._FinalStage slop(Integer slop)

      The phrase-match slop: the number of intervening positions allowed between query terms when textMode is PHRASE (0 means the terms must be exactly adjacent). Ignored for the other text modes.

      Specified by:
      slop in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • slop

      public SearchRequest._FinalStage slop(Optional<Integer> slop)

      The phrase-match slop: the number of intervening positions allowed between query terms when textMode is PHRASE (0 means the terms must be exactly adjacent). Ignored for the other text modes.

      Specified by:
      slop in interface SearchRequest._FinalStage

    • minTextRelevance

      public SearchRequest._FinalStage minTextRelevance(Double minTextRelevance)

      A relative relevance floor for the keyword leg, given as a fraction from 0 to 1 of the TOP result's score — results scoring below (top score × this value) are dropped. Keyword scores are unbounded and depend on the query, so this is a relative cutoff rather than an absolute score: for example, 0.5 keeps only results at least half as relevant as the best hit. Applies when the mode is TEXT or HYBRID. Omit it (or use a value of 0 or less) to keep all keyword matches.

      Specified by:
      minTextRelevance in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • minTextRelevance

      public SearchRequest._FinalStage minTextRelevance(Optional<Double> minTextRelevance)

      A relative relevance floor for the keyword leg, given as a fraction from 0 to 1 of the TOP result's score — results scoring below (top score × this value) are dropped. Keyword scores are unbounded and depend on the query, so this is a relative cutoff rather than an absolute score: for example, 0.5 keeps only results at least half as relevant as the best hit. Applies when the mode is TEXT or HYBRID. Omit it (or use a value of 0 or less) to keep all keyword matches.

      Specified by:
      minTextRelevance in interface SearchRequest._FinalStage

    • minSimilarity

      public SearchRequest._FinalStage minSimilarity(Double minSimilarity)

      The minimum semantic similarity score a result must have to be included, on a scale of 0.0 to 1.0. Results scoring below this threshold are dropped. Applies when the mode is SEMANTIC or HYBRID.

      Specified by:
      minSimilarity in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • minSimilarity

      public SearchRequest._FinalStage minSimilarity(Optional<Double> minSimilarity)

      The minimum semantic similarity score a result must have to be included, on a scale of 0.0 to 1.0. Results scoring below this threshold are dropped. Applies when the mode is SEMANTIC or HYBRID.

      Specified by:
      minSimilarity in interface SearchRequest._FinalStage

    • textMode

      public SearchRequest._FinalStage textMode(SearchRequestTextMode textMode)

      How query terms are matched by the keyword engine when the mode is TEXT or HYBRID. OR matches content containing any query term (broadest recall). AND requires every term to be present (higher precision). PHRASE requires the terms to appear as a contiguous sequence. COMPLEX enables the full query syntax, including boolean operators, field-scoped queries, and range filters. When omitted, defaults to PHRASE (with a slop of 3) in HYBRID mode and OR in TEXT mode.

      Specified by:
      textMode in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • textMode

      public SearchRequest._FinalStage textMode(Optional<SearchRequestTextMode> textMode)

      How query terms are matched by the keyword engine when the mode is TEXT or HYBRID. OR matches content containing any query term (broadest recall). AND requires every term to be present (higher precision). PHRASE requires the terms to appear as a contiguous sequence. COMPLEX enables the full query syntax, including boolean operators, field-scoped queries, and range filters. When omitted, defaults to PHRASE (with a slop of 3) in HYBRID mode and OR in TEXT mode.

      Specified by:
      textMode in interface SearchRequest._FinalStage

    • filters

      public SearchRequest._FinalStage filters(Map<String,FilterValue> filters)

      Field-level filters applied to your document and record metadata. Each key is a field name, and top-level keys are AND-combined. Each value is one of: a scalar (string, number, or boolean) for an exact match; an array of scalars to match any one of them; or an operator map for ranges, negation, and membership. The supported operators are a closed set: $eq, $ne, $gt, $gte, $lt, $lte (each takes a scalar) and $in, $nin (each takes an array of scalars). Operators within one map are AND-combined, so {"price":{"$gte":100,"$lte":500}} expresses a closed range; $in and $nin may not be combined with other operators. Numbers and booleans are matched by type, so the field must have been ingested under a typed schema; dates may be sent as ISO 8601 strings or epoch milliseconds. Unknown operators, non-scalar operands, and malformed field names are rejected with a 400.

      Specified by:
      filters in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • filters

      public SearchRequest._FinalStage filters(Optional<Map<String,FilterValue>> filters)

      Field-level filters applied to your document and record metadata. Each key is a field name, and top-level keys are AND-combined. Each value is one of: a scalar (string, number, or boolean) for an exact match; an array of scalars to match any one of them; or an operator map for ranges, negation, and membership. The supported operators are a closed set: $eq, $ne, $gt, $gte, $lt, $lte (each takes a scalar) and $in, $nin (each takes an array of scalars). Operators within one map are AND-combined, so {"price":{"$gte":100,"$lte":500}} expresses a closed range; $in and $nin may not be combined with other operators. Numbers and booleans are matched by type, so the field must have been ingested under a typed schema; dates may be sent as ISO 8601 strings or epoch milliseconds. Unknown operators, non-scalar operands, and malformed field names are rejected with a 400.

      Specified by:
      filters in interface SearchRequest._FinalStage

    • clientId

      public SearchRequest._FinalStage clientId(String clientId)

      Restrict results to content associated with this client — the Vectros-assigned UUID of a client in your account. Use GET /v1/clients?externalId= to look up a client's ID from your own identifier.

      Specified by:
      clientId in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • clientId

      public SearchRequest._FinalStage clientId(Optional<String> clientId)

      Restrict results to content associated with this client — the Vectros-assigned UUID of a client in your account. Use GET /v1/clients?externalId= to look up a client's ID from your own identifier.

      Specified by:
      clientId in interface SearchRequest._FinalStage

    • orgId

      public SearchRequest._FinalStage orgId(String orgId)

      Restrict results to content belonging to this organization — the Vectros-assigned UUID of an organization in your account. Use GET /v1/orgs?externalId= to look up an organization's ID from your own identifier.

      Specified by:
      orgId in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • orgId

      public SearchRequest._FinalStage orgId(Optional<String> orgId)

      Restrict results to content belonging to this organization — the Vectros-assigned UUID of an organization in your account. Use GET /v1/orgs?externalId= to look up an organization's ID from your own identifier.

      Specified by:
      orgId in interface SearchRequest._FinalStage

    • userId

      public SearchRequest._FinalStage userId(String userId)

      Restrict results to content owned by this user — the Vectros-assigned UUID of a user in your account. Use GET /v1/users?externalId= to look up a user's ID from your own identifier.

      Specified by:
      userId in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • userId

      public SearchRequest._FinalStage userId(Optional<String> userId)

      Restrict results to content owned by this user — the Vectros-assigned UUID of a user in your account. Use GET /v1/users?externalId= to look up a user's ID from your own identifier.

      Specified by:
      userId in interface SearchRequest._FinalStage

    • offset

      public SearchRequest._FinalStage offset(Integer offset)

      The number of results to skip, for pagination. Must be between 0 and 200. Defaults to 0.

      Specified by:
      offset in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • offset

      public SearchRequest._FinalStage offset(Optional<Integer> offset)

      The number of results to skip, for pagination. Must be between 0 and 200. Defaults to 0.

      Specified by:
      offset in interface SearchRequest._FinalStage

    • limit

      public SearchRequest._FinalStage limit(Integer limit)

      The maximum number of results to return. Must be between 1 and 100. Defaults to 20.

      Specified by:
      limit in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • limit

      public SearchRequest._FinalStage limit(Optional<Integer> limit)

      The maximum number of results to return. Must be between 1 and 100. Defaults to 20.

      Specified by:
      limit in interface SearchRequest._FinalStage

    • mode

      public SearchRequest._FinalStage mode(SearchRequestMode mode)

      How results are ranked. HYBRID combines semantic and keyword ranking (recommended). SEMANTIC ranks by vector similarity only. TEXT ranks by keyword matching only. Defaults to HYBRID.

      Specified by:
      mode in interface SearchRequest._FinalStage
      Returns:
      Reference to this so that method calls can be chained together.

    • mode

      public SearchRequest._FinalStage mode(Optional<SearchRequestMode> mode)

      How results are ranked. HYBRID combines semantic and keyword ranking (recommended). SEMANTIC ranks by vector similarity only. TEXT ranks by keyword matching only. Defaults to HYBRID.

      Specified by:
      mode in interface SearchRequest._FinalStage

    • build

      public SearchRequest build()
      Specified by:
      build in interface SearchRequest._FinalStage

    • additionalProperty

      public SearchRequest.Builder additionalProperty(String key, Object value)
      Specified by:
      additionalProperty in interface SearchRequest._FinalStage

    • additionalProperties

      public SearchRequest.Builder additionalProperties(Map<String,Object> additionalProperties)
      Specified by:
      additionalProperties in interface SearchRequest._FinalStage