Packages

package root

Documentation/API for the Molecule library - a meta DSL for the Datomic database.

Manual | scalamolecule.org | Github | Forum

Definition Classes: root

package molecule

Molecule library - a Scala meta-DSL for the Datomic database.

See api package for various api imports to start using Molecule.

Sub-packages

action		Actions on molecules and entities.
api		Molecule import interfaces of various arities.
ast		Internal Molecule ASTs.
boilerplate		Internal interfaces for auto-generated DSL boilerplate code.
composition		Builder methods to compose molecules.
exceptions		Exceptions thrown by Molecule.
expression		Attribute expressions and operations.
facade		Molecule facades to Datomic.
factory		Implicit macro methods `m` to instantiate molecules from custom DSL molecule constructs.
generic		Interfaces to generic information about datoms and Datomic database.
input		Input molecules awaiting input.
macro		Internal macros generating molecule code from custom DSL molecule constructs.
ops		Internal operational helpers for transforming DSL to molecule.
schema		Schema definition DSL.
transform		Internal transformers from DSL to Model/Query/Transaction.
util		Internal Java database functions for Datomic.

Definition Classes: root

package action

Various actions and operations on molecules and entities.

Definition Classes: molecule

package exception

package get

Package with various synchronous getter methods to retrieve data from Datomic with molecules.

For the Datomic Peer model, Datomic returns data synchronously. The Peer lives in application memory and caches data aggressively to save roundtrips to disk or memcached. Query results that can fit in memory will therefore have near-zero latency and return extremely fast.

Molecule has not yet addressed the Client api although the query engine would be the same as for the current Peer version.

Molecule has 5 groups of getters each returning data in various formats:

GetList - default getter returning Lists of tuples. Convenient typed data, suitable for smaller data sets
GetArray - fastest retrieved typed data set. Can be traversed with a fast while loop
GetIterable - for lazily traversing row by row
GetRaw - fastest retrieved raw un-typed data from Datomic
GetJson - data formatted as Json string

Getters in each of the 5 groups come with 5 time-dependent variations:

get [current data]
getAsOf
getSince
getWith
getHistory

Each time variation has various overloads taking different parameters (see each group for more info).

CompositeInserts

Entity

EntityOps

Molecule

OptionalMapOps

ShowDebug

package api

Public interfaces to be imported to use Molecule.

To make the Molecule macro materializations as fast as possible we try to import as few macro implicits as possible. If your application code build molecules with at the most 10 attributes, then you can do the following import to start using Molecule:

import molecule.api.out10._

out means "output molecule" , and 10 the maximum arity or number of attributes of your molecules.

If you use input molecules awaiting an input then you can add inX where X is how many inputs (1, 2 or 3) you will use, for instance:

import molecule.api.in2_out10._

This way we keep the implicit macro def lookups to a minimum and compilation speed as fast as possible.

Arities can be changed anytime you like. But not to a lower arity than that of the molecules you use in scope of the import.

Definition Classes: molecule

package ast

Internal Molecule ASTs.

Definition Classes: molecule

package boilerplate

Internal interfaces for auto-generated DSL boilerplate code.

Internal interfaces for auto-generated DSL boilerplate code.

Interfaces to the generated schema-defined DSL boilerplate code that the sbt-plugin generates when doing a sbt-compile. Molecule macros can then type-safely deduct the type structure of composed molecules.

Definition Classes: molecule

package composition

Methods to build transaction, composite and nested molecules.

Definition Classes: molecule

package exceptions

Exceptions thrown by Molecule.

Definition Classes: molecule

package expression

Attribute expressions and operations.

Attribute expressions and operations.

Refine attribute matches with various attribute expressions:

Person.age(42)                           // equality
Person.name.contains("John")             // fulltext search
Person.age.!=(42)                        // negation (or `not`)
Person.age.<(42)                         // comparison (< > <= >=)
Person.name("John" or "Jonas")           // OR-logic
Person.age()                             // apply empty value to retract value(s) in updates
Person.hobbies.assert("golf")               // add value(s) to card-many attributes
Person.hobbies.retract("golf")            // retract value(s) of card-many attributes
Person.hobbies.replace("golf", "diving") // replace value(s) of card-many attributes
Person.tags.k("en")                      // match values of map attributes by key
Person.age(Nil)                          // match non-asserted datoms (null)
Person.name(?)                           // initiate input molecules awaiting input at runtime
Person.name(unify)                       // Unify attributes in self-joins

Apply aggregate keywords to aggregate attribute value(s):

// Aggregates on any attribute type
Person.age(count).get.head         === 3   // count of asserted `age` attribute values
Person.age(countDistinct).get.head === 3   // count of asserted distinct `age` attribute values
Person.age(max).get.head           === 38  // maximum `age` value (using `compare`)
Person.age(min).get.head           === 5   // maximum `age` value (using `compare`)
Person.age(rand).get.head          === 25  // single random `age` value
Person.age(sample).get.head        === 27  // single sample `age` value (when single value, same as random)

// Aggregates on any attribute type, returning multiple values
Person.age(distinct).get.head  === Vector(5, 7, 38)  // distinct `age` values
Person.age(max(2)).get.head    === Vector(38, 7)     // 2 maximum `age` values
Person.age(min(2)).get.head    === Vector(5, 7)      // 2 minimum `age` values
Person.age(rand(2)).get.head   === Stream(5, ?)      // 2 random `age` values (values can re-occur)
Person.age(sample(2)).get.head === Vector(7, 38)     // 2 sample `age` values

// Aggregates on number attributes
Person.age(sum).get.head      === 50               // sum of all `age` numbers
Person.age(avg).get.head      === 16.66666667      // average of all `age` numbers
Person.age(median).get.head   === 7                // median of all `age` numbers
Person.age(stddev).get.head   === 15.107025591499  // standard deviation of all `age` numbers
Person.age(variance).get.head === 228.2222222222   // variance of all `age` numbers

Definition Classes: molecule
See also: Manual: expressions | aggregates | input molecules
Tests: expressions

package facade

Molecule facades to Datomic.

Molecule facades to Datomic.

Facades are not trying to cover all Datomic methods but rather only interfaces relevant to Molecule.

Definition Classes: molecule

package factory

Factory methods m to instantiate molecules from custom DSL molecule constructs.

Definition Classes: molecule

package generic

Interfaces to meta information about datoms and Datomic database.

Definition Classes: molecule

package input

Input molecules awaiting input.

Input molecules awaiting input.

Input molecules are molecules that awaits one or more inputs at runtime. When input value is applied, the input molecule is resolved and a standard molecule is returned that we can then call actions on.

Input molecule queries are cached by Datomic. So there is a runtime performance gain in using input molecules. Furthermore, input molecules are a good fit for re-use for queries where only a few parameters change.

Input molecules can await 1, 2 or 3 inputs and are constructed by applying the ? marker to attributes. If one marker is applied, we get a InputMolecule_1, 2 inputs creates an InputMolecule_2 and 3 an InputMolecule_3.

The three input molecule interfaces come in arity-versions corresponding to the number of non-?-marked attributes in the input molecule. Let's see a simple example:

// Sample data
Person.name.age insert List(("Ben", 42), ("Liz", 34))

// Input molecule created at compile time. Awaits a name of type String
val ageOfPersons: InputMolecule_1.InputMolecule_1_01[String, Int] = m(Person.name_(?).age)

// Resolved molecule. "Ben" input is matched against name attribute
val ageOfPersonsNamedBen: Molecule.Molecule01[Int] = ageOfPersons.apply("Ben")

// Calling action on resolved molecule.
// (Only age is returned since name was marked as tacit with the underscore notation)
ageOfPersonsNamedBen.get === List(42)

// Or we can re-use the input molecule straight away
ageOfPersons("Liz").get === List(34)

Definition Classes: molecule

package macros

Internal macros generating molecule code from custom DSL molecule constructs.

Definition Classes: molecule

package ops

Internal operational helpers for transforming DSL to molecules.

Definition Classes: molecule

package schema

Schema definition DSL and API.

Definition Classes: molecule

package transform

Internal transformers from DSL to Model/Query/Transaction/Datomic.

Internal transformers from DSL to Model/Query/Transaction/Datomic.

Molecule transforms custom boilerplate DSL constructs to Datomic queries in 3 steps:

Custom DSL molecule --> Model --> Query --> Datomic query string

Definition Classes: molecule
See also: http://www.scalamolecule.org/dev/transformation/

package util

Internal Java database functions for Datomic.

Definition Classes: molecule

molecule

action

package action

Various actions and operations on molecules and entities.

Source: package.scala

Linear Supertypes

AnyRef, Any

Content Hierarchy

Ordering

Alphabetic
By Inheritance

Inherited

action
AnyRef
Any

Hide All
Show All

Visibility

Public
All

Type Members

trait CompositeInserts extends Helpers

Insert methods to create composite entities containing multiple sub-molecules/tuples.

Insert composite data

insert(
  // 2 sub-molecules
  Article.name.author, Tag.name.weight
)(
  // Rows of tuples, each with 2 sub-tuples of data matching sub-molecules
  List(
    (("Battle of Waterloo", "Ben Bridge"), ("serious", 5)),
    (("Best jokes ever", "John Cleese"), ("fun", 3))
  )
)(
  // Optional transaction meta data molecule saved with the tx entity created
  MetaData.submitter("Brenda Johnson").usecase("AddReviews")
)

Query inserted composite data

We can then query the composite data:

// Important articles submitted by Brenda Johnson
// In queries we tie composite sub-molecules together with `~`
m(Article.name.author ~ Tag.weight.>=(4).Tx(MetaData.submitter_("Brenda Johnson"))).get === List(
  (("Battle of Waterloo", "Ben Bridge"), 5)
)

Debug a composite insert

Without affecting the database, a composite insert can be debugged with debugInsert to see the produced output:

debugInsert(
  Article.name.author, Tag.name.weight
)(
  List(
    (("Battle of Waterloo", "Ben Bridge"), ("serious", 5)),
    (("Best jokes ever", "John Cleese"), ("fun", 3))
  )
)(
  MetaData.submitter("Brenda Johnson").usecase("AddReviews")
)

outputs:

## 1 ## Composite arity-2 insert debug
========================================================================
1      Model(
  1      Atom(article,name,String,1,VarValue,None,List(),List())
  2      Atom(article,author,String,1,VarValue,None,List(),List())
  3      Atom(tag,name,String,1,VarValue,None,List(),List())
  4      Atom(tag,weight,Long,1,VarValue,None,List(),List())
  5      TxMetaData(
    1      Atom(metaData,submitter,String,1,Eq(List(Brenda Johnson)),None,List(),List())
    2      Atom(metaData,usecase,String,1,Eq(List(AddReviews)),None,List(),List())))
------------------------------------------------
2      List(
  1      :db/add    'tempId    :article/name          'arg                                     Card(1)
  2      :db/add    'e         :article/author        'arg                                     Card(1)
  3      :db/add    'e         :tag/name              'arg                                     Card(1)
  4      :db/add    'e         :tag/weight            'arg                                     Card(1)
  5      :db/add    'tx        :metaData/submitter    Values(Eq(List(Brenda Johnson)),None)    Card(1)
  6      :db/add    'tx        :metaData/usecase      Values(Eq(List(AddReviews)),None)        Card(1))
------------------------------------------------
3      List(
  1      List(
    1      :db/add    #db/id[:db.part/user -1000097]    :article/name          Battle of Waterloo    Card(1)
    2      :db/add    #db/id[:db.part/user -1000097]    :article/author        Ben Bridge            Card(1)
    3      :db/add    #db/id[:db.part/user -1000097]    :tag/name              serious               Card(1)
    4      :db/add    #db/id[:db.part/user -1000097]    :tag/weight            5                     Card(1))
  2      List(
    1      :db/add    #db/id[:db.part/user -1000098]    :article/name          Best jokes ever       Card(1)
    2      :db/add    #db/id[:db.part/user -1000098]    :article/author        John Cleese           Card(1)
    3      :db/add    #db/id[:db.part/user -1000098]    :tag/name              fun                   Card(1)
    4      :db/add    #db/id[:db.part/user -1000098]    :tag/weight            3                     Card(1))
  3      List(
    1      :db/add    #db/id[:db.part/tx -1000100]      :metaData/submitter    Brenda Johnson        Card(1)
    2      :db/add    #db/id[:db.part/tx -1000100]      :metaData/usecase      AddReviews            Card(1)))
========================================================================

The two first sections are internal Molecule representations.

The third section shows the transactional data sent to Datomic (except the line indexing numbers in the left column) - in this case two rows of data and one row of transaction data.

See also: Manual: composite inserts | composites
Tests: composite inserts

class Entity extends AnyRef
Entity wrapper with actions on entity.
Entity wrapper with actions on entity.

See also
Manual | Tests: entity api
trait EntityOps extends AnyRef
Operations on multiple entities.

trait Molecule[Tpl] extends MoleculeBase with CastHelpers[Tpl] with JsonBuilder with GetArray[Tpl] with GetIterable[Tpl] with GetList[Tpl] with GetRaw with GetJson with ShowDebug[Tpl]

Core molecule interface defining actions that can be called on molecules.

Groups of interfaces:

get		Get molecule data.
getAsOf		Get molecule data asOf point in time.
getSince		Get molecule data since point in time.
getWith		Get molecule data with given data set.
getHistory		Get molecule data from history of database.
save		Save molecule with applied data.
insert		Insert multiple rows of data matching molecule.
update		Update molecule with applied data.
tx		Molecule transaction data (input to `getWith`).
debug get		Debug calling get method on molecule.
debug action		Debug calling save/insert/update method on molecule.

Tpl: Type of molecule (tuple of its attribute types)

See also: For retract ("delete") methods, see EntityOps and Entity.
Manual: get, time, asOf/since, history, with, getJson, debug/test, save, insert, update, retract
Tests: get, asOf, since, history, with, test asOf, test since, test with, getJson, save, insert, retract,
update, update map, update ref, update multiple attributes, update multiple entities

trait OptionalMapOps extends AnyRef
Container of implicit for optional Map operations.
Container of implicit for optional Map operations.

See also
Tests
trait ShowDebug[Tpl] extends AnyRef
Debug methods
Debug methods
Call a debug method on a molecule to see the internal transformations and produced transaction statements or sample data.

Packages

Sub-packages

action

package action

Type Members

Insert composite data

Query inserted composite data

Debug a composite insert

Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

Packages

Sub-packages

action 

package action

Type Members

Insert composite data

Query inserted composite data

Debug a composite insert

Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

action