hildebrand.core

Below, functions corresponding to single Dynamo operations are linked to the appropriate Dynamo API documentation.

create-table!

(create-table! creds table-spec & [{:keys [chan close?]}])

• Keys are expressed as one or two element vectors - [hash-key] or [hash-key range-key]
• Index projection options are represented as variants - [tag] or [tag argument]
• [:all]
• [:include [attr1 attr2 ...]]
• [:keys-only]
• The returned channel will contain a single map representing the created table.
• The :status response key can have values :creating, :updating, :deleting or :active.

Examples

(def create-local-index
  {:name :game-by-user-id-timestamp
   :keys [:user-id :timestamp]
   :project [:include [:data]]})

(def create-global-index
  {:name :game-by-title-timestamp
   :keys [:game-title :timestamp]
   :project [:keys-only]
   :throughput {:read 1 :write 1}})

(create-table!
 creds
 {:table :games
  :throughput {:read 1 :write 1}
  :attrs {:user-id :string :game-title :string :timestamp :number}
  :keys  [:user-id :game-title]
  :indexes
  {:local
   [create-local-index]
   :global
   [create-global-index]}})

;; =>
{:table :games,
 :created 1437308360985,
 :throughput {:read 1, :write 1, :decreases 0},
 :size 0,
 :keys [:user-id :game-title],
 :status :creating,
 :attrs {:game-title :string, :timestamp :number, :user-id :string},
 :indexes
 {:local
  ({:index-arn ...,
    :name :game-by-user-id-timestamp,
    :size 0,
    :count 0,
    :keys [:user-id :timestamp],
    :project [:include [:data]]}),
  :global
  ({:index-arn ...,
    :name :game-by-title-timestamp,
    :size 0,
    :status :creating,
    :count 0,
    :keys [:game-title :timestamp],
    :project [:keys-only],
    :throughput {:read 1, :write 1, :decreases 0}})},
 :items 0,
 :table-arn ...}

list-tables!

(list-tables! creds & [{:keys [limit start-table]} {:keys [chan close?]}])

• See hildebrand.channeled/list-tables! for a more convenient implementation

Examples

(list-tables! creds {:limit 5 :start-table :games})
;; => [:games :games__test :users :users__test :machines]
;; => metadata = {:start-table :machines}

describe-table!

(describe-table! creds table-name & [_ {:keys [chan close?]}])

• Returned channel contains a map of identical structure to the create-table! response

delete-table!

(delete-table! creds table-name & [{:keys [chan close?]}])

• Returned channel contains a map, describing the table at deletion time.

ensure-table!

(ensure-table! creds table-spec)

• If a table with the given name (i.e. the value of :table within table-spec) doesn't exist, a create-table! will be issued.
• The returned channel will close only when the status of the table is :active - i.e. unlike create-table!, the table will be ready for use.

update-table!

(update-table! creds table-name
  {:keys [indexes stream-specification attrs throughput]
   :as update-spec}
  & [{:keys [chan close?]}])

• Returned channel contains a map describing the updated table

Example update-specs

{:stream-specification {:stream-enabled true
                        :stream-view-type :new-and-old-images}}

{:indexes [[:delete {:name :my-global-index}]
           [:create {:name :better-global-index
                     ...}]
           [:update {:name :some-other-index ...}]]}

get-item!

(get-item!
  creds
  table-name
  {hash-key-attr ... [range-key-attr ...]}
  & [{:keys [consistent project]}
     {:keys [chan close?]}])

• See Common Options for :consistent & :project
• The resulting channel will hold either a single map, or nothing

Examples

(put-item!
 creds :hildebrand-test-table
 {:name "Tony Wilson" :occupation "Host"})
...
(get-item!
 creds :hildebrand-test-table
 {:name "Tony Wilson"}
 {:project [:occupation]}) ;; -> {:occupation "Host"}

put-item!

(put-item!
  creds
  table-name
  {attr ...}
  & [{:keys [when return]}
     {:keys [chan close?]}])

• Valid values for :return are :none and :all-old. Default is :none.
• See Conditional Operations.

Examples

(put-item!
 creds
 :curries
 {:name "Jalfrezi"
  :region "Pakistan"
  :spiciness 4
  :allergens #{"clove" "cinnamon"}
  :ingredients {"onion" 2 "tomato" 3 "chili" 2}})

update-item!

(update-item!
 creds
 :hildebrand-test-table
 {hash-key-attr ... [range-key-attr ...]}
 update-map
 & [{:keys [when return]}
    {:keys [chan close?]}])

• For this operation, valid :return values are :all-old, :all-new, :updated-old, :updated-new and :none.
• The returned channel will contain no value by default. If :return is other-than :none, the channel will contain a single map value.
• See Conditional Operations.

Update Map

update-map is a nested map describing locations within the item, and specifying operations we'd like to perform on them. Supported operations:

• [:inc n]
• [:dec n]
• [:init value]
• [:set value]
• [:remove]
• [:concat value]

As Dynamo has different operators for adding to sets and lists, the single operation :concat expands into either :add or :set depending on whether its value is a set, or some other sequence type. :init expands into a :set which will only be performed if the attribute doesn't already exist.

The #hildebrand/path tag, or :hildebrand/path metadata can be applied to the values of many of the operators above, indicating that the value is to be interpreted as a path on the same item, rather than a literal vector.

{:top-level [:init []]}
;; Integer keys are used to refer to list elements
{:top-level {0 [:set 5]}}
{:top-level [:concat [6 7 8]]}
{:top-level {1 [:remove]}}

;; Set second element of list to value of "name" attribute
{:top-level {1 [:set #hildebrand/path [:name]]}}

Examples

(update-item!
 creds
 :curries
 {:name "Jalfrezi"}
 {:ingredients {:onion [:inc 4] :tomato [:remove]}
  :allergens   [:concat #{"mustard" "nuts"}]
  :delicious   [:init true]}
 {:when [:and
          [:< [:ingredients :onion] [:ingredients :tomato]]
          [:contains [:allergens] "clove"]]})

delete-item!

(delete-item!
 creds
 table-name
 {hash-key-attr ... [range-key-attr ...]}
 & [{:keys [when return]}
    {:keys [chan close?]}])

• Valid values for :return are :none and :all-old
• Returned channel will be empty, unless :return is set to :all-old, in which case it will contain a single map.
• See Conditional Operations.

query-count!

(query-count! creds table-name where
  & [query-opts {:keys [chan close?]}])

• Returned channel contains a single number representing the post-filter count of the query.
• See hildebrand.channeled/query! for detail on where, and other query options.

Examples

(query-count!
 creds :games
 {:user-id [:= "moea"]}
 {:filter [:between [:score] 10 30]})
;; => 2

scan-count!

(scan-count! creds table-name & [scan-opts {:keys [chan close?]}])

• Returned channel contains a single number representing the post-filter count of the scan.
• See hildebrand.channeled/scan! for more detail on scan options.

batch-get-item!

(batch-get-item! creds table->specs & [opts {:keys [chan close?]}])

• Returned channel contains a map of table names to sequences of retrieved items.
• If the batch isn't entirely processed, the channel will contain an ExceptionInfo instance, with a :type of :unprocessed-items. The :unprocessed key of the error map will be a sequence of the unprocessed items - the :result key will hold the successfully retrieved items.

Examples

(batch-get-item!
 creds
 {:hildebrand-test-table
  {:project [:age]
   :consistent true
   :keys [{:name "John"} {:name "Paul"}]}})

batch-write-item!

(batch-write-item! creds {:keys [put delete] :as write-spec}
  & [_ {:keys [chan close?]}])

• On success, the returned channel will contain an empty map. Failure, or partial success, will result in an :unprocesed-items error.
• See hildebrand.channeled/batching-puts & hildebrand.channeled/batching-deletes for a different approach to batch writes.

Examples

(batch-write-item!
 creds
 {:put {:hildebrand-test-table
        [{:name "John"}
         {:name "Paul"}]}
  :delete {:hildebrand-test-table
           [{:name "George"}]}})