`(pull $db ?entity pattern)` is undocumented

Datomic Cloud
1

It is possible to supply a src-var argument to a pull function within a Datalog query (as demonstrated below), though the documentation only mentions the 2 arity variant:

pull-expr = [‘pull’ variable pattern]
pattern = (pattern-name | pattern-data-literal)

I can imagine it’s not a common use-case, but it would be helpful to document this explicitly, so less experienced users are not left to wonder, UNLESS it’s not an intentionally supported feature.

The example also shows, that omitting the src-var implies the use of the 1st src-var.

(ns xxx
  (:require [datomic.client.api :as d]))

(set! *print-namespace-maps* false)

; (pull $? e [*])
(comment
  @(def dc (d/client {:server-type :dev-local :storage-dir :mem :system "sys"}))
  (def db-1-ref {:db-name "db-1"})
  (def db-2-ref {:db-name "db-2"})
  (d/create-database dc db-1-ref)
  (d/create-database dc db-2-ref)
  @(def conn-1 (d/connect dc db-1-ref))
  @(def conn-2 (d/connect dc db-2-ref))

  (def schema
    [{:db/ident       :external/id
      :db/valueType   :db.type/long
      :db/cardinality :db.cardinality/one
      :db/unique      :db.unique/value}])

  (d/transact conn-1 {:tx-data schema})
  (d/transact conn-1 {:tx-data [{:external/id 123 :db/doc "db-1"}]})

  (d/transact conn-2 {:tx-data schema})
  (d/transact conn-2 {:tx-data [{:external/id 123 :db/doc "db-2"}]})

  (d/q '{:find  [(pull ?e1 [*])]
         :in    [$1 $2]
         :where [[$1 ?e1 :external/id ?xid]
                 [$2 ?e2 :external/id ?xid]]}
       (d/db conn-1)
       (d/db conn-2))

  ;=> [[{:db/id 101155069755466, :db/doc "db-1", :external/id 123}]]

  (d/q '{:find  [(pull ?e2 [*])]
         :in    [$1 $2]
         :where [[$1 ?e1 :external/id ?xid]
                 [$2 ?e2 :external/id ?xid]]}
       (d/db conn-1)
       (d/db conn-2))

  ;=> [[{:db/id 74766790688842}]]
 
  (d/q '{:find  [(pull $2 ?e2 [*])]
         :in    [$1 $2]
         :where [[$1 ?e1 :external/id ?xid]
                 [$2 ?e2 :external/id ?xid]]}
       (d/db conn-1)
       (d/db conn-2))

  ;=> [[{:db/id 74766790688842, :db/doc "db-2", :external/id 123}]]

  (d/delete-database dc db-1-ref)
  (d/delete-database dc db-2-ref)
  (d/list-databases dc {})

  )
2

I’ve cross-posted this here: