Pull
Pull is a declarative way to make hierarchical (and possibly nested) selections of information about entities. Pull applies a pattern to a collection of entities, building a map for each entity. Pull is available
- as a standalone pull API
- as a find specification in query.
Patterns support forward and reverse attribute navigation, wildcarding, nesting, recursion, naming control, defaults, and limits on the results returned. Entities can be passed to pull as any kind of entity identifier: entity ids, idents, or lookup refs.
Pull patterns are written in the Extensible Data Notation (edn), which is programming language neutral. In programs, you can create patterns programmatically out of your basic language data types, e.g. Java Strings, Lists, and Maps. Alternatively, you can pass the pattern argument as a serialized edn string.
The results below are also written with edn, and they use an ellipsis
...
where large results have been elided for brevity.
Clojure source for the examples on this page can be found in the Day of Datomic Cloud repository.
Pull Grammar
Grammar Syntax
'' literal "" string [] = list or vector {} = map {k1 v1 ...} () grouping | choice + one or more
Pull Pattern Grammar
pattern = [attr-spec+] attr-spec = attr-name | wildcard | map-spec | attr-with-opts | attr-expr attr-name = an edn keyword that names an attr map-spec = { ((attr-name | limit-expr) (pattern | recursion-limit))+ } attr-with-opts = [attr-name attr-options+] attr-options = :as any-value | :limit (positive-number | nil) | :default any-value wildcard = "*" or '*' recursion-limit = positive-number | '...' attr-expr = limit-expr | default-expr limit-expr = [("limit" | 'limit') attr-name (positive-number | nil)] default-expr = [("default" | 'default') attr-name any-value]
Terminals such as "limit" can be strings, but where languages have a
symbol type you should prefer the idiomatic symbolic type,
e.g. (limit :friends 100)
in Clojure instead of ("limit" "friends" 100)
.
Attribute Specifications
attr-spec = attr-name | map-spec | attr-with-opts | wildcard | attr-expr attr-name = an edn keyword that names an attr map-spec = { ((attr-name | limit-expr) (pattern | recursion-limit))+ } attr-with-opts = [attr-name attr-options+] attr-options = :as any-value | :limit (positive-number | nil) | :default any-value wildcard = "*" or '*' attr-expr = limit-expr | default-expr
An attribute spec specifies an attribute to be returned, and (optionally) how that attribute should be returned. Attribute specs can be attribute names, wildcards, map specs, or attribute expressions.
Attribute Names
attr-name = an edn keyword that names an attr
An attribute spec names an attribute, with an optional leading underscore on the local name to reverse the direction of navigation.
Attribute Name Example
The following pattern uses two attribute names to return an :artist/name
and :artist/startYear
, pulling on ledZeppelin:
;; pattern [:artist/name :artist/gid] ;; result {:artist/gid #uuid "678d88b2-87b0-403b-b63d-5da7465aecc3", :artist/name "Led Zeppelin"}
Reverse Lookup
An underscore prefix (_
) on the local name component of an attribute
name causes the attribute to be navigated in reverse.
Attribute Name Reverse Lookup Example
You navigate backwards from :country/GB
to British artists by
pulling :artist/country
:
;; pattern [:artist/_country] ;; result {:artist/_country [{:db/id 17592186045751} {:db/id 17592186045755} ...]}
Map Specifications
map-spec = { ((attr-name | limit-expr) (pattern | recursion-limit))+ } limit-expr = [("limit" | 'limit') attr-name (positive-number | nil)] recursion-limit = positive-number | '...'
You can explicitly specify the handling of referenced entities by using
a map instead of just an attribute name. The simplest map
specification is a map specifying a specific pattern
for a
particular attr-name
.
Map Specification Example
The :track/artists
attribute appears in a map spec, causing the
:db/id
and :artist/name
to be sub-pulled for each artist on the
track ghostRiders:
;; pattern [:track/name {:track/artists [:db/id :artist/name]}] ;; result {:track/artists [{:db/id 17592186048186, :artist/name "Bob Dylan"} {:db/id 17592186049854, :artist/name "George Harrison"}], :track/name "Ghost Riders in the Sky"}
Map Specification Nesting Example
Map specs can nest arbitrarily. The pattern below pulls
concertForBanglaDesh
's media's tracks' titles and artists' names:
;; pattern [{:release/media [{:medium/tracks [:track/name {:track/artists [:artist/name]}]}]}] ;; result [{:medium/tracks [{:track/artists [{:artist/name "Ravi Shankar"} {:artist/name "George Harrison"}], :track/name "George Harrison / Ravi Shankar Introduction"} {:track/artists [{:artist/name "Ravi Shankar"}], :track/name "Bangla Dhun"}]} {:medium/tracks [{:track/artists [{:artist/name "George Harrison"}], :track/name "Wah-Wah"} {:track/artists [{:artist/name "George Harrison"}], :track/name "My Sweet Lord"} {:track/artists [{:artist/name "George Harrison"}], :track/name "Awaiting on You All"} {:track/artists [{:artist/name "Billy Preston"}], :track/name "That's the Way God Planned It"}] ...]}
Attribute With Options
attr-with-opts = [attr-name attr-options+] attr-options = :as any-value | :limit (positive-number | nil) | :default any-value
The Attributes With Options specification provides control of various aspects of the values returned by the pull of an attribute.
:as Option
[attr-name :as any-value]
The :as
option allows replacement of the key for an attribute result map with an arbitrary value.
:limit Option
[attr-name :limit (positive-number | nil)]
The :limit option controls how many values will be returned for a cardinality-many attribute. A limit can be a positive number or nil. A nil limit causes all values to be returned, and should be used with caution.
In the absence of an explicit limit, pull will return the first 1000 values for a cardinality-many attribute.
:limit Option Example
To return only 10 of ledZeppelin's tracks:
;; pattern [:artist/name (:track/_artists :limit 10)] ;; result {:artist/name "Led Zeppelin", :track/_artists [{:db/id 17592186057344} {:db/id 17592186057345} {:db/id 17592186057346} {:db/id 17592186057347} {:db/id 17592186057348} {:db/id 17592186057349} {:db/id 17592186057350} {:db/id 17592186057351} {:db/id 17592186057352} {:db/id 17592186057355}]}
:limit Inside a Map Specification Example
Pulling from ledZeppelin', you can get a limited set of nested track names with:
;; pattern [{(:track/_artists :limit 10) [:track/name]}] ;; result {:track/_artists [{:track/name "Whole Lotta Love"} {:track/name "What Is and What Should Never Be"} {:track/name "The Lemon Song"} {:track/name "Thank You"} {:track/name "Heartbreaker"} {:track/name "Living Loving Maid (She's Just a Woman)"} {:track/name "Ramble On"} {:track/name "Moby Dick"} {:track/name "Bring It on Home"} {:track/name "Whole Lotta Love"}]}
Nil :limit Example
Ths pattern below returns all of Led Zeppelin's tracks, without limit:
;; pattern [:artist/name (:track/_artists :limit nil)] ;; result {:artist/name "Led Zeppelin", :track/_artists [{:db/id 17592186057344} {:db/id 17592186057345} {:db/id 17592186057346} {:db/id 17592186057347} {:db/id 17592186057348} {:db/id 17592186057349} {:db/id 17592186057350} {:db/id 17592186057351} {:db/id 17592186057352} {:db/id 17592186057355} {:db/id 17592186057356} {:db/id 17592186057357} {:db/id 17592186057358} {:db/id 17592186057359} {:db/id 17592186057360} {:db/id 17592186057361} {:db/id 17592186057362} {:db/id 17592186057363} {:db/id 17592186057366} {:db/id 17592186057367} ...]} ;; lots more
:default Option
[attr-name :default any-value]
The :default option specifies a value to use if an attribute is not present for an entity.
:default Option Example
The following select reports a zero :artist/endYear for Paul McCartney, who is still active:
;; pattern [:artist/name (:artist/endYear :default 0)] ;; result {:artist/endYear 0, :artist/name "Paul McCartney"}
The default need not be of the same type as the attribute's values:
;; pattern [:artist/name (:artist/endYear :default "N/A")] ;; result {:artist/endYear "N/A", :artist/name "Paul McCartney"}
Wildcards
wildcard = "*" or '*'
The wildcard specification *
pulls all attributes of an entity, and
recursively pulls any component attributes:
Wildcard Example
The wildcard pulls all the direct attributes of the release. It also
recursively pulls :release/media
because it is a component
attribute. It does not recursively pull :release/artists
or
:release/country
, because those are not component attributes.
;; pattern [*] ;; result {:release/name "The Concert for Bangla Desh", :release/artists [{:db/id 17592186049854}], :release/country {:db/id 17592186045504}, :release/gid #uuid "f3bdff34-9a85-4adc-a014-922eef9cdaa5", :release/day 20, :release/status "Official", :release/month 12, :release/artistCredit "George Harrison", :db/id 17592186072003, :release/year 1971, :release/media [{:db/id 17592186072004, :medium/format {:db/id 17592186045741}, :medium/position 1, :medium/trackCount 2, :medium/tracks [{:db/id 17592186072005, :track/duration 376000, :track/name "George Harrison / Ravi Shankar Introduction", :track/position 1, :track/artists [{:db/id 17592186048829} {:db/id 17592186049854}]} {:db/id 17592186072006, :track/duration 979000, :track/name "Bangla Dhun", :track/position 2, :track/artists [{:db/id 17592186048829}]}]} ... ]}
Combining Wildcards and Map Specifications
A map specification can be used in conjunction with the wildcard to provide subpatterns for specific attributes.
- Combining Wildcards and Map Specifications Example
The wildcard pulls all attributes of the ghostRiders track, and an explicit map overrides the handling of
:track/artists
to pull:artist/name
.;; pattern ["*" {:track/artists [:artist/name]}] ;; result {:db/id 17592186063810, :track/duration 218506, :track/name "Ghost Riders in the Sky", :track/position 11, :track/artists [{:artist/name "Bob Dylan"} {:artist/name "George Harrison"}]}
Recursion Limits
recursion-limit = positive-number | '...' map-spec = { ((attr-name | limit-expr) (pattern | recursion-limit))+ }
A map specification can govern recursion. If a map specification has a
numeric value, then the selector containing that specification will be
applied recursively up to N times. The ellipsis symbol (...
) will
follow recursive references to arbitrary depth, and should be used
with caution!
If a recursive subselect encounters an entity that it has already seen,
it will not apply the pattern, instead returning only the :db/id
of
the entity. Thus recursive select is safe in the presence of cycles.
Limited Recursion Example
The following (non-mbrainz) specification will pull the first and last names of friends-of-friends up to six degrees of separation from the original entity.
[:person/firstName :person/lastName {:person/friends 6}]
Unlimited Recursion Example
The following specification will find all reachable friends, which might be most of the friends in the entire database.
[:person/firstName :person/lastName {:person/friends ...}]
Empty Results
If there is no match between a pattern and an entity, then pull
will
return nil (not an empty map):
;; pattern [:penguins] ;; entity led-zeppelin ;; result nil
Non-matching results will be removed entirely from collections. Even
though ghost-riders has artists, none of those artists have
:penguins
:
;; pattern [{:track/artists [:penguins]}] ;; entity ghost-riders ;; result {:track/artists []}
Pull Results
Component Defaults
If a pull attr-name
names a reference attribute, pull
will return
a map for the referenced value. If the attribute is a component
attribute, the map will contain all attributes of the related entity
as well.
- Component Defaults Example
:medium/tracks
is a component attribute, so pulling:release/media
will also pull related tracks. The example below pulls from darkSideOfTheMoon.;; pattern [:release/media] ;; result {:release/media [{:db/id 17592186121277, :medium/format {:db/id 17592186045741}, :medium/position 1, :medium/trackCount 10, :medium/tracks [{:db/id 17592186121278, :track/duration 68346, :track/name "Speak to Me", :track/position 1, :track/artists [{:db/id 17592186046909}]} {:db/id 17592186121279, :track/duration 168720, :track/name "Breathe", :track/position 2, :track/artists [{:db/id 17592186046909}]} {:db/id 17592186121280, :track/duration 230600, :track/name "On the Run", :track/position 3, :track/artists [{:db/id 17592186046909}]} ...]}]}
Non-Component Defaults
If a reference is to a non-component attribute, the default is to pull
only the :db/id
.
- Non-Component Defaults Example
Pulling
:artist/_{country}
of:country/GB
returns only the entity ids for the artists from Great Britain:;; pattern [:artist/_country] ;; result {:artist/_country [{:db/id 17592186045751} {:db/id 17592186045755} ...]}
Multiple Results
If navigating an attribute might lead to more than one value, the pull result will be a list of the values found. These cases include:
- All forward cardinality-many references
- Reverse references for non-component attributes.
- Multiple Results Example
Pulling
:artist/_{country}
of:country/GB
returns a list of the entity ids for the artists from Great Britain:;; pattern [:artist/_country] ;; result {:artist/_country [{:db/id 17592186045751} {:db/id 17592186045755} ...]}
Missing Attributes
In the absence of a default, attribute specifications that do not match
an entity are omitted from that entity's result map, rather than
e.g. appearing with a nil
value.
- Missing Attributes Example
Paul McCartney has an
:artist/name
but not adied-in-1966
, so only the former appears in a pull result:;; pattern [:artist/name :died-in-1966?] ;; result {:artist/name "Paul McCartney"}
Attribute Expressions
NOTE: Attributes With Options provides a superset of the functionality of Attribute Expressions and is preferred, however
limit
anddefault
Attribute Expressions will continue to be supported.
attr-expr = limit-expr | default-expr limit-expr = [("limit" | 'limit') attr-name (positive-number | nil)] default-expr = [("default" | 'default') attr-name any-value]
Attribute specifications can be wrapped in expressions to control the attribute's default or limit. Each is shown below.
Limit Expression
limit-expr = [("limit" | 'limit') attr-name (positive-number | nil)]
A limit expression controls how many values will be returned for a cardinality-many attribute. A limit can be a positive number or nil. A nil limit causes all values to be returned, and should be used with caution.
In the absence of an explicit limit, pull
will return the first 1000
values for a cardinality-many attribute.
Limit Example
To return only 10 of ledZeppelin's tracks:
;; pattern [:artist/name (limit :track/_artists 10)] ;; result {:artist/name "Led Zeppelin", :track/_artists [{:db/id 17592186057344} {:db/id 17592186057345} {:db/id 17592186057346} {:db/id 17592186057347} {:db/id 17592186057348} {:db/id 17592186057349} {:db/id 17592186057350} {:db/id 17592186057351} {:db/id 17592186057352} {:db/id 17592186057355}]}
Limit Inside a Map Specification Example
Pulling from ledZeppelin's, you can get a limited set of nested track names with:
;; pattern [{(limit :track/_artists 10) [:track/name]}] ;; result {:track/_artists [{:track/name "Whole Lotta Love"} {:track/name "What Is and What Should Never Be"} {:track/name "The Lemon Song"} {:track/name "Thank You"} {:track/name "Heartbreaker"} {:track/name "Living Loving Maid (She's Just a Woman)"} {:track/name "Ramble On"} {:track/name "Moby Dick"} {:track/name "Bring It on Home"} {:track/name "Whole Lotta Love"}]}
Nil Limit Example
Ths pattern below returns all of Led Zeppelin's tracks, without limit:
;; pattern [:artist/name (limit :track/_artists nil)] ;; result {:artist/name "Led Zeppelin", :track/_artists [{:db/id 17592186057344} {:db/id 17592186057345} {:db/id 17592186057346} {:db/id 17592186057347} {:db/id 17592186057348} {:db/id 17592186057349} {:db/id 17592186057350} {:db/id 17592186057351} {:db/id 17592186057352} {:db/id 17592186057355} {:db/id 17592186057356} {:db/id 17592186057357} {:db/id 17592186057358} {:db/id 17592186057359} {:db/id 17592186057360} {:db/id 17592186057361} {:db/id 17592186057362} {:db/id 17592186057363} {:db/id 17592186057366} {:db/id 17592186057367} ...]} ;; lots more
Default Expressions
default-expr = [("default" | 'default') attr-name any-value]
A default expression specifies a value to use if an attribute is not
present for an entity. The following select reports a zero
:artist/endYear
for Paul McCartney, who is still active.
;; pattern [:artist/name (default :artist/endYear 0)] ;; result {:artist/endYear 0, :artist/name "Paul McCartney"}
The default need not be of the same type as the attribute's values:
;; pattern [:artist/name (default :artist/endYear "N/A")] ;; result {:artist/endYear "N/A", :artist/name "Paul McCartney"}
Next: Raw Index Access