Step DB Firestore

Quick Answer

Use :db with :database :firestore, a bound :connection, and Firestore query fields (:collection, :where, :order-by, :limit).
Firestore DB queries are collection-based, not SQL-based.

Canonical Shape

Field	Type	Required	Notes
`:database`	keyword/string	Yes	Must be `:firestore`
`:connection`	keyword/string	Yes	Bound Firestore connection
`:collection`	keyword/string	Yes	Collection to query
`:where`	vector	No	Clauses: `[field op value]`
`:order-by`	vector	No	Clauses: `[field :asc/:desc]`
`:limit`	int	No	Default `100`, max `1000`

Supported `:where` Operators

:=
:!=
:<, :<=, :>, :>=
:in
:contains
:contains-any

Canonical Example

{:functions [{:id :rollup-usage
              :language :clojure
              :code "(fn [docs] {:count (count docs) :total-units (reduce + 0 (map #(or (:units %) 0) docs))})"}]
 :flow
 '(let [input (flow/input)
        docs (flow/step :db :fetch-metering-events
               {:database :firestore
                :connection :billing-firestore
                :collection :metering-events
                :where [[:workspace-id := (:workspace-id input)]
                        [:period := (:period input)]
                        [:status := :finalized]]
                :order-by [[:event-ts :asc]]
                :limit 1000})
        summary (flow/step :function :summarize-events
                  {:ref :rollup-usage
                   :input docs})]
    {:summary summary
     :documents docs})}

Limits And Behavior

Use deterministic filters and ordering for repeatable queries
Keep result sets bounded; use :limit and narrow predicates
Firestore pagination by offset is not supported in this step shape

Connection And Binding Recipe

{:requires [{:slot :billing-firestore
             :type :database
             :backends #{:firestore}
             :label "Billing Firestore"}]}

breyta connections list --type database
breyta flows configure <slug> --set billing-firestore.conn=conn-...

Query And Index Design Checklist

use equality filters for tenant/workspace partitioning first
keep :order-by aligned with your range/sort access pattern
keep :limit explicit and bounded (default is 100)
expect composite index requirements for more complex filter/order combinations
for high-volume reads, emit compact summaries in function steps before returning flow outputs

Data And Filter Pitfalls

values in :where are normalized for Firestore compatibility (keywords become strings)
make sure filter value types match stored document field types
avoid unbounded collection scans; combine selective predicates with bounded :limit
Firestore offset pagination is not supported in this step shape

Failure Triage

missing collection/config: verify :collection and bound connection
permission/auth failures: verify service account access to the project/database
large result errors: tighten :where, lower :limit, and persist downstream artifacts instead of returning full docs

Output Shape

Firestore DB steps return maps (documents) and include document :id.