toucan2.query — io.github.camsaul/toucan2 0.10.1.1-alpha

Query compilation pipeline is something like this:

Call something like [[toucan2.select/select]] with `modelable` and `unparsed-args`
↓
`modelable` is resolved to `model` with [[toucan2.model/with-model]]
↓
[[parse-args]] is used to parse args into a `parsed-args` map
↓
The `:queryable` key in parsed args is resolved and replaced with a `:query` by [[with-resolved-query]]
↓
[[build]] takes the `:query` in the parsed args and combines the other parsed args into it to build a
compilable query. The default backend builds a Honey SQL 2 query map
↓
some sort of reducible is returned.

<reducing the reducible>
↓
[[toucan2.compile/with-compiled-query]] compiles the built query (e.g. Honey SQL 2) into something that can be
executed natively (e.g. a `sql-args` vector)
↓
[[toucan2.connection/with-connection]] is used to get a connection from the current connectable, or the default
connectable for `model`, or the global default connectable
↓
Compiled query is executed with connection

*with-resolved-query-fn* clj

(*with-resolved-query-fn* model queryable f)

The function that should be invoked by with-resolved-query. By default, the multimethod do-with-resolved-query, but if you need to do some sort of crazy mocking you can swap it out with something else.

apply-kv-arg clj

(apply-kv-arg model query k v)

apply-kv-args clj

(apply-kv-args model query kv-args)

args-spec clj

(args-spec query-type)

[[clojure.spec.alpha]] spec that should be used to parse unparsed args for query-type by the default implementation of parse-args.

build clj

(build query-type model {:keys [query] :as parsed-args})

build takes the parsed args returned by [[parse]] and builds them into a query that can be compiled by toucan2.compile/with-compiled-query. For the default implementations, build takes the parsed arguments and builds a Honey SQL 2 map.

Dispatches on [query-type model query].

condition->honeysql-where-clause clj

(condition->honeysql-where-clause k v)

do-with-resolved-query clj

(do-with-resolved-query model queryable f)

Impls should resolve queryable to an unbuilt query that can be built by build and call

(f query)

Example:

;; define a custom query ::my-count that you can then use with select and the like
(m/defmethod do-with-resolved-query [:default ::my-count]
  [model _queryable f]
  (do-with-resolved-query model {:select [:%count.*], :from [(keyword (model/table-name model))]} f))

(select :model/user ::my-count)

Dispatches off of [modelable queryable].

parse-args clj

(parse-args query-type unparsed-args)

parse-args takes a sequence of unparsed args passed to something like toucan2.select/select and parses them into a parsed args map. The default implementation uses [[clojure.spec.alpha]] to parse the args according to the args-spec for query-type.

These keys are commonly returned by several of the different implementations parse-args, and other tooling is build to leverage them:

• :modelable -- usually the first of the unparsed-args, this is the thing that should get resolved to a model with toucan2.model/with-model.

• :queryable -- something that can be resolved to a query with with-resolved-query, for example a map or integer or 'named query' keyword. The resolved query is ultimately combined with other parsed args and built into something like a Honey SQL map with build, then compiled with toucan2.compile/with-compiled-query.

• :kv-args -- map of key-value pairs. When build builds a query, it calls apply-kv-arg for each of the key-value pairs. The default behavior is to append a Honey SQL :where clause based on the pair; but you can customize the behavior for specific keywords to do other things -- :toucan/pk is one such example.

• :columns -- for things that return instances, :columns is a sequence of columns to return. These are commonly specified by wrapping the modelable in a [modelable & columns] vector.

Dispatches off of query-type.

validate-parsed-args clj

(validate-parsed-args parsed-args)

with-resolved-query clj macro

(with-resolved-query [query-binding [model queryable]] & body)

Resolve a queryable to an unbuilt query and bind it to query-binding. After resolving the query the next step is to build it into a compilable query using build.

``clj (with-resolved-query [resolved-query [:model/user :some-named-query]] (build model :toucan2.select/select (assoc parsed-args :query resolved-query)))