Glossary

asOf

A database value as of a point in time. With asOf, you can reuse existing queries and rules to ask questions about points in time other than the present.

assertion

An atomic fact in the database, associating an entity, attribute, value, and a tx. Opposite of a retraction.

attribute

Something that can be said about an entity. An attribute has a name, e.g. :firstName, and a value type, e.g. :db.type/long, and a cardinality.

cardinality

Property of an attribute that specifies how many values of the attribute can be associated with a single entity. Possible values are :db.cardinality/one and :db.cardinality/many.

closed world assumption

Assumption that truth is what the database knows. Databases that intend to store data of record typically make the closed world assumption. Datomic adheres to the closed world model.

component

A reference attribute that is part of its entity. E.g. your arm is a component of you, but your sister isn't.

connection

Object running on a peer that provides access to a database. Programs can use a connection to submit transactions, or to get current or past values of the database to use as data sources for queries.

coordination

The ability of a group of processes to negotiate who is responsible for the various roles in a Datomic system.

covering index

A covering index contains (rather than points to) the data. Datomic indexes are covering indexes.

credentials

Information used to authenticate for a particular task. In accordance with the principle of least privilege, Datomic allows separate credentials for each different activity performed by a running system.

database

A database is a set of datoms.

data function

A function installed in a database, i.e. an attribute value whose type is :db/fn.

datom

An atomic fact in a database, composed of entity/attribute/value/transaction. Pronounced like "datum", but pluralizes as datoms.

datalog

A deductive query system, typically consisting of:

  • A database of facts
  • A set of rules for deriving new facts from existing facts
  • a query processor that, given some partial specification of a fact or rule: finds all instances of that specification implied by the database and rules, i.e. all the matching facts

Datomic's built-in query is an implementation of Datalog.

edn

An extensible data notation. A superset of edn is used by Clojure to represent programs, and it is used by Datomic and other applications as a data transfer format.

encrypted credentials

Encrypted form of credentials. Datomic encrypts credentials in places like EC2 user data to reduce the threat generic exploits.

entity

The first component of a datom, specifying who or what the datom is about. Also the collection of datoms associated with a single entity, as in the Java type, Entity.

external key

a unique identifier external to Datomic. Typical external key types are email address, UUID, and URI. External key attributes should be declared as db.unique/identity.

epoch

Period of time bounded by writing index to storage. During an epoch, indexing is done in memory. At epoch boundaries, the in-memory index is merged with the persistent index, and a new persistent index is written to the storage service (without blocking the system).

excision

The complete removal of a set of datoms matching a predicate. Excision should be a very infrequent operation, and should not be used to correct erroneous data.

fact

See datom.

Fressian

A binary format that is used everywhere data is serialized by Datomic: on the wire, at rest, and in the segment cache. Fressian is designed to be:

  • self-describing
  • language-independent
  • extensible
  • simple to implement and consume
  • compact and fast
  • friendly to dynamic and static languages
  • compressible in domain-specific ways

keyword

Data type representing a name, e.g. :email or (with namespace) customer/email.

index

Sorted collection of datoms. Indexes are named by the order in which datom components are used for sort, e.g. An index that sorts first by entity, then attribute, then value, then tx is called EAVT.

lookup ref

A list containing an attribute and a value that uniquely identifies an entity.

metrics

Statistics used to measure the health of a running system. By default, Datomic records metrics using Amazon's CloudWatch.

namespace

Prefix portion of a keyword used to make the keyword globally unique. Namespaces serve a similar function to table names in a relational store, without imposing any obligations or limitations, e.g. an entity can have attributes from more than one namespace.

object cache

A cache of objects in VM virtual memory. Peer and transactor processes use the object cache and segment cache to access data directly without having to revisit the storage service.

partition

A logical grouping of entities in a database. Partitions have unique qualified names. Every entity belongs to a partition that is assigned when the entity is created. Partitions act as a storage hint, so that larger systems can plan ahead for better locality of reference for entities that are frequently accessed together. Partitions are typically coarser grained than relational tables. Partitioning is invisible to the query system, and therefore has no impact on the code you write to access the database.

peer

A process that uses the Datomic library to interact with a system, and obtain connections to interact with one or more databases. Peers have in-memory access to database values, and an integrated Datalog query engine. There can be many kinds of peers, with capabilities varying by platform and need.

query

Datomic's Datalog system. A query finds values in a database or other collection of facts subject to the given constraints, and is specified as edn data as described in the Query docs.

reference

An attribute that refers to another entity. References always have the value type db.type/ref.

retraction

An atomic fact in the database, dissociating an entity from a particular value of an attribute. Opposite of an assertion.

role

Generic name for transactor/peer/persistence service., e.g. "The process claims the transactor role by placing a well-known value in SDB upon startup." Used in the config tools.

rule

A named group of query constraints, to allow re-use of logic across queries.

schema

The set of possible attributes that can be associated with entities. Only defines the characteristics of the attributes themselves, not which attributes can be associated with which entities.

segment cache

A cache that stores Fressian-serialized data, e.g. in memcached. A segment cache takes much less memory than equivalent data in the object cache, but is slower to access. Peer and transactor processes use both object caches and segment caches.

storage service

Subsystem responsible for persistence and nothing else. Datomic is designed so that the persistence layer is pluggable, and so that other functions traditionally associated with persistence are handled elsewhere. In particular, storage is provisioned separately from query and transaction capabilities.

system

A running instance of Datomic, comprised of one or more transactors, a storage service, and a storage location (e.g. a particular DynamoDB table). The memory database emulates the full service for the purposes of development and testing.

system id

Unique name for a system within an organization. When using DynamoDB for storage, the system id is identical to the DynamoDB table name.

tx

An entity representing a transaction. Every datom in a Datomic database includes the tx that created it, allowing recovery of the entire history of the database. Transactions are automatically associated with wall-clock time, but are otherwise ordinary entities. In particular, application code can make additional assertions about transactions.

transaction

An atomic unit of work in a database. All Datomic writes are transactional and have the ACID properties (Atomic, Consistent, Isolated, and Durable).

transaction function

A data function designed to be run inside a transaction. Transaction functions must take a database value as their first argument, and must return transaction data.

transactor

A process with the ability to commit transactions for a given database. At any moment in time, a running database has exactly one transactor, but any number of peers.

tuple

An ordered list of elements. Datomic queries return sets of tuples.

unique

Attribute of an attribute. Each entity that has a value for a :db/unique attribute must have a different value. :db/unique has two possible values

  • db.unique/value: attempts to assert a duplicate value will fail
  • db.unique/identity: attempts to assert a duplicate identity will upsert

upsert

Either insert or update an entity, depending on whether the entity already exists. Upsert is implicit in Datomic whenever you make an assertion about an attribute whose unique value is db.unique/identity. Upsert makes it simple to create transactions of the form "Set the first name of the person with SSN 123-45-6789 to "Jon".

value

Something that does not change, e.g. 42, John, or #inst "2012-02-29". A datom relates an entity to a value through an attribute.

value type

Attribute of an attribute that specifies the data structure that can be stored in the attribute. The value type determines how a value is

  • serialized
  • sorted for indexing
  • represented in a programming language type