Pull Expressions

Every query so far has listed each desired attribute as a separate :find variable. Pull lets you retrieve a whole entity, or a chosen subset of its attributes, as a single map, without enumerating every binding explicitly.

The syntax is (pull ?e pattern) inside :find, where pattern is a vector of attribute keywords (or [*] for all of them).

Selective pull

List only the attributes you care about. Here we fetch name and speed for every Pokemon faster than 100, getting back one map per entity instead of a two-column tuple:

Each result row contains a single map. This is especially useful when returning wide entities. Without pull, every attribute needs its own variable in :find and its own clause in :where, and each row is a flat tuple:

With pull, the same Pokemon and attributes need one expression, and each row is a map that names its own values:

Pull keeps entities that a join would drop

The Modeling data chapter showed that a join silently drops any entity missing one of its attributes. Only 4 Pokemon have a :pokemon/category, so joining it returns only those 4 names:

Pull instead keeps every entity, whether or not it has the attribute, with the key simply absent when there is nothing to pull. Wrapping the pull in a collection find spec ([...]) returns one map per entity, the form you will reach for most often in real code:

All 151 Pokemon come back, most without a :pokemon/category key at all. get-else, from Function clauses, fills in a default for a join; pull's own :default option below does the same.

Wildcard pull

Use [*] to pull every attribute on the entity, including Datomic's own :db/id:

The wildcard is handy for exploration and debugging. In production code, prefer listing attributes explicitly so the shape of your data is clear and stable.

Pikachu evolves, so its wildcard pull also returns :evolution/next. That attribute is a reference to another entity, so all a wildcard gives you is its :db/id. The sections below show how to follow it.

Pull with scalar find spec

Combine pull with the scalar find spec (.) to get a single entity map with no wrapping collection or tuple:

The result is a bare map, easy to pass directly to the rest of your application. Note that :pokemon/type comes back as ["Electric"], a vector, even though Pikachu has only one. Pull always returns a cardinality-many attribute as a collection, no matter how many values the entity actually has.

Attribute options

Wrap an attribute in a list to give it options. The first is :as, which renames the key in the result:

:limit caps how many values a cardinality-many attribute returns. Bulbasaur has two types, but this returns only one of them:

:default supplies a value when the entity doesn't have the attribute at all. Bulbasaur has no :pokemon/category, so we get the default. Without one, the key would be left out of the map:

Options can be combined in one pattern, each on its own attribute:

Your turn. Pull Pikachu's name under the key "name", and its :evolution/next with a default of :none. Then try the same for Raichu.

Following references

:evolution/next is a reference: its value is another entity. To pull that entity too, put the attribute in a map with a pattern for the entity it points at:

The value of :evolution/next is now a collection of maps, one for each Pokemon Charmander evolves into, and each map follows the pattern we gave it.

A pattern can follow several references at once, each with its own pattern. Here is everything the database knows about Fire's matchups:

Reverse lookups

Put an underscore in front of the attribute name to follow a reference backwards. :evolution/_next finds the entities whose :evolution/next points at this one:

Charizard evolves from Charmeleon. Nothing had to be stored twice: a reference can be followed in either direction.

Recursion

Use ... instead of a pattern to follow the same reference again and again, for as long as there is something to follow. A number, like {:evolution/next 2}, limits how many levels to follow:

This gives Charmander's whole evolution line as a nested map.