Permalink
Browse files

Adds querying docs

[ci skip]
  • Loading branch information...
danmcclain committed Feb 8, 2013
1 parent 8376047 commit e1ee16439ede8769dc198a637f444b27462f0b29
Showing with 48 additions and 7 deletions.
  1. +48 −7 docs/querying.md
View
@@ -1,7 +1,7 @@
# Querying PostgreSQL datatypes
* [Arrays](#arrays)
- * [INET/CIDR](#inetcidr)
+ * [INET/CIDR](#inetcidr-queries)
## Arrays
@@ -22,8 +22,17 @@ ARRAY[1,2,3] && ARRAY[3,5,6]
-- t
```
+Postgres\_ext extends the `ActiveRecord::Relation.where` method similar
+to the Rails 4.0 not clause. The easiest way to make a overlap query
+would be:
+
+```ruby
+User.where.overlap(:nick_names => ['Bob', 'Fred'])
+```
+
Postgres\_ext defines `array_overlap`, an [Arel](https://github.com/rails/arel)
-predicate for the `&&` operator.
+predicate for the `&&` operator. This is utilized by the `where.overlap`
+call above.
```ruby
user_arel = User.arel_table
@@ -51,6 +60,16 @@ Notice that the column is on the right hand side of the predicate,
instead of the left, because we have to call the `ANY` function on that
column.
+Postgres\_ext provides a `ActiveRecord::Relation.where.any()` method. The
+easiest way to make a ANY query would be:
+
+```ruby
+User.where.any(:nick_names => 'Bob')
+```
+
+There is also an `ActiveRecord::Relation.where.all()` call as well. This
+method utilizes the following code to create the query:
+
We can generate the above query using [Arel](https://github.com/rails/arel)
and generating the Node manually. We would use the following to
accompish this:
@@ -69,9 +88,7 @@ User.where(predicate)
The ALL version of this same predicate can be generated by swap `'ANY'`
for `'ALL'` in the named function.
-## INET/CIDR
-
-### `<<` -- Contained within operator
+## INET/CIDR Queries
PostgreSQL defines the `<<`, or contained within operator for INET and
CIDR datatypes. The `<<` operator returns `t` (true) if a INET or CIDR
@@ -85,13 +102,37 @@ inet '192.168.1.6' << inet '192.168.1.0/24'
-- t
```
+In addition to contained within, there is also:
+
+ * `<<=` - Contained within or equals
+ * `>>` - Contains
+ * `>>=` - Contains or equals
+
+Postgres\_ext extends the `ActiveRecord::Relation.where` method similar
+to the Rails 4.0 not clause. The easiest way to make a overlap query
+would be:
+
+```ruby
+User.where.contained_within(:ip => '192.168.1.1/24')
+User.where.contained_within_or_equals(:ip => '192.168.1.1/24')
+User.where.contains(:ip => '192.168.1.14')
+User.where.contains_or_equals(:ip => '192.168.1.14')
+```
+
Postgres\_ext defines `contained_within`, an [Arel](https://github.com/rails/arel)
-predicate for the `<<` operator.
+predicate for the `<<` operator. This is utilized by the
+methods above.
```ruby
user_arel = User.arel_table
# Execute the query
-User.where(user_arel[:ip_address].contained_witin('127.0.0.1/24'))
+User.where(user_arel[:ip_address].contained_within('127.0.0.1/24'))
# => SELECT \"users\".* FROM \"users\" WHERE \"users\".\"ip_address\" << '127.0.0.1/24'
+User.where(user_arel[:ip_address].contained_within_or_equals('127.0.0.1/24'))
+# => SELECT \"users\".* FROM \"users\" WHERE \"users\".\"ip_address\" <<= '127.0.0.1/24'
+User.where(user_arel[:ip_address].contains('127.0.0.1'))
+# => SELECT \"users\".* FROM \"users\" WHERE \"users\".\"ip_address\" >> '127.0.0.1'
+User.where(user_arel[:ip_address].contains_or_equals('127.0.0.1'))
+# => SELECT \"users\".* FROM \"users\" WHERE \"users\".\"ip_address\" >>= '127.0.0.1'
```

0 comments on commit e1ee164

Please sign in to comment.