Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Adds querying docs
[ci skip]
  • Loading branch information
danmcclain committed Feb 8, 2013
1 parent 8376047 commit e1ee164
Showing 1 changed file with 48 additions and 7 deletions.
55 changes: 48 additions & 7 deletions docs/querying.md
@@ -1,7 +1,7 @@
# Querying PostgreSQL datatypes # Querying PostgreSQL datatypes


* [Arrays](#arrays) * [Arrays](#arrays)
* [INET/CIDR](#inetcidr) * [INET/CIDR](#inetcidr-queries)


## Arrays ## Arrays


Expand All @@ -22,8 +22,17 @@ ARRAY[1,2,3] && ARRAY[3,5,6]
-- t -- 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) 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 ```ruby
user_arel = User.arel_table user_arel = User.arel_table
Expand Down Expand Up @@ -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 instead of the left, because we have to call the `ANY` function on that
column. 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) We can generate the above query using [Arel](https://github.com/rails/arel)
and generating the Node manually. We would use the following to and generating the Node manually. We would use the following to
accompish this: accompish this:
Expand All @@ -69,9 +88,7 @@ User.where(predicate)
The ALL version of this same predicate can be generated by swap `'ANY'` The ALL version of this same predicate can be generated by swap `'ANY'`
for `'ALL'` in the named function. for `'ALL'` in the named function.


## INET/CIDR ## INET/CIDR Queries

### `<<` -- Contained within operator


PostgreSQL defines the `<<`, or contained within operator for INET and PostgreSQL defines the `<<`, or contained within operator for INET and
CIDR datatypes. The `<<` operator returns `t` (true) if a INET or CIDR CIDR datatypes. The `<<` operator returns `t` (true) if a INET or CIDR
Expand All @@ -85,13 +102,37 @@ inet '192.168.1.6' << inet '192.168.1.0/24'
-- t -- 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) 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 ```ruby
user_arel = User.arel_table user_arel = User.arel_table


# Execute the query # 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' # => 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.