toucan.hydrate — toucan 1.15.1

Functions for deserializing and hydrating fields in objects fetched from the DB.

flush-hydration-key-caches! clj

(flush-hydration-key-caches!)

Clear out the cached hydration keys. Useful when doing interactive development and defining new hydration functions.

hydrate clj

(hydrate results k & ks)

Hydrate a single object or sequence of objects.

Automagic Batched Hydration (via hydration-keys)

hydrate attempts to do a batched hydration where possible. If the key being hydrated is defined as one of some model's hydration-keys, hydrate will do a batched db/select if a corresponding key ending with _id is found in the objects being batch hydrated.

(hydrate [{:user_id 100}, {:user_id 101}] :user)

Since :user is a hydration key for User, a single db/select will used to fetch Users:

(db/select User :id [:in #{100 101}])

The corresponding Users are then added under the key :user.

Function-Based Batched Hydration (via functions marked ^:batched-hydrate)

If the key can't be hydrated auto-magically with the appropriate :hydration-keys, hydrate will look for a function tagged with :batched-hydrate in its metadata, and use that instead. If a matching function is found, it is called with a collection of objects, e.g.

(defn with-fields
  "Efficiently add `Fields` to a collection of TABLES."
  {:batched-hydrate :fields}
  [tables]
  ...)

(let [tables (get-some-tables)]
  (hydrate tables :fields))     ; uses with-fields

By default, the function will be used to hydrate keys that match its name; as in the example above, you can specify a different key to hydrate for in the metadata instead.

Simple Hydration (via functions marked ^:hydrate)

If the key is not eligible for batched hydration, hydrate will look for a function or method tagged with :hydrate in its metadata, and use that instead; if a matching function is found, it is called on the object being hydrated and the result is assoced:

(defn ^:hydrate dashboard [{:keys [dashboard_id]}]
  (Dashboard dashboard_id))

(let [dc (DashboardCard ...)]
  (hydrate dc :dashboard))    ; roughly equivalent to (assoc dc :dashboard (dashboard dc))

As with :batched-hydrate functions, by default, the function will be used to hydrate keys that match its name; you can specify a different key to hydrate instead as the metadata value of :hydrate:

(defn ^{:hydrate :pk_field} pk-field-id [obj] ...) ; hydrate :pk_field with pk-field-id

Keep in mind that you can only define a single function/method to hydrate each key; move functions into the IModel interface as needed.

Hydrating Multiple Keys

You can hydrate several keys at one time:

(hydrate {...} :a :b)
  -> {:a 1, :b 2}

Nested Hydration

You can do recursive hydration by listing keys inside a vector:

(hydrate {...} [:a :b])
  -> {:a {:b 1}}

The first key in a vector will be hydrated normally, and any subsequent keys will be hydrated inside the corresponding values for that key.

(hydrate {...}
         [:a [:b :c] :e])
  -> {:a {:b {:c 1} :e 2}}