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

    api Molecule API.
    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.
    input Input molecules awaiting input.
    macros Internal macros generating molecule code from custom DSL molecule constructs.
    generic Interfaces to generic information about datoms and Datomic database.
    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 api

    Public interface to be imported to use Molecule.

    Public interface 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 exception
    Definition Classes
    api
  • package get

    Synchronous getter methods to retrieve data from Datomic.

    Synchronous getter methods to retrieve data from Datomic.

    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 5 groups of synchronous getters, each returning data in various formats:

    • GetArray - fastest retrieved typed data set. Can be traversed with a fast while loop
    • GetIterable - for lazily traversing row by row
    • GetJson - data formatted as Json string
    • GetList - 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 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).

    Definition Classes
    api
    See also

    equivalent asynchronous getters in the getAsync package.

  • package getAsync

    Asynchronous getter methods to retrieve data from Datomic.

    Asynchronous getter methods to retrieve data from Datomic.

    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 5 groups of asynchronous getters, each returning Futures of data in various formats:

    • GetAsyncArray - fastest retrieved typed data set. Can be traversed with a fast while loop
    • GetAsyncIterable - for lazily traversing row by row
    • GetAsyncJson - data formatted as Json string
    • GetAsyncList - 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 5 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).

    Definition Classes
    api
    See also

    equivalent synchronous getters in the get package.

  • Entity
  • EntityOps
  • Molecule
  • OptionalMapOps
  • ShowDebug
  • TxMethods
  • core
  • in1_out1
  • in1_out10
  • in1_out11
  • in1_out12
  • in1_out13
  • in1_out14
  • in1_out15
  • in1_out16
  • in1_out17
  • in1_out18
  • in1_out19
  • in1_out2
  • in1_out20
  • in1_out21
  • in1_out22
  • in1_out3
  • in1_out4
  • in1_out5
  • in1_out6
  • in1_out7
  • in1_out8
  • in1_out9
  • in2_out1
  • in2_out10
  • in2_out11
  • in2_out12
  • in2_out13
  • in2_out14
  • in2_out15
  • in2_out16
  • in2_out17
  • in2_out18
  • in2_out19
  • in2_out2
  • in2_out20
  • in2_out21
  • in2_out22
  • in2_out3
  • in2_out4
  • in2_out5
  • in2_out6
  • in2_out7
  • in2_out8
  • in2_out9
  • in3_out1
  • in3_out10
  • in3_out11
  • in3_out12
  • in3_out13
  • in3_out14
  • in3_out15
  • in3_out16
  • in3_out17
  • in3_out18
  • in3_out19
  • in3_out2
  • in3_out20
  • in3_out21
  • in3_out22
  • in3_out3
  • in3_out4
  • in3_out5
  • in3_out6
  • in3_out7
  • in3_out8
  • in3_out9
  • out1
  • out10
  • out11
  • out12
  • out13
  • out14
  • out15
  • out16
  • out17
  • out18
  • out19
  • out2
  • out20
  • out21
  • out22
  • out3
  • out4
  • out5
  • out6
  • out7
  • out8
  • out9

class Entity extends AnyRef

Entity wrapper with actions on entity.

Source
Entity.scala
See also

Manual | Tests: entity api

Linear Supertypes
AnyRef, Any
Type Hierarchy
Ordering
  1. Grouped
  2. Alphabetic
  3. By Inheritance
Inherited
  1. Entity
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Instance Constructors

  1. new Entity(entity: datomic.Entity, conn: Conn, id: AnyRef)

    entity

    datomic.Entity

    conn

    Implicit Conn in scope

    id

    Entity id of type Object

Type Members

  1. case class RetractMolecule(txMeta: MoleculeBase) extends Product with Serializable

    Wrapper to add retract methods on entity with transaction meta data.

    Wrapper to add retract methods on entity with transaction meta data.

    RetractMolecule is created from calling Tx:

    val benId = Person.name("Ben").Tx(MyMetaData.action("add member")).save.eid
    
    // Retract entity with tx meta data
    benId.Tx(MyMetaData.action("moved away")).retract
    
    // Query for Ben's history and why he was retracted
    Person(benId).name.t.op.Tx(MyMetaData.action).getHistory === List(
      ("Ben", 1028, true, "add member"), // Ben added as member
      ("Ben", 1030, false, "moved away") // Ben retracted since he moved away
    )
    txMeta

    A molecule with transaction meta data to be saved with entity retraction

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. def Tx(metaMolecule: MoleculeBase): RetractMolecule

    Entity retraction transaction meta data constructor.

    Entity retraction transaction meta data constructor.

    Build on from entity with Tx and apply a transaction meta data molecule to save transaction meta data with retraction of the entity.

    val benId = Person.name("Ben").Tx(MyMetaData.action("add member")).save.eid
    
    // Retract entity with tx meta data
    benId.Tx(MyMetaData.action("moved away")).retract
    
    // Query for Ben's history and why he was retracted
    Person(benId).name.t.op.Tx(MyMetaData.action).getHistory === List(
      ("Ben", 1028, true, "add member"), // Ben added as member
      ("Ben", 1030, false, "moved away") // Ben retracted since he moved away
    )
    metaMolecule

    Transaction meta data molecule

    returns

    RetractMolecule - a simple wrapper for adding retraction tx meta data

  5. def apply(kw1: String, kw2: String, kws: String*): List[Option[Any]]

    Get List of two or more unchecked/untyped attribute values of entity.

    Get List of two or more unchecked/untyped attribute values of entity.

    Apply two or more namespaced attribute names to return a List of unchecked/untyped optional attribute values.

    Referenced entities can be cast to an Option[Map[String, Any]].

    val List(benId, benAddressId) = Person.name.age.Address.street.insert("Ben", 42, "Hollywood Rd").eids
    
    // Type ascription is still unchecked since it is eliminated by erasure
    val List(
      optName: Option[String],
      optAge: Option[Int],
      optAddress: Option[Map[String, Any]]
    ) = benId(
      ":Person/name",
      ":Person/age",
      ":Person/address"
    )
    
    val name: String = optName.getOrElse("no name")
    
    // Type casting necessary to get right value type from Map[String, Any]
    val address: Map[String, Any] = optAddress.getOrElse(Map.empty[String, Any])
    val street: String = address.getOrElse(":Address/street", "no street").asInstanceOf[String]
    
    name === "Ben"
    street === "Hollywood Rd"

    Typed apply is likely more convenient if typed values are required.

    kw1

    First namespaced attribute name: ":[namespace with lowercase first letter]/[attribute name]"

    kw2

    Second namespaced attribute name

    kws

    Further namespaced attribute names

    returns

    List of optional unchecked/untyped attribute values

  6. def apply[T](kw: String): Option[T]

    Get typed attribute value of entity.

    Get typed attribute value of entity.

    Apply namespaced attribute name with a type parameter to return an optional typed value.

    Note how referenced entities are returned as a Map so that we can continue traverse the entity graph.

    val List(benId, benAddressId) = Person.name.age.Address.street.insert("Ben", 42, "Hollywood Rd").eids
    
    // Level 1
    benId[String](":Person/name") === Some("Ben")
    benId[Int](":Person/age") === Some(42)
    
    // Level 2
    val refMap = benId[Map[String, Any]](":Person/address").getOrElse(Map.empty[String, Any])
    benAddressId[String](":Address/street") === Some("Hollywood Rd")
    
    // Non-asserted or non-existing attribute returns None
    benId[Int](":Person/non-existing-attribute") === None
    benId[Int](":Person/existing-but-non-asserted-attribute") === None
    T

    Type of attribute

    kw

    Namespaced attribute: ":[namespace with lowercase first letter]/[attribute name]"

    returns

    Optional typed attribute value

  7. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  8. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )
  9. def debugRetract: Unit

    Debug entity transaction data of method retract without affecting the database.

    Debug entity transaction data of method retract without affecting the database.

    // Debug retraction of an entity
    eid.debugRetract

    This will print generated Datomic transaction statements in a readable format to output:

    ## 1 ## Debug `retract` on entity
    ========================================================================
    1          List(
      1          List(
        1          :db.fn/retractEntity   17592186045445))
    ========================================================================
  10. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  11. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  12. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  13. final def format2(date: Date): String
    Attributes
    protected
  14. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  15. def getRetractTx: List[List[RetractEntity]]

    Get entity retraction transaction data without affecting the database.

    Get entity retraction transaction data without affecting the database.

    Call getRetractTx to retrieve the generated transaction data of the method retract on an entity

    // Get entity id of Ben
    val benId = Person.e.name_("Ben").get.head
    
    // Retraction transaction data
    benId.getRetractTx === List(List(RetractEntity(17592186045445)))
    returns

    List[List[Retractentity[Long]]]

  16. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  17. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  18. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  19. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  20. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  21. def retract: TxReport

    Retract single entity using entity id.

    Retract single entity using entity id.

    Given the implicit conversion of Long's in molecule.api.EntityOps to an Entity we can can call retract on an entity id directly:

    // Get entity id of Ben
    val benId = Person.e.name_("Ben").get.head
    
    // Retract Ben entity
    benId.retract

    To retract single entity id with tx meta data, use
    eid.Tx(MyMetaData.action("my meta data")).retract

    To retract multiple entities (with or without tx meta data), use
    retract(eids, txMetaDataMolecules*) in molecule.api.EntityOps.

    returns

    molecule.facade.TxReport with result of retraction

  22. def retractAsync(implicit ec: ExecutionContext): Future[TxReport]

    Asynchronously retract single entity using entity id.

    Asynchronously retract single entity using entity id.

    Given the implicit conversion of Long's in molecule.api.EntityOps to an Entity we can can call retractAsync on an entity id directly:

    // Get entity id of Ben
    val benId = Person.e.name_("Ben").get.head
    
    // Retract Ben entity asynchronously
    benId.retractAsync.map { tx =>
      // ..ben was retracted
    }

    To retract single entity id with tx meta data, use
    eid.Tx(MyMetaData.action("my meta data")).retract

    To retract multiple entities (with or without tx meta data), use
    retract(eids, txMetaDataMolecules*) in molecule.api.EntityOps.

    returns

    molecule.facade.TxReport with result of retraction

  23. final lazy val sdf: SimpleDateFormat
    Attributes
    protected
  24. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  25. def toString(): String
    Definition Classes
    AnyRef → Any
  26. def touch: Map[String, Any]

    Get entity graph as Map.

    Get entity graph as Map.

    If entity has reference(s) to other entities it can be a nested graph. Default max levels retrieved is 5.

    • Keys of returned Map are namespaced names of attributes
    • Values of returned Map are untyped attribute values. For references to other entities, the value is a Map itself of the referenced entity attributes, etc.
    val benId = Person.name.age.Address.street.insert("Ben", 42, "Hollywood Rd").eid
    
    benId.touch === Map(
      ":db/id" -> 17592186045445L,
      ":Person/age" -> 42,
      ":Person/address" -> Map(
        ":db/id" -> 17592186045446L,
        ":Address/street" -> "Hollywood Rd"),
      ":Person/name" -> "Ben"
    )
    returns

    Map[key: String, value: Any] where value can be a primitive or another nested Map of the entity graph

  27. def touchList: List[(String, Any)]

    Get entity graph as List.

    Get entity graph as List.

    If entity has reference(s) to other entities it can be a nested graph. Default max levels retrieved is 5.

    • Keys of returned Map are namespaced names of attributes
    • Values of returned Map are untyped attribute values. For references to other entities, the value is a Map itself of the referenced entity attributes, etc.
    val benId = Person.name.age.Address.street.insert("Ben", 42, "Hollywood Rd").eid
    
    benId.touchList === List(
      ":db/id" -> 17592186045445L,
      ":Person/age" -> 42,
      ":Person/address" -> List(
        ":db/id" -> 17592186045446L,
        ":Address/street" -> "Hollywood Rd"),
      ":Person/name" -> "Ben"
    )
    returns

    List[(key: String, value: Any)] where value can be a primitive or another nested List of the entity graph

  28. def touchListMax(maxDepth: Int): List[(String, Any)]

    Get entity graph to some depth as List.

    Get entity graph to some depth as List.

    • Keys of returned Map are namespaced names of attributes
    • Values of returned Map are untyped attribute values. For references to other entities, the value is a Map itself of the referenced entity attributes, etc.
    val benId = Person.name.age.Address.street.insert("Ben", 42, "Hollywood Rd").eid
    
    // 2 levels returned
    benId.touchListMax(2) === List(
      ":db/id" -> 17592186045445L,
      ":Person/age" -> 42,
      ":Person/address" -> List(
        ":db/id" -> 17592186045446L,
        ":Address/street" -> "Hollywood Rd"),
      ":Person/name" -> "Ben"
    )
    
    // 1 level returned
    benId.touchListMax(1) === List(
      ":db/id" -> 17592186045445L,
      ":Person/age" -> 42,
      ":Person/address" -> 17592186045446L // Only reference returned
      ":Person/name" -> "Ben"
    )
    returns

    List[(key: String, value: Any)] where value can be a primitive or another nested Map of the entity graph

    To do

    remove overload hack (by avoiding implicit apply method of scala.collection.LinearSeqOptimized ?)

  29. def touchListQuoted: String

    Get entity graph as List-string (for tests).

    Get entity graph as List-string (for tests).

    If entity has reference(s) to other entities it can be a nested graph. Default max levels retrieved is 5.

    • Keys of returned Map are namespaced names of attributes
    • Values of returned Map are untyped attribute values. For references to other entities, the value is a Map itself of the referenced entity attributes, etc.
    val benId = Person.name.age.Address.street.insert("Ben", 42, "Hollywood Rd").eid
    
    benId.touchListQuoted ===
      """List(
        |  ":db/id" -> 17592186045445L,
        |  ":Person/age" -> 42,
        |  ":Person/address" -> List(
        |    ":db/id" -> 17592186045446L,
        |    ":Address/street" -> "Hollywood Rd"),
        |  ":Person/name" -> "Ben")""",stripMargin
    returns

    String

  30. def touchListQuotedMax(maxDepth: Int): String

    Get entity graph to some depth as List-string (for tests).

    Get entity graph to some depth as List-string (for tests).

    • Keys of returned Map are namespaced names of attributes
    • Values of returned Map are untyped attribute values. For references to other entities, the value is a Map itself of the referenced entity attributes, etc.
    val benId = Person.name.age.Address.street.insert("Ben", 42, "Hollywood Rd").eid
    
    // 2 levels (in this case all levels) returned
    benId.touchListQuotedMax(2) ===
      """List(
        |  ":db/id" -> 17592186045445L,
        |  ":Person/age" -> 42,
        |  ":Person/address" -> List(
        |    ":db/id" -> 17592186045446L,
        |    ":Address/street" -> "Hollywood Rd"),
        |  ":Person/name" -> "Ben")""",stripMargin
    
    // 1 level returned
    // Note that only reference to Address entity on level 2 is returned
    benId.touchListQuotedMax(1) ===
      """List(
        |  ":db/id" -> 17592186045445L,
        |  ":Person/age" -> 42,
        |  ":Person/address" -> 17592186045446L,
        |  ":Person/name" -> "Ben")""",stripMargin
    returns

    String

  31. def touchMax(maxDepth: Int): Map[String, Any]

    Get entity graph to some depth as Map.

    Get entity graph to some depth as Map.

    • Keys of returned Map are namespaced names of attributes
    • Values of returned Map are untyped attribute values. For references to other entities, the value is a Map itself of the referenced entity attributes, etc.
    val benId = Person.name.age.Address.street.insert("Ben", 42, "Hollywood Rd").eid
    
    // 2 levels returned
    benId.touchMax(2) === Map(
      ":db/id" -> 17592186045445L,
      ":Person/age" -> 42,
      ":Person/address" -> Map(
        ":db/id" -> 17592186045446L,
        ":Address/street" -> "Hollywood Rd"),
      ":Person/name" -> "Ben"
    )
    
    // 1 level returned
    benId.touchMax(1) === Map(
      ":db/id" -> 17592186045445L,
      ":Person/age" -> 42,
      ":Person/address" -> 17592186045446L // Only reference returned
      ":Person/name" -> "Ben"
    )
    returns

    Map[key: String, value: Any] where value can be a primitive or another nested Map of the entity graph

  32. def touchQuoted: String

    Get entity graph as Map-string (for presentation).

    Get entity graph as Map-string (for presentation).

    To show the entity graph, this method quotes all text strings so that you can paste the whole graph into any presentation. Pasting it into test code is less useful, since the order of key/value pairs in a Map is not guaranteed. In that case, touchListQuoted is recommended since a List guarantees order.

    If entity has reference(s) to other entities it can be a nested graph. Default max levels retrieved is 5.

    • Keys of returned Map are namespaced names of attributes
    • Values of returned Map are untyped attribute values. For references to other entities, the value is a Map itself of the referenced entity attributes, etc.
    val benId = Person.name.age.Address.street.insert("Ben", 42, "Hollywood Rd").eid
    
    benId.touchQuoted ===
      """Map(
        |  ":db/id" -> 17592186045445L,
        |  ":Person/age" -> 42,
        |  ":Person/address" -> Map(
        |    ":db/id" -> 17592186045446L,
        |    ":Address/street" -> "Hollywood Rd"),
        |  ":Person/name" -> "Ben")""".stripMargin
    returns

    String

  33. def touchQuotedMax(maxDepth: Int): String

    Get entity graph to some depth as Map-string (for presentation).

    Get entity graph to some depth as Map-string (for presentation).

    To show the entity graph, this method quotes all text strings so that you can paste the whole graph into any presentation. Pasting it into test code is less useful, since the order of key/value pairs in a Map is not guaranteed. In that case, touchListQuoted(maxLevel) is recommended since a List guarantees order.

    • Keys of returned Map are namespaced names of attributes
    • Values of returned Map are untyped attribute values. For references to other entities, the value is a Map itself of the referenced entity attributes, etc.
    val benId = Person.name.age.Address.street.insert("Ben", 42, "Hollywood Rd").eid
    
    // 2 levels (in this case all levels) returned
    benId.touchQuotedMax(2) ===
      """Map(
        |  ":db/id" -> 17592186045445L,
        |  ":Person/age" -> 42,
        |  ":Person/address" -> Map(
        |    ":db/id" -> 17592186045446L,
        |    ":Address/street" -> "Hollywood Rd"),
        |  ":Person/name" -> "Ben")""".stripMargin
    
    // 1 level returned
    // Note that only reference to Address entity on level 2 is returned
    benId.touchQuotedMax(1) ===
      """Map(
        |  ":db/id" -> 17592186045445L,
        |  ":Person/age" -> 42,
        |  ":Person/address" -> 17592186045446L,
        |  ":Person/name" -> "Ben")""".stripMargin
    returns

    String

  34. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  35. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  36. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )

Inherited from AnyRef

Inherited from Any

Entity retraction

Entity retraction with transaction meta data

Traverse entity graph

Touch entity graph

Ungrouped