toucan2.query — io.github.camsaul/toucan2 1.0.0-beta1

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

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.

condition->honeysql-where-clause clj

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

Something sequential like :id [:> 5] becomes [:> :id 5]. Other stuff like :id 5 just becomes [:= :id 5].

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].

honeysql-table-and-alias clj

(honeysql-table-and-alias model)

Build an Honey SQL [table] or [table alias] (if the model has a toucan2.model/namespace form) for model for use in something like a :select clause.

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.

validate-parsed-args clj

(validate-parsed-args parsed-args)

with-built-query clj macro

(with-built-query [built-query-binding
                   [query-type model parsed-args resolved-query]]
                  &
                  body)

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)))