Pull

'' literal
"" string
[] = list or vector
{} = map {k1 v1 ...}
() grouping
| choice
+ one or more

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

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"}

An underscore prefix (_) on the local name component of an attribute name causes the attribute to be navigated in reverse.

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

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

The following pattern uses an :as option to pull an :artist/name, replacing the key in the result map with the string "Band Name", pulling on ledZeppelin:

;; pattern
[:artist/name :as "Band Name"]

;; result
{"Band Name" "Led Zeppelin"}

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

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"}]}

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

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"}

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

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"}]}
  

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

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

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 []}

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

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

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

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 a died-in-1966, so only the former appears in a pull result:

  ;; pattern
  [:artist/name :died-in-1966?]
  
  ;; result
  {:artist/name "Paul McCartney"}
  

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

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"}]}

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