Introduction
This is the second part of the Crux tutorial.
The Earth installment looked at setting up a simple Crux standalone node and a very simple put
transaction.
We shall assume you have a Crux standalone node. If not, you can find all you need to know on Earth. Click on a destination above to take you there.
If you are following on your own machine, it is best you follow along in sequence as this tutorial depends on the Earth installment.
To go to different destination, click the location above.
Arrival on Pluto
As you enter the Plutonian atmosphere, a message pops up on your communication panel:
Welcome to the dwarf planet Pluto. You are entering privately governed space. If you do not have the correct papers, entry will be denied. We hope you enjoy your stay.
Have a nice day.
The government of Pluto is asking to see your flight manifest.
Pluto Space Port
As you circle the dwarf planet to land, you have a quick read of your Crux manual.
You know you will be using the put
operation a lot for this assignment and although you used the operation to add your manifest before you left, you think it is a good idea to brush up on your knowledge.
Currently there are only four transaction operations in Crux:
put
,delete
,cas
andevict
.
Transaction Description
put
Writes a version of a document
delete
Deletes a version of a document
cas
Writes new version of a document if the old version is as expected.
evict
Removes a document entirely
Put:
The
put
operation is used to write versions of a document (doc).Each document must be in Extensible Data Notation (edn) and must contain a unique
:crux.db/id
value. However, beyond those two requirements you have the flexibility to add whatever you like to your documents because Crux is schemaless.Along with the document (doc),
put
has two optional additional arguments:
start valid-time
The time at which the entry will be valid from.
end valid-time
The time at which the entry will be valid until.
This means that you can query back through Crux, you can use
valid-time
arguments to see the state of Crux at a different time.If no
valid-time
is provided, startvalid-time
defaults to the transaction time and the document is valid either eternally or until the document is updated by a future transaction with the same eid.
- Time in Crux is denoted
#inst "yyyy-MM-ddThh:mm:ss"
. For example, 9:30 pm on January 2nd 1999 would be written:
#inst "1999-01-02T21:30:00"
.
- A complete
put
transaction has the form:
[:crux.tx/put doc valid-time-start valid-time-end]
Read More
Assignment
You land on the surface of the dwarf planet. As you do, the job ticket for this assignment is unlocked.
Task |
|
Company |
|
Contact |
|
Submitted |
|
Additional information |
|
Attachments |
You make your way over to the mines on the next shuttle. On your way you decide to get a head start and put the commodities into Crux.
(crux/submit-tx crux
[[:crux.tx/put
{:crux.db/id :commodity/Pu
:common-name "Plutonium"
:type :element/metal
:density 19.816
:radioactive true}]
[:crux.tx/put
{:crux.db/id :commodity/N
:common-name "Nitrogen"
:type :element/gas
:density 1.2506
:radioactive false}]
[:crux.tx/put
{:crux.db/id :commodity/CH4
:common-name "Methane"
:type :molecule/gas
:density 0.717
:radioactive false}]])
Since it takes six hours for each transaction to reach your Crux node on Earth from here, it is a good idea to batch up all the commodities in a single transaction.
=>#:crux.tx{:tx-id 1598856704299009, :tx-time #inst "2115-02-20T13:38:20.292-00:00"}
Stock take
You arrive at the mine and are met by the CEO, Reginald Glogofloon, a 150 year old Plutonian.
Hello, I’m glad you’re here.
I would like you to fill in our last week’s worth of data on our commodities. We need to be able to look back at a given day and see what our stocks were for auditing purposes.
The stock for each day must be submitted at 6pm Earth time (UTC) for your banks records.
Are you able to do that for me?
Choose your path
"Yes I’ll give it a go." | "I’m not sure how to even begin." |
---|

You remember that with Crux you have the option of adding a valid-time
.
This comes in useful now as you enter the weeks worth of stock takes for Plutonium.
(crux/submit-tx crux
[[:crux.tx/put
{:crux.db/id :stock/Pu
:commod :commodity/Pu
:weight-ton 21 }
#inst "2115-02-13T18"] ;; valid-time
[:crux.tx/put
{:crux.db/id :stock/Pu
:commod :commodity/Pu
:weight-ton 23 }
#inst "2115-02-14T18"]
[:crux.tx/put
{:crux.db/id :stock/Pu
:commod :commodity/Pu
:weight-ton 22.2 }
#inst "2115-02-15T18"]
[:crux.tx/put
{:crux.db/id :stock/Pu
:commod :commodity/Pu
:weight-ton 24 }
#inst "2115-02-18T18"]
[:crux.tx/put
{:crux.db/id :stock/Pu
:commod :commodity/Pu
:weight-ton 24.9 }
#inst "2115-02-19T18"]])
You notice that the amount of Nitrogen and Methane has not changed in the last week which saves you some time:
(crux/submit-tx crux
[[:crux.tx/put
{:crux.db/id :stock/N
:commod :commodity/N
:weight-ton 3 }
#inst "2115-02-13T18" ;; start valid-time
#inst "2115-02-19T18"] ;; end valid-time
[:crux.tx/put
{:crux.db/id :stock/CH4
:commod :commodity/CH4
:weight-ton 92 }
#inst "2115-02-15T18"
#inst "2115-02-19T18"]])
The CEO is impressed with your speed, but a little skeptical that you have done it properly.
You gain their confidence by showing them the entries for Plutonium on two different days:
(crux/entity (crux/db crux #inst "2115-02-14") :stock/Pu)
=> {:crux.db/id :stock/Pu, :commod :commodity/Pu, :weight-ton 21}
(crux/entity (crux/db crux #inst "2115-02-18") :stock/Pu)
=> {:crux.db/id :stock/Pu, :commod :commodity/Pu, :weight-ton 22.2}
Easy ingest
As a parting gift to them you create an easy ingest function so that if they needed to add more commodities to their stock list they could do it fast.
(defn easy-ingest
"Uses Crux put transaction to add a vector of documents to a specified
node"
[node docs]
(crux/submit-tx node
(vec (for [doc docs]
[:crux.tx/put doc]))))
Tombaugh Resources Ltd. are happy that this will be simple enough to use. They thank you for the extra help and you head back to your ship.
Space Port
You are back at your ship and check your communications panel. There is a new assignment waiting for you:
Congratulations on completing your first assignment.
We would like you to go to Mercury, the hub of the trade world. Their main trade center has a new IT department and want you to show them how to query Crux.
It’s a long flight so you refuel, and update your manifest.
You have been awarded a new badge.
Since this is the only thing to update in your manifest, you use the Clojure function assoc
to save time.
(crux/submit-tx
crux
[[:crux.tx/put
(assoc manifest :badges ["SETUP" "PUT"])]])
You check this has worked because it’s your first time doing it this way.
(crux/entity (crux/db crux) :manifest)
=> {:crux.db/id :manifest,
:pilot-name "Johanna",
:id/rocket "SB002-sol",
:id/employee "22910x2",
:badges ["SETUP" "PUT"],
:cargo ["stereo" "gold fish" "slippers" "secret note"]}
You enter countdown for lift off to Mercury. See you soon.
Click on Mercury to take you to your next assignment.