Schema

Every new attribute is described by three required attributes:

• :db/ident specifies the unique name of an attribute. It's value is a namespaced keyword with the lexical form :<namespace>/<name>. It is possible to define a name without a namespace, as in :<name>, but a namespace is preferred in order to avoid naming collisions. Namespaces can be hierarchical, with segments separated by ".", as in :<namespace>.<nested-namespace>/<name>. The :db namespace is reserved for use by Datomic itself.

• Keywords map to the native interned-name type in languages that support them.
• Instants are stored as the number of milliseconds since the epoch.
• Symbols map to the symbol type in languages that support them, e.g. clojure.lang.Symbol in Clojure
• Consistent results in query depend on the scale matching for all BigDecimal comparisons. You are strongly encouraged to use a consistent scale per attribute.

Tuples can be used to create multi-attribute unique keys on domain entities. Tuples can be used to optimize queries that otherwise would have to join two or more high-population attributes.

Note: Tuples require 0.9.5927 or later and a compatible base schema.

A tuple is a collection of 2-8 scalar values, represented in memory as a Clojure vector. There are three kinds of tuples:

• Composite tuples are derived from other attributes of the same entity. Composite tuple types have a :db/tupleAttrs attribute, whose value is 2-8 keywords naming other attributes.
• Heterogeneous fixed length tuples have a :db/tupleTypes attribute, whose value is a vector of 2-8 scalar value types.
• Homogeneous variable length tuples have a :db/tupleType attribute, whose value is a keyword naming a scalar value type.

The following types are considered scalar types suitable for use in a tuple:

:db.type/bigdec :db.type/bigint :db.type/boolean :db.type/double 
:db.type/instant :db.type/keyword :db.type/long :db.type/ref :db.type/string 
:db.type/symbol :db.type/uri :db.type/uuid 

String values within a tuple are limited to 256 characters.

nil is a legal value for any slot in a tuple. This facilitates using tuples in range searches, where nil sorts lowest.

Datomic includes the query helpers tuple and untuple to support storing same values both in a tuple and in separate attributes.

Composite tuples are applicable:

• when a domain entity has a multi-attribute key
• to optimize a query that joins more than one high-population attributes on the same entity

For example, consider the domain of course registrations, modelled with the following entity types:

• courses represent a course, e.g. Algebra II
• semesters represent a period in time when a course is run, e.g. "Fall 2019"
• students can take courses in particular semesters

[{:db/ident :student/first
  :db/valueType :db.type/string
  :db/cardinality :db.cardinality/one}
 {:db/ident :student/last
  :db/valueType :db.type/string
  :db/cardinality :db.cardinality/one}
 {:db/ident :student/email
  :db/valueType :db.type/string
  :db/cardinality :db.cardinality/one
  :db/unique :db.unique/identity}
 {:db/ident :semester/year
  :db/valueType :db.type/long
  :db/cardinality :db.cardinality/one}
 {:db/ident :semester/season
  :db/valueType :db.type/keyword
  :db/cardinality :db.cardinality/one}
 {:db/ident :semester/year+season
  :db/valueType :db.type/tuple
  :db/tupleAttrs [:semester/year :semester/season]
  :db/cardinality :db.cardinality/one
  :db/unique :db.unique/identity}
 {:db/ident :course/id
  :db/valueType :db.type/string
  :db/unique :db.unique/identity
  :db/cardinality :db.cardinality/one}
 {:db/ident :course/name
  :db/valueType :db.type/string
  :db/cardinality :db.cardinality/one}]

A registration entity is a unique combination of a student, semester, and course. In Datomic schema:

{:db/ident :reg/course
 :db/valueType :db.type/ref
 :db/cardinality :db.cardinality/one}
{:db/ident :reg/semester
 :db/valueType :db.type/ref
 :db/cardinality :db.cardinality/one}
{:db/ident :reg/student
 :db/valueType :db.type/ref
 :db/cardinality :db.cardinality/one}

A given course/semester/student combination is unique in the database. To model this, you can create a composite tuple whose :db/tupleAttrs are

{:db/ident :reg/semester+course+student
 :db/valueType :db.type/tuple
 :db/tupleAttrs [:reg/course :reg/semester :reg/student]
 :db/cardinality :db.cardinality/one
 :db/unique :db.unique/identity}

With this composite installed, Datomic's unique identity will ensure that all assertions about a semester/course/student combination resolve to the same entity.

Composite attributes are entirely managed by Datomic–you never assert or retract them yourself. Whenever you assert or retract any attribute that is part of a composite, Datomic will automatically populate the composite value.

Given a database with the courses and semesters schema, add some seed data:

[{:semester/year 2018
  :semester/season :fall}
 {:course/id "BIO-101"}
 {:student/first "John"
  :student/last "Doe"
  :student/email "johndoe@university.edu"}]

Now if you register John for Bio 101 in the fall of 2018 by transacting:

[{:reg/course [:course/id "BIO-101"]
  :reg/semester [:semester/year+season [2018 :fall]]
  :reg/student [:student/email "johndoe@university.edu"]}] 

Datomic will also add the composite tuple datom:

#datom[20736789299855447 83 [6324390882967637 44112406506373204 64110323992363094] 13194139533320 true]]

Note that your entity IDs will differ from those in the example above

If the current value of an entity does not include all attributes of a composite, the missing attributes will be nil. For example, given a composite 4-tuple :reg/semester+course+student+grade that also includes a student’s grade, the assertions above would cause Datomic to populate:

#datom[20736789299855447 83 [6324390882967637 44112406506373204 64110323992363094 nil] 13194139533320 true]]

Note that nil sorts lower than all other values, so tuples with trailing nils can be useful for range queries.

If you retract all constituents of a composite, Datomic will retract the composite. For example, transacting:

[[:db/retract 20736789299855447 :reg/course [:course/id "BIO-101"]]
 [:db/retract 20736789299855447 :reg/semester [:semester/year+season [2018 :fall]]]
 [:db/retract 20736789299855447 :reg/student [:student/email "johndoe@university.edu"]]]

will cause Datomic to retract the composite:

#datom[20736789299855447 83 [6324390882967637 44112406506373204 64110323992363094] 13194139533321 false]]

Again, note that you will need to substitute the entity IDs from your initial transaction to replicate this example in your system.

Adding a composite tuple to a database that contains existing data using those attributes will not immediately generate values for the new tuple. The composite tuple will be created the next time any of the composite member attributes are transacted. This includes "no-op" transactions of the same attribute value. This design allows you to add composite tuples in a systematic and paced manner, so as not to overwhelm a running system.

An example helper function can be found in the day of datomic cloud examples. The function will cycle through all values for a given attribute, reasserting them, with the specified batch size and pause between batches. You can use this, or something like it, to systematically add composite tuples once you've created the necessary schema attribute(s).

All entities in a database have an internal key, the entity id. You can use :db/unique to define an attribute to represent an external key.

An entity may have any number of external keys.

External keys must be single attributes, multi-attribute keys are not supported.

Attribute definitions are represented as data structures (see Data Structures) that can be submitted to a database as part of a transaction. It is idiomatic to use the transaction map data structure, as shown in the following example. It defines an attribute named :person/name of type :db.type/string with :db.cardinality/one that is intended to capture a person's name.

{:db/ident :person/name
 :db/valueType :db.type/string
 :db/cardinality :db.cardinality/one
 :db/doc "A person's name"}

Every attribute definition must include :db/ident, :db/valueType, and :db/cardinality.

Leading underscores are used for reverse lookup in pull.

If your attribute has a leading underscore then you will not be able to use reverse lookup with that attribute.

Attribute installation is atomic. All the required information for an attribute must be specified in a single transaction, after which the attribute will be immediately available for use.

The :db.entity/attrs attribute is a cardinality-many attribute of keywords, where each keyword names a required attribute.

For example, the following transaction data creates a spec that requires a :user/name and :user/email:

{:db/ident :user/validate
 :db.entity/attrs [:user/name :user/email]}

The :user/validate entity can then be used in later transactions to ensure that all required attribute are present.

When an entity references required attributes via a :db/ensure, Datomic will verify that all attributes are present on that entity in the end-of-transaction (db-after) database value. The example below would fail validation unless John Doe already had a :user/email in db-before.

{:user/name "John Doe"
 :db/ensure :user/validate}

When a required attribute is missing, Datomic will throw an anomaly whose ex-data includes the failing entity and the name of the spec, e.g.:

{:cognitect.anomalies/category
 :cognitect.anomalies/incorrect, 
 :cognitect.anomalies/message
 "Entity 42 missing attributes [:user/email] by :user/validate"}

The :db.entity/preds attribute is a cardinality-many attribute of symbols, where each symbol names a predicate of database value (db-after) and entity id. Before committing a transaction, Datomic will check all predicates requested by a :db/ensure against db-after and entity id, aborting the transaction if any predicate returns a value that is not true.

Entity predicates must be on the classpath of a process that is performing a transaction.

For example, given the following predicate:

(ns datomic.samples.entity-preds
  (:require [datomic.api :as d]))

(defn scores-are-ordered?
  [db eid]
  (let [m (d/pull db [:score/low :score/high] eid)]
    (<= (:score/low m) (:score/high m))))

You could install the predicate on a guard entity:

{:db/ident :score/guard
 :db.entity/attrs [:score/low :score/high] ;; entity spec
 :db.entity/preds 'datomic.samples.entity-preds/scores-are-ordered?} ;; entity predicate

Given an invalid entity that requests the :score/guard:

{:score/low 100
 :score/high 20
 :db/ensure :score/guard}

Datomic will throw an anomaly whose ex-data names the failing predicate:

{:cognitect.anomalies/category 
 :cognitect.anomalies/incorrect,
 :cognitect.anomalies/message
 "Entity 42 failed pred datomic.samples.entity-preds/scores-are-ordered? of spec :score/guard"
 :db.error/pred-return false}

Datomic will report the value returned by the failing predicate under the :db.error/pred-return key. This can be used to report more information about what went wrong.

cancel can be used from an entity predicate to cancel the entire transaction.

To facilitate entity grouping when using a multitude of partitions, each Datomic database includes 524288 implicit partitions, which can be accessed by calling implicit-part. Unlike named partitions, implicit partitions require no transaction to create. Like named partitions, each implicit partition corresponds to an entity ID.

Applications can employ algorithmic schemes to group related entities to the same partition. For example, an order processing system could assign a customer to an implicit partition (e.g. via hashing), then put all of a customer's order and line item entities in that partition. This would improve locality of reference when querying for a customer's orders.

Partitions are discussed in more detail in the Indexes topic.

A partition is represented by an entity with a :db/ident attribute, as shown below. A partition can be referred to by either its entity id or ident.

{:db/ident :communities}

As with attribute definitions, there are two steps to installing a new partition in a database. The first is to create the partition entity. The second is to associate the new partition entity with the built-in system partition entity, :db.part/db. Specifically, the new partition must be added as a value of the :db.part/db entity's :db.install/partition attribute. This linkage is what tells the database that the new entity is actually a partition definition.

Here is a complete transaction for installing the :communities partition. It includes the map that defines the partition, followed by the statement adding it as a value of :db.part/db's :db.install/partition attribute.

[{:db/id "communities"
  :db/ident :communities}
 [:db/add :db.part/db :db.install/partition "communities"]]