Molecule0.25.1 < Back

Packages

package root
Documentation/API for the Molecule library - a meta DSL for the Datomic database.
scalamolecule.org | Github | Forum

Definition Classes
root
package molecule
Molecule library - a Scala meta-DSL for the Datomic database.
Molecule library - a Scala meta-DSL for the Datomic database.

Definition Classes
root
package core

Definition Classes
molecule
package api

Definition Classes
core
package exception
package getAsyncObj
Asynchronous getter methods to retrieve data as objects.
Asynchronous getter methods to retrieve data as objects.
For convenience, all synchronous getter methods from the get package are here wrapped in Futures.
The Datomic On-Prem(ises) server model provides a Peer that returns data synchronously. The Peer which lives in application memory caches data aggressively and for data fitting in memory, latency can be extremely low and queries return very fast. And even when access to disk is needed, clever branching is used. Memcached is also an option.
The Datomic Cloud model data returns data asynchronously. If Datomic creates a Java API for the Cloud model, Molecule could relatively easy adapt to this model too. In the meanwhile, Future-wrapped methods in this package can be used.
Molecule has 4 groups of asynchronous getters for objects, each returning Futures of data in various formats:
- GetAsyncObjArray - fastest retrieved typed data set. Can be traversed with a fast while loop
- GetAsyncObjIterable - for lazily traversing row by row
- GetAsyncObjList - default getter returning Lists of objects. Convenient typed data, suitable for smaller data sets
- GetAsyncRaw - fastest retrieved raw un-typed data from Datomic
Getters in each of the 4 groups come with 5 time-dependent variations:
- getAsync [current data]
- getAsyncAsOf
- getAsyncSince
- getAsyncWith
- getAsyncHistory
Each time variation has various overloads taking different parameters (see each group for more info).
See also
equivalent synchronous getters in the getTpl package.
package getAsyncTpl
Asynchronous getter methods to retrieve tuples of data.
Asynchronous getter methods to retrieve tuples of data.
For convenience, all synchronous getter methods from the get package are here wrapped in Futures.
The Datomic On-Prem(ises) server model provides a Peer that returns data synchronously. The Peer which lives in application memory caches data aggressively and for data fitting in memory, latency can be extremely low and queries return very fast. And even when access to disk is needed, clever branching is used. Memcached is also an option.
The Datomic Cloud model data returns data asynchronously. If Datomic creates a Java API for the Cloud model, Molecule could relatively easy adapt to this model too. In the meanwhile, Future-wrapped methods in this package can be used.
Molecule has 4 groups of asynchronous getters for tuples, each returning Futures of data in various formats:
- GetAsyncTplArray - fastest retrieved typed data set. Can be traversed with a fast while loop
- GetAsyncTplIterable - for lazily traversing row by row
- GetAsyncTplList - default getter returning Lists of tuples. Convenient typed data, suitable for smaller data sets
- GetAsyncRaw - fastest retrieved raw un-typed data from Datomic
Getters in each of the 4 groups come with 5 time-dependent variations:
- getAsync [current data]
- getAsyncAsOf
- getAsyncSince
- getAsyncWith
- getAsyncHistory
Each time variation has various overloads taking different parameters (see each group for more info).
See also
equivalent synchronous getters in the getTpl package.
package getObj
Synchronous getter methods to retrieve data as objects.
Synchronous getter methods to retrieve data as objects.
The Datomic On-Prem(ises) server model provides a Peer that returns data synchronously. The Peer which lives in application memory caches data aggressively and for data fitting in memory latency can be extremely low and queries return very fast. And even when access to disk is needed, clever branching is used. Memcached is also an option.
The Datomic Cloud model data returns data asynchronously. If Datomic creates a Java API for the Cloud model, Molecule could relatively easy adapt to this model too. In the meanwhile, Future-wrapped methods in this package can be used.
Molecule has 3 groups of synchronous object getters, each returning data in various formats:
- GetObjArray - fastest retrieved typed data set. Can be traversed with a fast while loop
- GetObjIterable - for lazily traversing row by row
- GetObjList - default getter returning Lists of objects. Convenient typed data, suitable for smaller data sets
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).
See also
equivalent asynchronous getters in the getAsyncTpl package.
package getTpl
Synchronous getter methods to retrieve data as tuples.
Synchronous getter methods to retrieve data as tuples.
The Datomic On-Prem(ises) server model provides a Peer that returns data synchronously. The Peer which lives in application memory caches data aggressively and for data fitting in memory latency can be extremely low and queries return very fast. And even when access to disk is needed, clever branching is used. Memcached is also an option.
Molecule has 4 groups of synchronous tuple getters, each returning data in various formats:
- GetTplArray - fastest retrieved typed data set. Can be traversed with a fast while loop
- GetTplIterable - for lazily traversing row by row
- GetTplList - default getter returning Lists of tuples. Convenient typed data, suitable for smaller data sets
- GetRaw - fastest retrieved raw un-typed data from Datomic
Getters in each of the 4 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).
See also
equivalent asynchronous getters in the getAsyncTpl package.
GetAsyncRaw
GetRaw
InputMolecule
Keywords
Molecule_0
Molecule_1
Molecule_2
Molecule_3
OptionalMapOps
TxBundles
TxFunctions
package ast
Internal Molecule ASTs.
Internal Molecule ASTs.

Definition Classes
core
package composition
Methods to build transaction, composite and nested molecules.
Methods to build transaction, composite and nested molecules.

Definition Classes
core
package data
Data model DSL and API.
Data model DSL and API.

Definition Classes
core
package dsl
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
core
package exceptions
Exceptions thrown by Molecule.
Exceptions thrown by Molecule.

Definition Classes
core

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: core

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

Definition Classes
core
package generic

Definition Classes
core
package macros

Definition Classes
core
package ops

Definition Classes
core
package transform

Definition Classes
core
package util
Internal database functions for Datomic.
Internal database functions for Datomic.

Definition Classes
core

molecule.core

api

package api

Content Hierarchy

Ordering

Alphabetic

Visibility

Public
All

Type Members

trait GetAsyncRaw extends AnyRef
Asynchronous data getter methods on molecules returning raw untyped Datomic data.
Asynchronous data getter methods on molecules returning raw untyped Datomic data.

Returns a Future with raw untyped java.util.Collection[java.util.List[Object]] directly from Datomic and is therefore the fastest (but untyped) way of retrieving data. Can be useful where typed data is not needed.
```
val rawDataFuture: Future[java.util.Colleciton[java.util.List[Object]] = Person.name.age.getAsyncRaw
for {
  rawData <- rawDataFuture
} yield {
  rawData.toString === """[["Ben" 42]["Liz" 37]]"""
}
```
Each asynchronous getter in this package simply wraps the result of its equivalent synchronous getter (in the get package) in a Future. getAsyncRawAsOf thus wraps the result of getRawAsOf in a Future and so on.
trait GetRaw extends JavaUtil
Data getter methods on molecules that return raw untyped Datomic data.
Data getter methods on molecules that return raw untyped Datomic data.

Returns raw untyped java.util.Collection[java.util.List[Object]] directly from Datomic and is therefore the fastest (but untyped) way of retrieving data. Can be useful where typed data is not needed.
trait InputMolecule extends Molecule
Shared interface of all input molecules.
Shared interface of all input molecules.

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 Molecule_1, 2 inputs creates an Molecule_2 and 3 an Molecule_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(
  ("Joe", 42),
  ("Liz", 34)
)

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

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

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

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

trait Molecule_0[Obj, Tpl] extends Molecule with CastHelpers[Obj, Tpl] with GetTplArray[Obj, Tpl] with GetTplIterable[Obj, Tpl] with GetTplList[Obj, Tpl] with GetRaw with GetObjArray[Obj, Tpl] with GetObjIterable[Obj, Tpl] with GetObjList[Obj, Tpl] with GetAsyncTplArray[Obj, Tpl] with GetAsyncTplIterable[Obj, Tpl] with GetAsyncTplList[Obj, Tpl] with GetAsyncObjArray[Obj, Tpl] with GetAsyncObjIterable[Obj, Tpl] with GetAsyncObjList[Obj, Tpl] with GetAsyncRaw with ShowInspect[Obj, Tpl]

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

Groups of interfaces:

get	getAsync	Get molecule data.
getAsOf	getAsyncAsOf	Get molecule data asOf point in time.
getSince	getAsyncSince	Get molecule data since point in time.
getWith	getAsyncWith	Get molecule data with given data set.
getHistory	getAsyncHistory	Get molecule data from history of database.
save	saveAsync	Save molecule with applied data.
insert	insertAsync	Insert multiple rows of data matching molecule.
update	updateAsync	Update molecule with applied data.
tx		Molecule transaction data (input to `getWith`).
inspect get		Inspect calling get method on molecule.
inspect operation		Inspect 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.

trait Molecule_1[Obj, I1] extends InputMolecule

Shared interfaces of input molecules awaiting 1 input.

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

// Input molecule awaiting 1 input for `name`
val ageOfPersons = m(Person.name_(?).age)

// Resolve input molecule with name input in various ways
ageOfPersons("Joe").get === List(42)
ageOfPersons("Joe", "Liz").get === List(42, 34)
ageOfPersons("Joe" or "Liz").get === List(42, 34)
ageOfPersons(Seq("Joe", "Liz")).get === List(42, 34)

I1: Type of input matching attribute with ? marker

trait Molecule_2[Obj, I1, I2] extends InputMolecule

Shared interfaces of input molecules awaiting 2 inputs.

// Sample data set
Person.name.profession.age insert List(
  ("Ann", "doctor", 37),
  ("Ben", "teacher", 37),
  ("Joe", "teacher", 32),
  ("Liz", "teacher", 28)
)

// Input molecule awaiting 2 inputs for `profession` and `age`
val profAge = m(Person.name.profession_(?).age_(?))


// A. Pairs of input .................................

// One pair as params
profAge("doctor", 37).get === List("Ann")

// One or more pairs
profAge(("doctor", 37)).get === List("Ann")
profAge(("doctor", 37), ("teacher", 37)).get.sorted === List("Ann", "Ben")

// One or more logical pairs
// [pair-expression] or [pair-expression] or ...
profAge(("doctor" and 37) or ("teacher" and 32)).get.sorted === List("Ann", "Joe")
profAge(Seq(("doctor", 37), ("teacher", 37))).get.sorted === List("Ann", "Ben")

// List of pairs
profAge(Seq(("doctor", 37))).get === List("Ann")


// B. 2 groups of input, one for each input attribute .................................

// Two expressions
// [profession-expression] and [age-expression]
profAge("doctor" and 37).get === List("Ann")
profAge(("doctor" or "teacher") and 37).get.sorted === List("Ann", "Ben")
profAge(("doctor" or "teacher") and (32 or 28)).get.sorted === List("Joe", "Liz")

// Two Lists
profAge(Seq("doctor"), Seq(37)).get === List("Ann")
profAge(Seq("doctor", "teacher"), Seq(37)).get.sorted === List("Ann", "Ben")
profAge(Seq("teacher"), Seq(37, 32)).get.sorted === List("Ben", "Joe")
profAge(Seq("doctor", "teacher"), Seq(37, 32)).get.sorted === List("Ann", "Ben", "Joe")

I1: Type of input matching first attribute with ? marker (profession: String)
I2: Type of input matching second attribute with ? marker (age: Int)

trait Molecule_3[Obj, I1, I2, I3] extends InputMolecule

Shared interfaces of input molecules awaiting 3 inputs.

// Sample data set
Person.name.profession.age.score insert List(
  ("Ann", "doctor", 37, 1.0),
  ("Ben", "teacher", 37, 1.0),
  ("Joe", "teacher", 32, 1.0),
  ("Liz", "teacher", 28, 2.0)
)

// Input molecule awaiting 3 inputs for `profession`, `age` and `score`
val profAgeScore = m(Person.name.profession_(?).age_(?).score_(?))


// A. Triples of input .................................

// One triple as params
profAgeScore.apply("doctor", 37, 1.0).get === List("Ann")

// One or more triples
profAgeScore.apply(("doctor", 37, 1.0)).get === List("Ann")
profAgeScore.apply(("doctor", 37, 1.0), ("teacher", 37, 1.0)).get.sorted === List("Ann", "Ben")

// One or more logical triples
// [triple-expression] or [triple-expression] or ...
profAgeScore.apply(("doctor" and 37 and 1.0) or ("teacher" and 32 and 1.0)).get.sorted === List("Ann", "Joe")

// List of triples
profAgeScore.apply(Seq(("doctor", 37, 1.0))).get === List("Ann")
profAgeScore.apply(Seq(("doctor", 37, 1.0), ("teacher", 37, 1.0))).get.sorted === List("Ann", "Ben")


// B. 3 groups of input, one for each input attribute .................................

// Three expressions
// [profession-expression] and [age-expression] and [score-expression]
profAgeScore.apply("doctor" and 37 and 1.0).get === List("Ann")
profAgeScore.apply(("doctor" or "teacher") and 37 and 1.0).get.sorted === List("Ann", "Ben")
profAgeScore.apply(("doctor" or "teacher") and (37 or 32) and 1.0).get.sorted === List("Ann", "Ben", "Joe")
profAgeScore.apply(("doctor" or "teacher") and (37 or 32) and (1.0 or 2.0)).get.sorted === List("Ann", "Ben", "Joe")

// Three lists
profAgeScore.apply(Seq("doctor"), Seq(37), Seq(1.0)).get === List("Ann")
profAgeScore.apply(Seq("doctor", "teacher"), Seq(37), Seq(1.0)).get.sorted === List("Ann", "Ben")

I1: Type of input matching first attribute with ? marker (profession: String)
I2: Type of input matching second attribute with ? marker (age: Int)
I3: Type of input matching third attribute with ? marker (score: Double)

trait OptionalMapOps extends AnyRef
Container of implicit for optional Map operations.
trait TxBundles extends AnyRef
trait TxFunctions extends AnyRef
Transactional methods for bundled transactions and tx functions

Value Members

object Keywords extends Keywords
object Molecule_0
Arity 1-22 molecule implementation interfaces.
object Molecule_1
Implementations of input molecules awaiting 1 input, output arity 1-22
object Molecule_2
Implementations of input molecules awaiting 2 inputs, output arity 1-22
object Molecule_3
Implementations of input molecules awaiting 3 inputs, output arity 1-22
object OptionalMapOps extends OptionalMapOps
Optional implicit operations for optional Map attributes
Optional implicit operations for optional Map attributes
Is not imported in the default Molecule api imports since they are rather specialized. If needed, they can be made available with the following aditional import:
```
import molecule.api.optionalMapOps._
import molecule.datomic.api._ // Standard api import with any arity
```
Since this is a rather specialized
object TxFunctions extends Helpers with BridgeDatomicFuture

Packages

api 

package api

Type Members

Value Members

Ungrouped

api