What is EQL?
EQL is a declarative way to make hierarchical (and possibly nested) selections of information about data requirements.
EQL doesn’t have its own language; it uses EDN to express the request, taking advantage of the rich set of primitives provided by it.
EQL for selections
An easy way to get started is to think of a map and try to describe its shape. For example:
{:album/name "Magical Mystery Tour"
:album/year 1967}By describing the shape, we mean describing the structure but without the values, the previous example can be described using EQL as:
[:album/name :album/year]Like using select-keys to specify which fields to extract from a map. Now let’s see
what it looks like for nested structures:
{:album/name "Magical Mystery Tour"
:album/artist {:artist/name "The Beatles"}}
; can be described as:
[:album/name
; note the use of a map to express nesting
{:album/artist
[:artist/name]}]It works the same to represent nested sequences:
{:album/name "Magical Mystery Tour"
:album/tracks [{:track/name "The Fool On The Hill"}
{:track/name "All You Need Is Love"}]}
; can be described as:
[:album/name
{:album/tracks
[:track/name]}]| Although with just EQL you can’t know if a key value is expected to be a single item or a sequence, you can have this information setup out of band using Clojure specs. If you do so, you can instrospect the spec and detect that, this is not a feature of EQL in any way, just a suggested approach in case you need to know if the response of a key is a single item or a sequence. |
EQL for operations
EQL also supports mutations, which are like side effect calls to an API. Mutations can
appear on EQL transaction, and they look like Clojure function calls, example:
[(call-mutation {:data "value"})]More details in Mutations.
Datomic Pull Syntax comparison
On top of the Datomic Pull Syntax expression, EQL also supports:
Check the links on each for more details.
The attribute with options feature from the Datomic Pull Syntax is not present in EQL; instead, we provide the parameterized attributes that can handle arbitrary data to go along the base property.
GraphQL comparison
Similar to GraphQL, EQL works as a language to client libraries to communicate data requirements and operations, there is a good set of intersection in features between both, as:
-
a language to describe arbitrarily nested structures
-
support for mutations (operations to side effect the world)
-
support for parametrization
-
union queries for query branching (select query according to some custom definition based on the data)
GraphQL has a type system in its definition, and it is required for a GraphQL system to work. EQL has no such thing, and it dictates only the syntax but not the semantics. Some features in GraphQL don’t make sense in EQL, like fragments, since EQL is already a data format (EDN), it’s easy to compose data as you would do in a regular Clojure program, for that reason many features are not necessary because EQL is a parseable data format with all the Clojure tools already available to operate on top of it. Also read the AST Encode/Decode section for more information on how to programmatically manipulate EQL data structures.