The page you requested has been relocated to http://edn-query-language.org/eql/1.0.0/what-is-eql.html.
-------------------------------------------------------------------------------- /docs/assets/img/edit.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /project.clj: -------------------------------------------------------------------------------- 1 | (defproject edn-query-language/eql "2025.09.27" 2 | :description "EDN Query Language support library" 3 | :url "https://github.com/edn-query-language/eql" 4 | :license {:name "MIT" :url "https://opensource.org/licenses/MIT"} 5 | 6 | :plugins [[lein-tools-deps "0.4.1"]] 7 | :middleware [lein-tools-deps.plugin/resolve-dependencies-with-deps-edn] 8 | :lein-tools-deps/config {:config-files [:install :user :project] 9 | :clojure-executables ["/opt/homebrew/bin/clojure"]} 10 | 11 | :jar-exclusions [#"public/.*" #"\.DS_Store"]) 12 | -------------------------------------------------------------------------------- /docs-dev.yml: -------------------------------------------------------------------------------- 1 | site: 2 | title: EDN Query Language 3 | url: http://127.0.0.1:8080 4 | start_page: eql::what-is-eql.adoc 5 | keys: 6 | google_analytics: UA-3833116-19 7 | content: 8 | sources: 9 | - url: . 10 | branches: HEAD 11 | start_path: docs-src 12 | ui: 13 | bundle: 14 | url: /Users/wilker.lucio/Development/third-part/docs-ui/build/ui-bundle.zip 15 | snapshot: true 16 | output_dir: assets 17 | output: 18 | dir: ./docs 19 | asciidoc: 20 | attributes: 21 | experimental: '' 22 | tabs: tabs 23 | toc: ~ 24 | xrefstyle: short 25 | -------------------------------------------------------------------------------- /deps.edn: -------------------------------------------------------------------------------- 1 | {:paths 2 | ["src"] 3 | 4 | :deps 5 | {} 6 | 7 | :aliases 8 | {:provided 9 | {:extra-deps {org.clojure/clojure {:mvn/version "1.9.0"} 10 | org.clojure/clojurescript {:mvn/version "1.10.339"} 11 | org.clojure/test.check {:mvn/version "1.0.0"}}} 12 | 13 | :test 14 | {:extra-paths ["test"] 15 | :extra-deps {com.cognitect/test-runner {:git/url "https://github.com/cognitect-labs/test-runner.git" 16 | :sha "5fb4fc46ad0bf2e0ce45eba5b9117a2e89166479"}} 17 | :main-opts ["-m" "cognitect.test-runner"]}}} 18 | -------------------------------------------------------------------------------- /docs/assets/js/vendor/feedback.js: -------------------------------------------------------------------------------- 1 | !function(){"use strict";Math.max(window.screen.availHeight,window.screen.availWidth)<769||window.addEventListener("load",function(){var e=document.getElementById("feedback-script").dataset,c=document.createElement("script");c.src="https://issues.couchbase.com/s/df1d14c9d77c1ad1c4ef2db3d8d7da3f-T/-6ikjte/73013/c4d560fe7f608200148fbd40cb0f35ae/2.0.23/_/download/batch/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector.js?locale=en-US&collectorId="+e.collectorId,document.body.appendChild(c)})}(); -------------------------------------------------------------------------------- /docs.yml: -------------------------------------------------------------------------------- 1 | site: 2 | title: EDN Query Language 3 | url: http://edn-query-language.org 4 | start_page: eql::what-is-eql.adoc 5 | keys: 6 | google_analytics: UA-3833116-19 7 | content: 8 | sources: 9 | - url: git@github.com:edn-query-language/eql.git 10 | branches: HEAD 11 | start_path: docs-src 12 | ui: 13 | bundle: 14 | url: https://github.com/wilkerlucio/docs-ui/raw/wsscode-theme/build/ui-bundle.zip 15 | snapshot: true 16 | output_dir: assets 17 | runtime: 18 | fetch: true 19 | output: 20 | dir: ./docs 21 | asciidoc: 22 | attributes: 23 | experimental: '' 24 | tabs: tabs 25 | toc: ~ 26 | xrefstyle: short 27 | -------------------------------------------------------------------------------- /docs/sitemap.xml: -------------------------------------------------------------------------------- 1 | 2 |The page you're looking for does not exist. It may have been moved.
43 |If you arrived on this page by clicking on a link, please notify the owner of the site that the link is broken. 46 | If you typed the URL of this page manually, please double check that you entered the address correctly.
47 |Here you can find a formal definition for the query syntax, expressed as Clojure Specs.
95 |(s/def ::property keyword?)
99 | (s/def ::special-property #{'*})
100 | (s/def ::ident-value (s/with-gen any? (default-gen ::gen-ident-value)))
101 | (s/def ::ident (s/with-gen (s/tuple ::property ::ident-value) (default-gen ::gen-ident)))
102 | (s/def ::join-key (s/or :prop ::property, :ident ::ident, :param-exp ::join-key-param-expr))
103 | (s/def ::join (s/map-of ::join-key ::join-query, :count 1, :conform-keys true))
104 | (s/def ::union (s/map-of ::property ::query, :min-count 1, :conform-keys true))
105 | (s/def ::recursion-depth (s/with-gen nat-int? (default-gen ::gen-depth)))
106 | (s/def ::recursion (s/or :depth ::recursion-depth, :unbounded #{'...}))
107 |
108 | (s/def ::join-query
109 | (s/with-gen
110 | (s/or :query ::query
111 | :union ::union
112 | :recursion ::recursion)
113 | (default-gen ::gen-join-query)))
114 |
115 | (s/def ::params
116 | (s/with-gen map? (default-gen ::gen-params)))
117 |
118 | (s/def ::param-expr-key
119 | (s/with-gen
120 | (s/or :prop ::property
121 | :join ::join
122 | :ident ::ident)
123 | (default-gen ::gen-param-expr-key)))
124 |
125 | (s/def ::param-expr
126 | (s/with-gen
127 | (s/and seq? (s/cat :expr ::param-expr-key :params (s/? ::params)))
128 | (default-gen ::gen-param-expr)))
129 |
130 | (s/def ::join-key-param-key (s/or :prop ::property :ident ::ident))
131 |
132 | (s/def ::join-key-param-expr
133 | (s/with-gen
134 | (s/and seq? (s/cat :expr ::join-key-param-key :params (s/? ::params)))
135 | (default-gen ::gen-join-key-param-expr)))
136 |
137 | (s/def ::mutation-key (s/with-gen symbol? (default-gen ::gen-mutation-key)))
138 |
139 | (s/def ::mutation-expr
140 | (s/with-gen
141 | (s/and seq? (s/cat :mutate-key ::mutation-key :params (s/? ::params)))
142 | (default-gen ::gen-mutation-expr)))
143 |
144 | (s/def ::mutation-join
145 | (s/map-of ::mutation-expr ::query :count 1 :conform-keys true))
146 |
147 | (s/def ::mutation
148 | (s/or :mutation ::mutation-expr
149 | :mutation-join ::mutation-join))
150 |
151 | (s/def ::query-expr
152 | (s/or :prop ::property
153 | :join ::join
154 | :ident ::ident
155 | :mutation ::mutation
156 | :param-exp ::param-expr
157 | :special ::special-property))
158 |
159 | (s/def ::query
160 | (s/coll-of ::query-expr :kind vector? :gen (default-gen ::gen-query)))
EQL is a declarative way to make hierarchical (and possibly nested) selections of information about data requirements.
100 |EQL doesn’t have its own language; it uses EDN to express the request, taking advantage of 103 | the rich set of primitives provided by it.
104 |An easy way to get started is to think of a map and try to describe its shape. For example:
112 |{:album/name "Magical Mystery Tour"
116 | :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:
121 |[:album/name :album/year]Like using select-keys to specify which fields to extract from a map. Now let’s see
129 | what it looks like for nested structures:
{:album/name "Magical Mystery Tour"
134 | :album/artist {:artist/name "The Beatles"}}
135 |
136 | ; can be described as:
137 |
138 | [:album/name
139 | ; note the use of a map to express nesting
140 | {:album/artist
141 | [:artist/name]}]It works the same to represent nested sequences:
146 |{:album/name "Magical Mystery Tour"
150 | :album/tracks [{:track/name "The Fool On The Hill"}
151 | {:track/name "All You Need Is Love"}]}
152 |
153 | ; can be described as:
154 |
155 | [:album/name
156 | {:album/tracks
157 | [:track/name]}]| 164 | 165 | | 166 |167 | Although with just EQL you can’t know if a key value is expected to be a single item or a sequence, you 168 | can have this information setup out of band using Clojure specs. If you do so, you can instrospect the spec 169 | and detect that, this is not a feature of EQL in any way, just a suggested approach in case you need to know 170 | if the response of a key is a single item or a sequence. 171 | | 172 |
EQL also supports mutations, which are like side effect calls to an API. Mutations can
182 | appear on EQL transaction, and they look like Clojure function calls, example:
[(call-mutation {:data "value"})]More details in Mutations.
191 |On top of the Datomic Pull Syntax expression, EQL also supports:
199 |Check the links on each for more details.
215 |The attribute with options feature 218 | from the Datomic Pull Syntax is not present in EQL; instead, we provide the parameterized 219 | attributes that can handle arbitrary data to go along the base property.
220 |Similar to GraphQL, EQL works as a language to client libraries to communicate data requirements and operations, 228 | there is a good set of intersection in features between both, as:
229 |a language to describe arbitrarily nested structures
234 |support for mutations (operations to side effect the world)
237 |support for parametrization
240 |union queries for query branching (select query according to some custom definition based on the data)
243 |GraphQL has a type system in its definition, and it is required for a GraphQL system to work. EQL has 248 | no such thing, and it dictates only the syntax but not the semantics. Some features in 249 | GraphQL don’t make sense in EQL, like fragments, since EQL is already a data format (EDN), 250 | it’s easy to compose data as you would do in a regular Clojure program, for that reason 251 | many features are not necessary because EQL is a parseable data format with all the Clojure 252 | tools already available to operate on top of it. Also read the AST Encode/Decode 253 | section for more information on how to programmatically manipulate EQL data structures.
254 |The package edn-query-language.core provides a suite of specs to validate queries and
97 | ASTs. It also provides generators for the query and helper functions to common
98 | query operations.
The EQL library provides specs to validate and generate queries.
107 |You can validate the query syntax using clojure.spec, here is an example:
112 |(s/valid? ::eql/query [:sample :query]) ; => true
116 | (s/valid? ::eql/query [#{:set}]) ; => false
117 | (s/valid? ::eql/query ['(call/op {})]) ; => true| 124 | 125 | | 126 |
127 | s is alias for clojure.spec.alpha
128 | |
129 |
You can use spec explain feature for more details:
134 |(s/explain ::eql/query [#{:set}])
138 | ; In: [0] val: #{:set} fails spec: :edn-query-language.core/mutation-expr at: [:mutation :mutation] predicate: seq?
139 | ; In: [0] val: #{:set} fails spec: :edn-query-language.core/mutation-join at: [:mutation :mutation-join] predicate: map?
140 | ; In: [0] val: #{:set} fails spec: :edn-query-language.core/property at: [:prop] predicate: keyword?
141 | ; In: [0] val: #{:set} fails spec: :edn-query-language.core/join at: [:join] predicate: map?
142 | ; In: [0] val: #{:set} fails spec: :edn-query-language.core/ident at: [:ident] predicate: vector?
143 | ; In: [0] val: #{:set} fails spec: :edn-query-language.core/param-expr at: [:param-exp] predicate: seq?
144 | ; In: [0] val: #{:set} fails spec: :edn-query-language.core/special-property at: [:special] predicate: #{(quote *)}I suggest you check the sources for the specs for more details on parts that compose 149 | it, they will stay consistent and can be used to validate parts of the transaction as well.
150 |EQL also provides built-in generators, the main intended usage for it is to write generative 156 | tests for parser implementations.
157 |Basic example to generate random queries:
160 |(gen/sample (s/gen ::query) 10)
164 | =>
165 | ([]
166 | []
167 | [(:?./*_ {}) :z/ZH]
168 | []
169 | [#:J{:w {:c/!V [#:YY{:u [:u1/X?!
170 | #:r94{:*+ [#:aG{:YA 2} :t!o/Ya1 :XL/HR #:!-Q{:b_ []}]}
171 | :OP/E]}
172 | :.qE/Nd-],
173 | :j./!T [[:p/h*y :f?1]
174 | #:s*{:-W []}
175 | (NG_
176 | {[] #{}, [4] (0.5 :_ -3 -Ch), #{} #{}, #{-1 {##-Inf ?.1/e?A}} {}})],
177 | :z/s+ []}}
178 | :-_/_
179 | :H/E
180 | :Y/xD]
181 | [:?7/w :iO/! (:r/!N {{-2.0 false} [], [] [], [:P7] [0 J1]})]
182 | [:+Bi/-K :!8*/r0 :?/Cio]
183 | [:*.-/R* :+BT/W :-l8/c :Ih/V [:RE/- "0>WwI`u"] :H/vT]
184 | [:z+8/g]
185 | [])| 192 | 193 | | 194 |
195 | gen is alias for clojure.test.check.generators
196 | |
197 |
Although fully random queries can be interesting to test some parser edge cases, in many 202 | situations you will may want to constraint how the query is generated, with this in mind 203 | EQL provides a way to enable this kind of customization. To get a sense of what you can 204 | customize you can take a look at the default implementation for each default generator, 205 | any of those keys can be tuned to constraint how the query is generated.
206 |To demonstrate how to use this, let’s customize the generator to limit the properties it generates 209 | to a fixed set we pre defined:
210 |(gen/sample (eql/make-gen {::eql/gen-property ; (1)
214 | (fn [_] (gen/elements [:id :name :title :foo :bar]))}
215 | ::eql/gen-query) ; (2)
216 | 10)
217 | =>
218 | ([]
219 | []
220 | []
221 | [[:X/q6 1] :name :title]
222 | [({:title [(L {#{} [], () [], #{-5} ()})
223 | (:name {{#{} {}} :., {} {}})
224 | {:name [:bar :title]}]}
225 | {[*+-] #{0.5625 #uuid"edf051fb-ab28-42d0-a941-152c4e87b060"},
226 | #{#uuid"712e7415-5148-400b-99db-cfb79004700e" -1/2} (),
227 | {} (:F/le9 #uuid"5ad52713-d13a-4888-bd92-2d1541c0387b" "" true)})
228 | {(:foo
229 | {[(2.0 false) z/NO] [I./j #uuid"eef64a1d-8055-4ae7-95be-06bdc4f9cefd"], {} [""]}) [:id
230 | ({:id [:name
231 | *]}
232 | {})]}]
233 | [:id :id]
234 | [{:foo [:name * [:mO/D MZ_/e0Z] :bar :foo]}]
235 | []
236 | [:bar]
237 | [:foo])| 1 | 244 |We send a map to eql/make-gen to override some of the generator settings, any non
245 | defined keys will fallback to default implementation |
246 |
| 2 | 249 |Select which generator to use, this is useful to generate only sub-parts if needed | 250 |
One more example changing many definitions:
255 |(let [system (assoc generators
259 | ::gen-params
260 | (fn [_] (gen/map (gen/elements [:param :foo/param]) gen/string-ascii))
261 |
262 | ::gen-property
263 | (fn [_] (gen/elements [:id :name :title :foo :bar :other :price :namespaced/value]))
264 |
265 | ::gen-ident-key
266 | (fn [_] (gen/elements [:user/by-id :other/by-id]))
267 |
268 | ::gen-ident-value
269 | (fn [_] gen/string-ascii)
270 |
271 | ::gen-mutation-key
272 | (fn [_] (gen/elements '[do-something create/this-thing operation.on/space])))]
273 | (gen/sample ((::gen-query system) system)))
274 | =>
275 | ([]
276 | [{:other []}]
277 | []
278 | []
279 | []
280 | [{:price [{[:user/by-id "!"] []} :title]} :id]
281 | [:bar {[:other/by-id "@"] [:foo :other :name]}]
282 | [:name :id]
283 | [:price :title :id :name]
284 | [:foo
285 | ({:bar [[:user/by-id ""] :price {:id [:other]} :other]} {})
286 | :other
287 | :namespaced/value
288 | {:name [:name
289 | {:bar [:name
290 | :bar
291 | :namespaced/value
292 | ({[:user/by-id "AeA$;"] [:foo]}
293 | {:foo/param "_+y9ihY", :param "Y@p5Bd5B"})
294 | :id
295 | :namespaced/value
296 | :name]}]}
297 | :id])If you wanna see an even more advanced usage, you can check Pathom connect generator, which 302 | uses the Pathom connect index to generate queries that are valid according to the user property graph.
303 |If you are not using the specs provided by EQL you can free some build space by 309 | eliding then. To do that you need to set the Clojurescript compiler options with:
310 |{:closure-defines {edn-query-language.core.INCLUDE_SPECS false}}To convert between query and AST, EQL provides the helper functions eql/query→ast and
324 | eql/ast→query. Here are some example usages:
(eql/query->ast [:foo])
329 | ; => {:type :root, :children [{:type :prop, :dispatch-key :foo, :key :foo}]}
330 |
331 | (eql/ast->query {:type :root, :children [{:type :prop, :dispatch-key :foo, :key :foo}]})
332 | ; => [:foo]Check the complete API docs at EQL cljdoc page.
342 |