Find Specifications

Every query so far has used the default :find form, which returns a collection of tuples. Datomic Datalog offers four distinct find specifications, each returning a different shape. Choosing the right one makes downstream code simpler.

Relation (default) — collection of tuples

The standard form. Each variable becomes a column; each matching combination becomes a row. Order among the rows is not guaranteed.

Collection — flat vector of one variable

Wrap a single variable in [?var ...] to get a flat vector of its values instead of a collection of single-element tuples. Useful when you only care about one column and want to pass it directly to other code:

Scalar — single value

Append . after the variable to return exactly one value instead of a collection. When multiple rows match, which one you get is arbitrary, so scalars are most useful with aggregations that already produce a single row, like (max ...):

Without the . this would return [[150]]: a collection containing one single-element tuple. With it you get the bare number 150.

Tuple — single row

Wrap multiple variables in [?a ?b] (no ...) to return exactly one tuple. If the query matches several rows, you get one of them and Datomic does not tell you the others existed, so the query has to be guaranteed to match one row. That takes two things: the lookup goes through a unique attribute, and every other attribute it joins is cardinality one. In this database :pokemon/number is declared :db.unique/identity, and :pokemon/name, :stat/hp and :stat/speed each hold one value per Pokemon:

The result is a plain vector ["Pikachu" 35 90] rather than a collection of tuples, easy to destructure directly in Clojure. Any number that exists in the database gives exactly one row.

What could go wrong

Break either condition and the tuple spec stops being safe. This query looks the Pokemon up by :pokemon/name, which the schema does not make unique, and it joins :pokemon/type, which is cardinality many. Bulbasaur is Grass and Poison, so 2 rows match. Before you run it, predict what the tuple spec returns:

You get a single tuple with one of the two types. There is no error and no warning, and the other type is gone. Swap in "Pikachu" and the same query looks fine, but only because Pikachu happens to have one type.

When you want one entity with everything it has, use pull with the scalar find spec instead. The Pull chapter covers it: a cardinality-many attribute comes back as a collection holding every value.