Pathom Datomic
This package includes functions to integrate Datomic with Pathom Connect.
|
|
Project in alpha state, need volunteers to try it out! |
Also, this project uses the reader3 from Pathom, which also still needs production
grade testing. I recommend this project for people trying to experiment
and help the development of these new pieces, if you need production tested implementations
its better to avoid pathom-datomic at this time.
Setup
Currently supported only with deps:
{:deps {com.wsscode/pathom-datomic {:git/url "https://github.com/wilkerlucio/pathom-datomic.git"
:sha "d1ebb8447342a7b1279dc23bc4ab9942a4d8171b"}}Integration
Using this integration, you provide the Datomic connection to Pathom, then it loads your Datomic schema and delegates sub queries to Datomic automatically.
The examples in this documentation will be using the Datomic mbrainz sample database.
Example setup:
(ns com.wsscode.pathom.connect.datomic-test
(:require [clojure.test :refer :all]
[com.wsscode.pathom.connect :as pc]
[com.wsscode.pathom.connect.datomic :as pcd]
[com.wsscode.pathom.connect.datomic.on-prem :refer [on-prem-config]]
[com.wsscode.pathom.core :as p]))
(def whitelist-attributes
#{:artist/country
:artist/gid
:artist/name
:artist/sortName
:artist/type
:country/name
:medium/format
:medium/name
:medium/position
:medium/trackCount
:medium/tracks
:release/artists
:release/country
:release/day
:release/gid
:release/labels
:release/language
:release/media
:release/month
:release/name
:release/packaging
:release/script
:release/status
:release/year
:track/artists
:track/duration
:track/name
:track/position})
(def parser
(p/parser
{::p/env {::p/reader [p/map-reader
pc/reader3
pc/open-ident-reader
p/env-placeholder-reader]
::p/placeholder-prefixes #{">"}}
::p/mutate pc/mutate
::p/plugins [(pc/connect-plugin {::pc/register []})
; (1)
(pcd/datomic-connect-plugin (assoc on-prem-config
::pcd/conn conn
::pcd/whitelist whitelist-attributes}))
p/error-handler-plugin
p/trace-plugin]}))-
Datomic connect integration plugin. The whilelist part is where you decide which attribute are going to be automatically available.
|
ℹ️
|
We are using the on-prem config for this tutorial, if you wanna connect using
the client api, get the config from com.wsscode.pathom.connect.datomic.client/client-config
|
This setup will automatically provides entry points for every Datomic attribute marked
with :unique true.
|
🔥
|
If you add :db/id to the whitelist, you can allow referencing using it, but
be careful, if nothing else is done (via plugin or other way) to secure access, this means
any user of the API could see any entity.
|
Example queries we can run:
(parser {}
[{[:db/id 637716744120508]
[:artist/name]}])
; => {[:db/id 637716744120508] {:artist/name "Janis Joplin"}}
(parser {}
[{[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"]
[:artist/name
{:artist/country [:country/name]}]}])
; => {[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"]
; #:artist{:name "Janis Joplin"
; :country #:country{:name "United States"}}}When Pathom sees a Datomic attribute, it will compute the sub-query that should be
delegated to Datomic, issue a single pull to fulfil the data, and them walk the
results to fulfil any extra data that need to come from other resolvers.
To illustrate this point, let’s add a new resolver to the game and play with it in the query, this resolver will count the number of years that some artist was active, considering the start and end year data points:
(pc/defresolver years-active [env {:artist/keys [startYear endYear]}]
{::pc/input #{:artist/startYear :artist/endYear}
::pc/output [:artist/active-years-count]}
{:artist/active-years-count (- endYear startYear)})
; then add it to the connect-plugin definition, as:
; (pc/connect-plugin {::pc/register [years-active]})Time to play:
(parser {}
[{[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"]
[:artist/active-years-count]}])
; {[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"] #:artist{:active-years-count 27}}Notice that Pathom was able to automatically figure out the dependencies and compute
the appropriated pull request, which in this case was [:artist/startYear :artist/endYear].
Datomic ident values
If you used the Datomic pull syntax, you know this kind of result:
(parser {}
[{[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"]
[:artist/type]}])
=>
; => {[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"] #:artist{:type #:db{:id 17592186045423}}}
; if you are familiar with pull, you know the drill:
(parser {}
[{[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"]
[{:artist/type [:db/ident]}])
=>
; => {[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"] #:artist{:type #:db{:ident :artist.type/person}}}Not so good, even with the version we get the actual value :artist.type/person, we still
have to unwrap that.
To facilitate this common scenario, you can configure the integration and tell Pathom
which attributes should behave as ident attributes, this means if you don’t do a sub
query on them, Pathom will request the :db/ident and unwrap automatically:
; just the changes to the datomic connect plugin:
(pcd/datomic-connect-plugin (assoc on-prem-config
::pcd/conn conn
::pcd/ident-attributes #{:artist/type}))
; now a different result
(parser {}
[{[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"]
[:artist/type]}])
=>
; => {[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"]
#:artist{:type :artist.type/person}}
; you can still get the entity data using a sub query:
(parser {}
[{[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"]
[{:artist/type [:db/id]}]}])
=>
; => {[:artist/gid #uuid"76c9a186-75bd-436a-85c0-823e3efddb7f"] #:artist{:type #:db{:id 17592186045423}}}Custom queries
To handle custom sets of entities, we recommend using the helpers query-entity and
query-entities, provided by this library, examples:
(pc/defresolver artists-before-1600 [env _]
{::pc/output [{:artist/artists-before-1600 [:db/id]}]}
{:artist/artists-before-1600
(pcd/query-entities env
'{:where [[?e :artist/name ?name]
[?e :artist/startYear ?year]
[(< ?year 1600)]]})})
; using the resolver
(parser {}
[{:artist/artist-before-1600
[:artist/name
:artist/active-years-count
{:artist/country
[:country/name]}]}])
=>
; #:artist{:artist-before-1600 #:artist{:name "Heinrich Schütz",
; :active-years-count 87,
; :country #:country{:name "Germany"}}}Note the Datalog query must use the map format. The :find part will be automatically
fulfilled by Pathom, considering the sub query requested in the process, this way you
don’t need to care ahead of time.
Opening all data
You can enable the integration to pull everything from Datomic, this can be useful on initial development, but be aware this opens the entire Datomic to the external world.
To do this, use ::pcd/whitelist ::pcd/DANGER_ALLOW_ALL!.
Next steps
We need to figure a way to handle security, currently this integration opens too much for most use cases, if you have ideas please let’s talk at #pathom on Clojurians!