renamed select operation to where

1 files changed, 88 insertions, 29 deletions

diff --git a/README b/README
index efd379d784..0e8f31ce13 100644
--- a/README
+++ b/README
@@ -1,8 +1,16 @@
-== Abstract ==
+## Abstract ##
 
-Arel is a Relational Algebra for Ruby. It 1) simplifies the generation complex of SQL queries and it 2) transparently adapts to various RDBMS systems. It is intended to be a framework framework; that is, you can build your own ORM with it, focusing on innovative object and collection modeling as opposed to database compatibility and query generation.
+Arel is a Relational Algebra for Ruby. It 1) simplifies the generation complex of SQL queries and it 2) adapts to various RDBMS systems. It is intended to be a framework framework; that is, you can build your own ORM with it, focusing on innovative object and collection modeling as opposed to database compatibility and query generation.
 
-== A Gentle Introduction ==
+## Status ##
+
+Arel is alpha software, BEWARE. Nevertheless, at this point, many (most?) SELECT queries can be composed, including very very complicated ones. Writes are only experimental for now.
+
+For the moment, Arel uses ActiveRecord's connection adapters to connect to the various engines, connection pooling, perform quoting, and do type conversion. On the horizon is the use of DataObjects instead.
+
+The long term goal, following both LINQ and DataMapper, is to have Arel adapt to engines beyond RDBMS, including XML, IMAP, YAML, etc.
+
+## A Gentle Introduction ##
 
 Generating a query with ARel is simple. For example, in order to produce
 
@@ -10,56 +18,107 @@ Generating a query with ARel is simple. For example, in order to produce
    
 you construct a table relation and convert it to sql:
 
-    Arel::Table.new(:users).to_sql
+    users = Arel::Table.new(:users)
+    users.to_sql
    
-In fact, you will probably never call `#to_sql`. Let `users = Arel::Table.new(:users)`. Rather, you'll work with data from the table directly. You can iterate through all rows in the `users` table like this:
+In fact, you will probably never call `#to_sql`. Rather, you'll work with data from the table directly. You can iterate through all rows in the `users` table like this:
 
     users.each { |user| ... }
     
-In other words, Arel relations behave implement Ruby's Eunmerable interface. Let's have a look at a concrete example:
+In other words, Arel relations implement Ruby's Enumerable interface. Let's have a look at a concrete example:
 
-    users.first # => {'id' => 10, 'name' => 'bob'}
+    users.first # => { users[:id] => 1, users[:name] => 'bob' }
     
 As you can see, Arel converts the rows from the database into a hash, the values of which are sublimated to the appropriate Ruby primitive (integers, strings, and so forth).
 
-== Relational Algebra ==
+### More Sophisticated <strike>Queries</strike> Relations ###
+
+Here is a whirlwind tour through the most common relational operators. These will probably cover 80% of all interaction with the database.
 
-Arel is based on the Relational Algebra, a mathematical model that is also the inspiration for relational databases. Arel::Relation objects do not represent queries per se (i.e., they are not object-representations of `SELECT`, `INSERT`, `UPDATE`, or `DELETE` statements), rather they represent a collection of data that you can select from, insert into, update, and delete. For example, to insert a row into the users table, do the following:
+First is the 'restriction' operator, `where`:
 
-    users.insert({users[:name] => 'amy'}) # => INSERT INTO users (users.name) VALUES ('amy')
+    users.where(users[:name].eq('amy'))
+    # => SELECT * FROM users WHERE users.name = 'amy'
+
+What would, in SQL, be part of the `SELECT` clause is called in Arel a `projection`:
+
+    users.project(users[:id]) # => SELECT users.id FROM users
     
-To delete all users:
+Joins resemble SQL strongly:
+
+    users.join(photos).on(users[:id].eq(photos[:user_id]))
+    # => SELECT * FROM users INNER JOIN photos ON users.id = photos.user_id
+
+What are called `LIMIT` and `OFFSET` in SQL are called `take` and `skip` in Arel:
+
+    users.take(5) # => SELECT * FROM users LIMIT 5
+    users.skip(4) # => SELECT * FROM users OFFSET 4
+    
+`GROUP BY` is called `group`:
+
+    users.group(users[:name]) # => SELECT * FROM users GROUP BY name
+
+The best property of the Relational Algebra is its "composability", or closure under all operations. For example, to select AND project, just "chain" the method invocations:
+
+    users                                 \
+      .where(users[:name].eq('amy'))      \
+      .project(users[:id])                \
+    # => SELECT users.id FROM users WHERE users.name = 'amy'
+
+All operators are chainable in this way, and they are chainable any number of times, in any order.
 
-    users.delete # => DELETE FROM users
+    users.where(users[:name].eq('bob')).where(users[:age].lt(25))
     
-To update:
+Of course, many of the operators take multiple arguments, so the last example can be written more tersely:
+
+    users.where(users[:name].eq('bob'), users[:age].lt(25))
 
-    users.update({users[:name] => 'carl'}) # => UPDATE users SET name = 'carl'
+The `OR` operator is not yet supported. It will work like this:
+
+    users.where(users[:name].eq('bob').or(users[:age].lt(25)))
     
-As you can see, the `relation` named `users` does not represent an individual query; rather it is an abstraction on a collection of data and it can produce appropriate SQL queries to do the various CRUD operations.
+The `AND` operator will behave similarly.
 
-=== More Sophisticated <strike>Queries</strike> Relations ===
+### The Crazy Features ###
 
-Following the Relational Algebra, Arel's interface uses some jargon that differs from standard SQL. For example, in order to add a `WHERE` clause to your relations, you use the `select` operation:
+The examples above are fairly simple and other libraries match or come close to matching the expressiveness of Arel (e.g., `Sequel` in Ruby).
 
-    users.select(users[:name].eq('amy')) # => SELECT * FROM users WHERE users.name = 'amy'
 
-What would, in SQL, be part of the `SELECT` clause is called here a `projection`:
+#### Complex Joins ####
 
-    users.project(users[:id]) # => SELECT users.id FROM users
+Where Arel really shines in its ability to handle complex joins and aggregations. As a first example, let's consider an "adjacency list", a tree represented in a table. Suppose we have a table `comments`, representing a threaded discussion:
+
+    comments = Arel::Table.new(:comments)
     
-Joins are fairly straightforward:
+And this table has the following attributes:
 
-    users.join(photos).on(users[:id].eq(photos[:user_id])) => SELECT * FROM users INNER JOIN photos ON users.id = photos.user_id
+    comments.attributes # => [comments[:id], comments[:body], comments[:parent_id]]
 
-The best property of the Relational is compositionality, or closure under all operations. For example, to select and project:
+The `parent_id` column is a foreign key from the `comments` table to itself. Now, joining a table to itself requires aliasing in SQL. In fact, you may alias in Arel as well:
 
-    users                                 \
-      .select(users[:name].eq('amy')) \
-      .project(users[:id])                \
-    # => SELECT users.id FROM users WHERE users.name = 'amy'
+    replies = comments.alias
+    comments_with_replies = \
+      comments.join(replies).on(replies[:parent_id].eq(comments[:id]))
+    # => SELECT * FROM comments INNER JOIN comments AS comments_2 WHERE comments_2.parent_id = comments.id
+    
+Arel will always produce a unique name for every table joined in the relation, and it will always do so deterministically to exploit query caching. Typically, the problem with automated table aliasing is that extracting data out of the result set when everything has a random name is quite hard. Arel makes this simple: to get just certain columns from the result set, treat a row like a hash:
+
+    comments_with_replies.first[replies[:body]]
+    
+This will return the first comment's reply's body.
+
+Arel can actually perform the aliasing automatically, without the need for the programmer to explicitly call `alias`. However, this makes it difficult to specify the join condition:
+
+    comments.join(comments).on(comments[:parent_id].eq(comments[:id]))
+    # => SELECT * FROM comments INNER JOIN comments AS comments_2 WHERE comments.parent_id = comments.id
+    
+This does NOT have the same meaning as the previous query. As an alternative to aliasing, there is a convenient block form:
+
+    comments.join(comments) { |comments, replies| replies[:parent_id].eq(comments[:id]) }
+    
+Of course, without the `alias`, you will have a harder time extracting `replies` data from a row.
 
+#### Complex Aggregations ####
 
-== Contributions ==
+My personal favorite feature of Arel, and certainly the most difficult to implement, is closure under joining even in the presence of aggregations. This is a feature where the Relational Algebra is fundamentally easier to use than SQL.
 
-I appreciate all contributions to Arel. There is only one "unusual" requirement I have concerning code style: all specs should be written without mocks, using concrete examples to elicit testable behavior. This has two benefits: it 1) ensures the tests serve as concrete documentation and 2) suits the functional nature of this library, which emphasizes algebraic transformation rather than decoupled components.
\ No newline at end of file