Clojure
Fluree has a Clojure client.
A note on terminology#
If you are familiar with Datomic, Datahike, Datascript, or Crux (or other Clojure triple-store+ databases) you may wonder at the difference in terminology between those databases and Fluree. Fluree uses RDF terminology to describe the relationships between entities, or subjects.
Here's a quick glossary of how your knowledge may map on to Fluree's terminology:
| Clojure Triple-Store+ term | Fluree term |
|---|---|
| entity | subject |
| attribute | predicate |
| value | object |
| datom | flake |
Setup#
Make sure you have a running Fluree ledger service to connect to. See the Getting Started docs for more details.
Add to the artifact to your dependencies:
Leiningen -
[com.fluree/db "1.0.0-rc22"]deps.edn -
com.fluree/db {:mvn/version "1.0.0-rc22"}Require the api and establish a connection to your Fluree server:
(require '[fluree.db.api :as fdb])
(def conn (fdb/connect "http://localhost:8090"))
(def ledger "example/test")
@(fdb/new-ledger conn ledger)Transacting#
transact is used to make any changes to the ledger, either adding data or schema. It's all data, and it all uses the same api to effect changes.
Schema#
All data transacted into a ledger must conform to a schema. We'll transact a basic schema below. See the Schema documentation for more details.
Create a collection, which you can think of as a type of entity, or a relational database table.
;; creates book and author collections@(fdb/transact conn ledger [{:_id :_collection :_collection/name :book} {:_id :_collection :_collection/name :author}])
;; can also use strings like in the Fluree docs:;; {"_id" "_collection" "_collection/name" "author"}Create some predicates for the collection, analogous to entity attributes or relational database columns.
@(fdb/transact conn ledger [{:_id :_predicate :_predicate/name :author/name :_predicate/doc "An author's complete name." :_predicate/unique true :_predicate/type :string :_predicate/upsert true}
{:_id :_predicate :_predicate/name :book/title :_predicate/doc "A book's title." :_predicate/unique true :_predicate/upsert true :_predicate/fullText true :_predicate/type :string} {:_id :_predicate :_predicate/name :book/notes :_predicate/doc "Any notes about the book" :_predicate/type :string} {:_id :_predicate :_predicate/name :book/authors :_predicate/doc "A book's authors." :_predicate/type :ref :_predicate/multi true :_predicate/restrictCollection :author} {:_id :_predicate :_predicate/name :book/tags :_predicate/doc "Tags for categorizing books." :_predicate/type :tag :_predicate/multi true}])
Data#
Insert some subject data that conforms to the schema we've created. See the Transact documentation for more details.
;; adding data@(fdb/transact conn ledger [{:_id :book :book/title "Watership Down" :book/tags [:rabbits :fiction] :book/authors [{:_id :author :name "Richard Adams"}]} {:_id :book :book/title "The Joy of Clojure" :book/tags [:programming :non-fiction] :book/authors [{:_id :author :name "Michael Fogus"} {:_id :author :name "Chris Houser"}]} {:_id :book :book/title "Cryptonomicon" :book/tags [:fiction :sci-fi] :book/authors [{:_id :author :name "Neal Stephenson"}]}])
@(fdb/transact conn ledger [{:_id [:book/title "Cryptonomicon"] :book/notes "I rly liked it."}])
;; updating a single-cardinality predicate@(fdb/transact conn ledger [{:_id [:book/title "Cryptonomicon"] :book/notes "I really liked it."}])
;; updating a multi-cardinality predicate@(fdb/transact conn ledger [{:_id [:book/title "The Joy of Clojure"] :book/title "The Joy of Clojure" :book/tags [:favorite]}]) ; adding the :favorite tag
;; retracting a predicate@(fdb/transact conn ledger [{:_id [:book/title "Cryptonomicon"] :book/notes nil}])
;; retracting multi-cardinality member@(fdb/transact conn ledger [{:_id [:book/title "The Joy of Clojure"] :_action :delete :book/tags [:favorite]}]) ; only removing :favorite tag
;; retracting a whole subject@(fdb/transact conn ledger [{:_id [:book/title "Watership Down"] :_action :delete}])
Querying#
Analytical queries#
The syntax for these queries is similar to datalog and eql. These don't support keywords for matching on flake values in the :where clause.
The query function takes a db value to execute a query against, as well as a query map. See the docs for Analytical queries and Basic queries for more details.
;; store the current immutable database value. See API docs for getting a prior version of a db, applying permissions to a db, and other options.(def db (fdb/db conn ledger))
;; all books@(fdb/query (fdb/db conn ledger) {:select {"?book" [:*, {:book/authors [:*]}]} :where [["?book" "book/title" nil]]})
;; all non-fiction books@(fdb/query (fdb/db conn ledger) {:select "?title" :where [["?book" "book/title" "?title"] ["?book" "book/tags" "non-fiction"]]})
History queries#
History queries can show you the raw history of a subject. Use :pretty-print to get back maps of predicate names to object values instead of raw flake data.
;; see the history of the "Cryptonomicon" book.@(fdb/history-query (fdb/db conn ledger) {:history ["book/title" "Cryptonomicon"] :pretty-print true})Block queries#
Block queries return all of the raw flake data stored in a block. Use :pretty-print to get back maps of predicate names to object values instead of raw flake data.
;; see all the flakes from block 3@(fdb/block_query-async conn ledger {:block 3 :pretty-print true})Other query languages#
In addition to the FlureeQL syntax used above, Fluree also supports queries in other query languages: SQL, SPARQL, GraphQL. These can be used from Clojure by supplying a database value and a query string, or, in the case of GraphQL, a query map.
@(fdb/sql (fdb/db conn ledger) "select * from book")
@(fdb/sparql (fdb/db conn ledger) "SELECT ?title WHERE { ?book fd:book/title ?title; fd:book/tags \"sci-fi\".}")
@(fdb/graphql conn ledger {:query "{graph { book { _id title}}}"} )
Async API#
All of the interactions with the Fluree ledger server are performed asynchronously, returning a promise. If you prefer to work with core.async channels instead of promises, there are -async variants of all the functions mentioned here that will return a core.async channel which will receive the result when the operation has finished.
(require '[clojure.core.async :as async])
(async/<!! (fdb/query-async (fdb/db conn ledger) {:select ["*"] :from "book"}))