Skip to content
This repository has been archived by the owner on Apr 20, 2018. It is now read-only.

Home

Jump to bottom
Moe Aboulkheir edited this page Aug 6, 2015 · 7 revisions

Most of the functions in hildebrand.core correspond directly to their Dynamo counterparts (and are identically named) though the representations used for parameters differ significantly from the Dynamo API. The signature of all of the fundamental Dynamo operations in Hildebrand is as follows:

(operation-name! creds top-level-arg ... &
  [op-args {:keys [chan close?] :or {close? true} :as req-args}])
  • creds, as per Eulalie, is a map describing either root account credentials, or credentials identifying an IAM/instance-specific role. A more in-depth explanation of the options is available on the eulalie.creds page of the Eulalie wiki. In the simplest case (default region, no IAM role, etc.) creds will contain values for :access-key & :secret-key.
  • Each function then accepts zero or more operation-specific arguments (e.g. table name, key specification, etc.)
  • op-args is an optional map of Dynamo operation-specific arguments which haven't been elevated into positional arguments.
  • chan and close? are the only appropriate values for req-args

If using the library with Clojure, blocking/double-bang versions of each hildebrand.core function are available, e.g. update-item!!, etc.

Channeled Functions

All of the functions in hildebrand.core and hildebrand.streams return a channel which will contain at most one value.

Where core.async can be leveraged more fruitfully, alternative implementations exist in hildebrand.channeled and hildebrand.streams.channeled. There are also utilities which would be awkward to express without channels, e.g. batching-puts, etc.

Types

Types are only specified when creating tables or indexes - the rest of the time they're inferred from item values.

Hildebrand uses the type names :string, :number, :list, :binary, :number-set, :string-set, :binary-set, :map, :null and :boolean, rather than Dynamo's abbreviations.

Numbers

Dynamo is unable to represent numbers with more than 38 digits of precision (unable to represent them as numbers. Strings and byte arrays are available). An error will be thrown client-side if an attempt is made to insert an unrepresentable number.

In Clojure, all numbers retrieved from Dynamo will be typed as either BigInteger or BigDecimal, and can be inserted as any common numeric type (Long, Double, Integer, Float, BigInteger, BigDecimal).

In Node/Clojurescript, bignumber.js is used for wrapping numbers pulled out of Dynamo. To adjust for the awkwardness of comparing these with their input values, Javascript Number instances are used for integer values having <= 15 digits of precision. I'm open-minded about other approaches.

Keywords

In most places where things are being named (tables, attributes, indexes, etc.) keywords may be used in place of strings, and will be retrieved as keywords when the loaded from Dynamo.

Map keys (i.e. within attributes of type :map), and members of :string-set attributes will be keywordized when retrieved.

Binary

In Clojure, byte arrays will be mapped to the :binary type, and sets of byte arrays to the :binary-set type. On Node, Buffer instances are used for representing binary data.

Errors

All of the basic functions in hildebrand.core return a channel containing no values, or a single value. If present, the value will be of some collection type, or an ExceptionInfo instance, wrapped around a map with :type and :message keys.

The :type values associated with errors are keywords obtained directly from the Dynamo API, complete with the -exception or -error suffix. The two abbreviations employed are:

  • :resource-not-found (e.g. describing non-existent table)
  • :conditional-failed (precondition failure prevented a conditional write from succeeding)

There is also a Hildebrand-defined error type:

  • :unprocessed-items

Which will be thrown if a batch operation doesn't entirely complete. The error map will contain :unprocessed and :results keys.

The paged functions in hildebrand.channeled (query!, scan!) communicate by placing item maps on their output channels. Errors, when they occur, will be placed on the output channel alongside the successful results, in the same format as above.

The batching output functions in hildebrand.channeled (batching-puts, batching-deletes) return distinct error channels, as there is no output when writes are successful.

Clone this wiki locally