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.

    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.

    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.

    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.

    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.

    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.

    Methods to build transaction, composite and nested molecules.

    Definition Classes
    molecule
  • package exceptions

    Exceptions thrown by Molecule.

    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.

    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.

    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.

    Internal macros generating molecule code from custom DSL molecule constructs.

    Definition Classes
    molecule
  • package ops

    Internal operational helpers for transforming DSL to molecules.

    Internal operational helpers for transforming DSL to molecules.

    Definition Classes
    molecule
  • package schema

    Schema definition DSL and API.

    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.

    Internal Java database functions for Datomic.

    Definition Classes
    molecule
p

molecule

action

package action

Various actions and operations on molecules and entities.

Source
package.scala
Linear Supertypes
AnyRef, Any
Content Hierarchy
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. action
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Type Members

  1. trait CompositeInserts extends Helpers

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

    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

  2. class Entity extends AnyRef

    Entity wrapper with actions on entity.

    Entity wrapper with actions on entity.

    See also

    Manual | Tests: entity api

  3. trait EntityOps extends AnyRef

    Operations on multiple entities.

  4. 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.

    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

  5. trait OptionalMapOps extends AnyRef

    Container of implicit for optional Map operations.

    Container of implicit for optional Map operations.

    See also

    Tests

  6. 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.

Value Members

  1. object Entity

    Entity wrapper factory.

  2. object Molecule

    Arity 1-22 molecule implementation interfaces.

Inherited from AnyRef

Inherited from Any

Ungrouped