From 2cc833ab07f8ef77935cf425dd5e6d3daa62c146 Mon Sep 17 00:00:00 2001 From: Carlo Zancanaro Date: Mon, 1 Jul 2013 07:50:26 +1000 Subject: Update the readme --- README.md | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 9a90ee2..2d50a7b 100644 --- a/README.md +++ b/README.md @@ -19,11 +19,26 @@ allow for data to be inserted, updated and deleted. `clojure-sql` aims to have an extensible compiler. Compilation of queries is performed by multimethods which dispatch on an arbitrary (and otherwise unused) `db` parameter. This allows the compilation of -queries to be entirely special-cased per database. By default -`clojure-sql` will produce SQL for PostgreSQL. +queries to be special-cased per database. By default `clojure-sql` +will produce SQL for PostgreSQL (work on other databases may be +undertaken in future). ## Usage +In `clojure-sql` expressions it is generally assumed that: + +* Clojure keywords represent *column names* (exception: the `table` + function) +* Clojure symbols represent *SQL functions* and *SQL operators* +* Clojure strings represent *literal strings* +* Clojure numbers represent *literal numbers* + +Thus: `(and (= :name "Barry") (= (length :username) 10))` compiles +into an SQL expression equivalent to `("name" = 'Barry' AND +"length"("username") = 10)`. + +A few more involved query examples: + (require '[clojure-sql.core :as s]) (-> (s/table :users) ;; tables are automatically given internal aliases @@ -50,12 +65,25 @@ explicitly. `clojure-sql` does not depend on `clojure.java.jdbc`. (deref (-> (s/table :users) (s/project [:id :username]))) - ;; => [{:id 5, :username "mange"}] + ;; => [{:id 5, :username "username"}] Results are returned from queries in an eager vector. [3]: https://github.com/clojure/java.jdbc +## Generated queries + +In general, `clojure-sql` will try to avoid creating subqueries. For +any of the RA primitives (`select`, `join`, `project`, `rename`) no +subqueries will be introduced. The use of non-RA operations (`group`, +`sort`, `take`/`drop`) may introduce a subquery. + +The particular operations which will create a subquery are: + +* `join`ing a query which has been `group`ed +* `sort`ing a query which has been `take`n or `drop`ped from +* `group`ing a query which has been previously `group`ed + ## License Copyright © 2013 Carlo Zancanaro -- cgit v1.2.3