Step Search (:search)

Quick Answer

Use :search to query workspace resources and entities without external HTTP calls.

{:type :search :query "..." :mode :hybrid :keyword-mode :balanced :targets [:resources :flows :runs :connections] :limit 12}

For :resources, Breyta supports three retrieval modes:

• :lexical — keyword/path/metadata search. Use this for deterministic strict keyword matching.
• :hybrid — lexical plus semantic ranking when the semantic index is enabled; falls back to lexical with diagnostics when semantic reads are unavailable.
• :semantic — semantic-only retrieval. Use this only when the semantic index is enabled; otherwise the request fails instead of silently returning lexical results.

The same :search step keeps exact path/URI pinning, storage filters, and hydration behavior.

For lexical matching, :keyword-mode controls term recall:

• :all — every keyword must match one resource. Use this for strict lexical searches.
• :balanced — removes common query words and requires a strong subset of significant keywords. Use this for natural-language questions over small resource sets.
• :any — any keyword can match. Use this for broad discovery or when a later step will filter relevance.

When :targets includes :resources and the flow omits the retrieval knobs, the runtime defaults resource retrieval to :mode :hybrid and :keyword-mode :balanced. If the flow explicitly sets :mode :lexical and omits :keyword-mode, keyword matching defaults back to strict :all. Workspace entity-only searches still report the legacy lexical/all defaults.

When :targets includes :resources, the step hydrates the top resource hits by default so flows can send full file or blob content to downstream steps without an extra fetch path.
Use :persist {:search-index ...} on the producing step when you need persisted artifacts to be easier to find later by text, tags, or source label.

Canonical Shape

Hydrate Config

Runtime Behavior

• Search scope is always the current workflow runtime workspace.
• workspace-id is taken from runtime context, not step input.
• Search clients are injected by runtime wiring:
  • resources search client
  • workspace search client (flows/runs/connections)
• If a requested target has no configured search client, step execution fails with a validation error.
• :mode applies only to :resources hits.
• :lexical always uses lexical resource search.
• :keyword-mode applies only to resource lexical matching. It does not change :flows, :runs, or :connections workspace search.
• :keyword-mode :balanced supports recognized query-string syntax such as quoted phrases, wildcards, fuzzy suffixes, boosts, resource field filters, and uppercase AND/OR/NOT. Ordinary punctuation in literal text or resource URIs stays on the keyword path.
• :hybrid uses semantic retrieval only when the Elastic resource-search backend has semantic reads enabled and no explicit sort is requested; otherwise it returns lexical results with fallback diagnostics.
• :semantic requires semantic reads and a non-blank query. If semantic reads are unavailable, the request fails loudly.
• :flows, :runs, and :connections still use workspace search.
• Local memory search and emulator fallback stay lexical.
• Explicit sorting disables hybrid semantic ranking. Sorted resource searches keep deterministic lexical/index ordering.
• Resource hydration uses the runtime workspace resource store and preserves workspace isolation.
• Hydration only applies to :resources hits.
• :storage-backend, :storage-root, and :path-prefix apply only to :resources hits.
• The resource index keeps both the full physical path and normalized storage fields (storage_backend, storage_root, path_under_root).
• :path-prefix is interpreted against path_under_root, so it stays relative to the effective storage root instead of the absolute workspace storage path.
• Text-like resources return inline :content.
• Non-text resources return :content-url with :hydration-status :linked-binary.
• Oversized or failed reads keep the hit and mark :hydration-status instead of failing the whole search step.

Public Docs Retrieval

:search does not search Breyta public docs directly. It only searches the current workflow runtime workspace.

When a flow needs Breyta docs at runtime, use an explicit :http step against the public docs API:

• search docs pages with GET /api/docs/pages
• fetch page content with GET /api/docs/pages/:slug?format=md

Use a :http-api connection slot with :base-url "https://flows.breyta.ai" so the flow body only contains API paths. See Step HTTP for a complete copy-pasteable example.

Searchable Resource Lifecycle

Resource search is workspace-scoped and runs over indexed resource metadata plus indexed text when available.

The most common searchable resource sources are:

• workspace files
• persisted step artifacts (res://...)
• HTTP page responses auto-indexed by :http
• retained artifacts whose indexed text/metadata were customized with :persist {:search-index ...}

Use :search-index inside the :persist map when the stored payload bytes are not the best search text on their own, or when the resource should show a more useful label in search results.

Successful :http GET responses for page-like content can be auto-persisted and indexed. This covers HTML, markdown, and article-like plain text pages. See Step HTTP for defaults and opt-out.

When semantic resource search is enabled, indexed article/page text is available to semantic ranking. When it is disabled, the same resources are still found through lexical keyword and metadata matching.

For fast operator proof outside the flow runtime, start with:

breyta resources search "refund support bundle" --mode hybrid --keyword-mode balanced
breyta steps run --type search --id kb-search \
  --params '{"query":"refund support bundle","targets":["resources"],"mode":"hybrid","keyword-mode":"balanced","hydrate":{"enabled":true}}'

Result Shape

{:query "refund policy"
 :mode :lexical
 :keyword-mode :balanced
 :requested-mode :hybrid
 :semantic-fallback? true
 :semantic-fallback-reason "semantic-index-unavailable"
 :targets [:resources :flows]
 :limit 12
 :grouped {:resources [{:target :resources
                        :title "Refund policy"
                        :uri "res://..."
                        :content "Full file content..."
                        :content-type "text/markdown"
                        :size-bytes 1842
                        :content-truncated? false
                        :hydration-status :inline-text}]
           :flows [...]
           :runs []
           :connections []}
 :results [...]} ; flattened in requested target order

Hydrated resource hits may include:

• :content
• :content-url
• :content-type
• :size-bytes
• :content-truncated?
• :hydration-status as one of :inline-text, :linked-binary, :too-large, :read-error, :skipped
• :hydration-error

When :mode :hybrid cannot use semantic retrieval, the step keeps returning
lexical results and includes :requested-mode, :semantic-fallback?, and
:semantic-fallback-reason. Strict :mode :semantic does not fall back.

Canonical Example

'(let [hits (flow/step :search :knowledge
              {:query (:question (flow/input))
               :mode :hybrid
               :keyword-mode :balanced
               :targets [:resources :flows :runs]
               :storage-backend :gcs
               :storage-root "reports/acme"
               :path-prefix "exports/2026"
               :limit 10
               :hydrate {:top-k 5
                         :max-chars 20000}})]
   hits)

Persist, index, and retrieve later:

'(let [bundle (flow/step :function :persist-support-bundle
                {:input {:rows (:rows (flow/input))}
                 :code '(fn [{:keys [rows]}] rows)
                 :persist {:type :blob
                           :path "support/bundles"
                           :filename "refund-bundle.json"
                           :content-type "application/json"
                           :search-index {:text "refund support bundle refunds chargebacks returns"
                                          :tags ["refund" "support" "bundle"]
                                          :source-label "Refund support bundle"
                                          :include-raw-content? true}}})
       hits (flow/step :search :find-support-bundle
              {:query "refund support bundle"
               :keyword-mode :balanced
               :targets [:resources]
               :limit 5
               :hydrate {:enabled true
                         :top-k 1
                         :max-chars 20000}})]
   {:bundle bundle
    :hits hits})

Related

• Step Reference
• Persisted Results And Resource Refs