Query Reference

query                      = [find-spec with-clause? inputs? where-clauses?]

A query consists of:

• a find-spec that specifies variables and aggregates to return
• an optional with-clause to control how duplicate find values are handled
• an optional inputs clause that names the databases, data, and rules available to the query engine
• optional where-clauses that constrain and transform data

At least one of inputs or where-clauses must be specified.

find-spec                  = ':find' find-rel
find-rel                   = find-elem+
find-elem                  = (variable | pull-expr | aggregate)

A find-spec is the literal :find followed by one or more find-elems, which can be

• a variable that returns variables directly
• a pull-expr that hierarchically selects data about an entity variable
• an aggregate that summarizes all values of a variable

The order of find-elems determines the order variables appear in a result tuple.

variable                   = symbol starting with "?"

A variable is a symbol that begins with ?. In a find-spec, variables control which variables are returned, and what order those variables appear in the result tuple.

Like the rest of Clojure, variables are case-sensitive. ?track and ?Track are different variables.

pull-expr                  = ['pull' variable pattern]
pattern                    = (pattern-name | pattern-data-literal)

A pull expression returns information about a variable as specified by a pattern. Pull expressions are fully described in the Pull reference.

NOTE Each variable can appear in at most one pull expression.

You can write your own custom functions for use as aggregate, predicate, or function clauses in query. To make these functions available in Datomic Cloud:

• Include your functions in an ion project.
• Add your functions' fully-qualified names under the :allow key in your ion-config.edn file.
• Push and deploy your ion to the compute group that will use the functions.

You can cancel custom query functions.

NOTE Return maps are available in client 0.8.78.

Supplying a return-map will cause the query to return maps instead of tuples. Each entry in the :keys / :strs / :syms clause will become a key mapped to the corresponding item in the :find clause.

aggregate                  = [aggregate-fn-name fn-arg+]
fn-arg                     = (constant | src-var)

An aggregate function appears in the find clause and transforms a result. Aggregate functions can take variables, constants, or src-vars as arguments.

Aggregates appear as lists in a find-spec. Query variables not in aggregate expressions will group the results and appear intact in the result.

inputs                     = ':in' (src-var | binding | pattern-name | rules-var)+

The inputs clause names and orders the inputs to a query. Inputs can be

• a database name, i.e. a symbol starting with $
• a variable binding, e.g. a symbol starting with ?
• a pattern name, i.e. a plain symbol
• the rules var, i.e. the symbol %

A query has as many inputs as it has :args values, and the inputs bind the :args values for use inside the query.

A binding form tells how to map data onto variables. A variable name like ?artist-name is the simplest kind of binding, assigning its value directly to variable. Other forms support destructuring the data into a tuple, a collection, or a relation:

where-clauses              = ':where' clause+
clause                     = (not-clause | not-join-clause | or-clause | or-join-clause | expression-clause)
expression-clause          = (data-pattern | pred-expr | fn-expr | rule-expr)

A where clause limits the results returned. The most common kind of where clause is a data pattern that is matched against datoms in the database, but there are many other kinds of clauses to support negation, disjunction, predicates, and functions.

where clauses implicitly join. If the same variable appears in multiple clauses, those matches must unify.

data-pattern               = [ src-var? (variable | constant | '_')+ ]

A data pattern is a tuple that begins with an optional src-var which binds to a relation. The src-var is followed one or more elements that match the tuples of that relation in order. The relation is almost always a Datomic database, so the components are E, A, V, Tx, and Op. The elements of data pattern can be

• variables, which unify and bind to values
• constants, which limit results to tuples that match the constant
• the blank _ which matches anything

The underscore symbol (_) is a blank placeholder, and matches anything without binding or unifying. Blanks do not cause unification. Clauses with multiple blanks will not unify despite appearing to have the same symbol used.

pred-expr                  = [ [pred fn-arg+] ]

A predicate is an arbitrary Java or Clojure function. Predicates must be pure functions, i.e. they must be free of side effects and always return the same thing given the same arguments.

Predicates are invoked against variables are that are already bound to further constrain the result set. If the predicate returns false or nil for a set of variable bindings, that set is removed.

Built-in Predicates and Functions lists all built-in predicates.

fn-expr                    = [ [fn fn-arg+] binding]

Queries can call arbitrary Java or Clojure functions. Such functions must be pure functions, i.e. they must be free of side effects and always return the same thing given the same arguments.

Functions are invoked against variables are that are already bound, and their results are interpreted via binding forms to bind additional variables.

Built-in Predicates and Functions lists all built-in functions.

Datomic provides the following built-in expression functions and predicates:

• Two-argument comparison predicates: !=, <, <=, >, and >=.
• Two-argument mathematical operators: +, -, *, and /.

Note: Datomic's / operator is similar to Clojure's / in terms of promotion and contagion with a notable exception: Datomic's / operator does not return a clojure.lang.Ratio to callers. Instead, it returns a quotient as per quot.

• All of the functions from the clojure.core namespace of Clojure, except eval.
• A set of functions and predicates that are aware of Datomic data structures, documented below:
  • get-else
  • get-some
  • ground
  • missing
  • q
  • tuple
  • untuple
• [Peer API] A set of functions that are aware of Datomic's Log:
  • tx-ids
  • tx-data

Java methods can be used as query expression functions and predicates, and should be type hinted for performance. Java code used in this way must be on the Java process classpath.

Java methods should only be used when there is not an equivalent function in clojure.core.

Clojure functions can be used as query expression functions and predicates. Function names outside clojure.core need to be fully qualified and included on the classpath for Pro, or in the ion :allow list for Cloud. The query engine will automatically require namespaces as necessary.

not-clause                 = [ src-var? 'not' clause+ ]

not clauses can express that one or more logic variables inside a query must not satisfy all of a set of predicates. Removes already bound tuples that satisfy the clauses. Unless you specify an explicit src-var, not clauses will target a source named $.

not-join-clause            = (src-var? 'not-join' [var+] clause+)

A not-join clause works exactly like a not clause, but also allows you to specify which variables should unify with the surrounding clause; only this list of variables needs binding before the clause can run.

var specifies which variables should unify.

or-clause                  = [ src-var? 'or' (clause | and-clause)+]

or clauses can express that one or more logic variables inside a query satisfy at least one of a set of predicates. An or clause constrains the result to tuples that satisfy at least one of its /clause/s or /and-clauses/s

and-clause                 = [ 'and' clause+ ]

Inside an or clause, you may use an and clause to specify conjunction. The and clauses is not available (or needed) outside of an or clause, since conjunction is the default in other clauses.

or-join-clause             = [ src-var? 'or-join' [variable+] (clause | and-clause)+ ]

An or-join clause is similar to an or clause, but it allows you to specify which variables should unify with the surrounding clause; only this list of variables needs binding before the clause can run. The /variable/s specifies which variables should unify.

A with-clause considers additional variables not named in the find-spec when forming the basis set for a query result. The with variables are then removed, leaving a bag (not a set!) of values to be consumed by the find-spec. This is particularly useful when finding aggregates.

Datomic datalog allows you to package up sets of :where clauses into named rules. These rules make query logic reusable, and also composable, meaning that you can bind portions of a query's logic at query time.