Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Minor doc updates

  • Loading branch information...
commit 252f997ef6bddb4c4e901f149bc4209c226a6ff6 1 parent fa6b093
@jeremyevans authored
View
71 doc/cheat_sheet.rdoc
@@ -48,8 +48,8 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
== Retrieve rows
dataset.each{|r| p r}
- dataset.all #=> [{...}, {...}, ...]
- dataset.first
+ dataset.all # => [{...}, {...}, ...]
+ dataset.first # => {...}
== Update/Delete rows
@@ -66,47 +66,51 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
== Filtering (see also doc/dataset_filtering.rdoc)
+=== Equality
+
dataset.filter(:name => 'abc')
dataset.filter('name = ?', 'abc')
- dataset.filter{|o| o.value > 100}
- dataset.exclude{|o| o.value <= 100}
+=== Inequality
+
+ dataset.filter{value > 100}
+ dataset.exclude{value <= 100}
+
+=== Inclusion
dataset.filter(:value => 50..100)
- dataset.where{|o| (o.value >= 50) & (o.value <= 100)}
+ dataset.where{(value >= 50) & (value <= 100)}
dataset.where('value IN ?', [50,75,100])
dataset.where(:value=>[50,75,100])
- dataset.filter(:name => 'abc').first
- dataset[:name => 'abc']
+ dataset.where(:id=>other_dataset.select(:other_id))
- dataset.where('price > (SELECT avg(price) + 100 FROM table)')
- dataset.filter{|o| o.price > dataset.select(o.avg(price) + 100)}
+=== Subselects as scalar values
-=== Advanced filtering using ruby expressions
+ dataset.where('price > (SELECT avg(price) + 100 FROM table)')
+ dataset.filter{price > dataset.select(avg(price) + 100)}
- DB[:items].filter{|o| o.price < 100}.sql
- #=> "SELECT * FROM items WHERE (price < 100)"
+=== LIKE/Regexp
- DB[:items].filter(:name.like('AL%')).sql
- #=> "SELECT * FROM items WHERE (name LIKE 'AL%')"
+ DB[:items].filter(:name.like('AL%'))
+ DB[:items].filter(:name => /^AL/)
-There's support for nested expressions with AND, OR and NOT:
+=== AND/OR/NOT
- DB[:items].filter{|o| (o.x > 5) & (o.y > 10)}.sql
- #=> "SELECT * FROM items WHERE ((x > 5) AND (y > 10))"
+ DB[:items].filter{(x > 5) & (y > 10)}.sql
+ # SELECT * FROM items WHERE ((x > 5) AND (y > 10))
DB[:items].filter({:x => 1, :y => 2}.sql_or & ~{:z => 3}).sql
- #=> "SELECT * FROM items WHERE (((x = 1) OR (y = 2)) AND (z != 3))"
+ # SELECT * FROM items WHERE (((x = 1) OR (y = 2)) AND (z != 3))
-You can use arithmetic operators and specify SQL functions:
+=== Mathematical operators
DB[:items].filter((:x + :y) > :z).sql
- #=> "SELECT * FROM items WHERE ((x + y) > z)"
+ # SELECT * FROM items WHERE ((x + y) > z)
- DB[:items].filter{|o| :price - 100 < o.avg(:price)}.sql
- #=> "SELECT * FROM items WHERE ((price - 100) < avg(price))"
+ DB[:items].filter{price - 100 < avg(price)}.sql
+ # SELECT * FROM items WHERE ((price - 100) < avg(price))
== Ordering
@@ -114,7 +118,7 @@ You can use arithmetic operators and specify SQL functions:
dataset.reverse_order(:kind)
dataset.order(:kind.desc, :name)
-== Row ranges
+== Limit/Offset
dataset.limit(30) # LIMIT 30
dataset.limit(30, 10) # LIMIT 30 OFFSET 10
@@ -122,12 +126,12 @@ You can use arithmetic operators and specify SQL functions:
== Joins
DB[:items].left_outer_join(:categories, :id => :category_id).sql
- #=> "SELECT * FROM items LEFT OUTER JOIN categories ON categories.id = items.category_id"
+ # SELECT * FROM items LEFT OUTER JOIN categories ON categories.id = items.category_id
DB[:items].join(:categories, :id => :category_id).join(:groups, :id => :items__group_id)
- #=> "SELECT * FROM items INNER JOIN categories ON categories.id = items.category_id INNER JOIN groups ON groups.id = items.group_id"
+ # SELECT * FROM items INNER JOIN categories ON categories.id = items.category_id INNER JOIN groups ON groups.id = items.group_id
-== Summarizing
+== Aggregate functions methods
dataset.count #=> record count
dataset.max(:price)
@@ -135,6 +139,7 @@ You can use arithmetic operators and specify SQL functions:
dataset.avg(:price)
dataset.sum(:stock)
+ dataset.group_and_count(:category)
dataset.group(:category).select(:category, :AVG.sql_function(:price))
== SQL Functions / Literals
@@ -150,11 +155,11 @@ You can use arithmetic operators and specify SQL functions:
DB.create_table :items do
primary_key :id
String :name, :unique => true, :null => false
- boolean :active, :default => true
+ TrueClass :active, :default => true
foreign_key :category_id, :categories
- Time :created_at
+ DateTime :created_at
- index :grade
+ index :created_at
end
DB.drop_table :items
@@ -169,7 +174,7 @@ You can use arithmetic operators and specify SQL functions:
DB[:items].select(:name.as(:item_name))
DB[:items].select(:name___item_name)
DB[:items___items_table].select(:items_table__name___item_name)
- # => "SELECT items_table.name AS item_name FROM items AS items_table"
+ # SELECT items_table.name AS item_name FROM items AS items_table
== Transactions
@@ -211,8 +216,8 @@ Savepoints can be used if the database supports it:
== Miscellaneous:
- dataset.sql #=> "SELECT * FROM items"
- dataset.delete_sql #=> "DELETE FROM items"
- dataset.where(:name => 'sequel').exists #=> "EXISTS ( SELECT * FROM items WHERE name = 'sequel' )"
+ dataset.sql # "SELECT * FROM items"
+ dataset.delete_sql # "DELETE FROM items"
+ dataset.where(:name => 'sequel').exists # "EXISTS ( SELECT * FROM items WHERE name = 'sequel' )"
dataset.columns #=> array of columns in the result set, does a SELECT
DB.schema(:items) => [[:id, {:type=>:integer, ...}], [:name, {:type=>:string, ...}], ...]
View
23 doc/dataset_filtering.rdoc
@@ -1,6 +1,6 @@
= Dataset Filtering
-Sequel offers unparalleled flexibility when it comes to filtering records. You can specify your conditions as a custom string, as a string with parameters, as a hash of values to compare against, or as ruby code that Sequel translates into SQL expressions.
+Sequel is very flexibile when it comes to filtering records. You can specify your conditions as a custom string, as a string with parameters, as a hash of values to compare against, or as ruby code that Sequel translates into SQL expressions.
== Filtering using a custom filter string
@@ -14,12 +14,21 @@ In order to prevent SQL injection, you can replace literal values with question
items.filter('category = ?', 'ruby').sql
#=> "SELECT * FROM items WHERE category = 'ruby'"
+You can also use placeholders with :placeholder and a hash of placeholder values:
+
+ items.filter('category = :category', :category=>'ruby').sql
+ #=> "SELECT * FROM items WHERE category = 'ruby'"
+
=== Specifying SQL functions
-Sequel also allows you to specify functions by using the Symbol#sql_function method (and the Symbol#[] method on ruby 1.8):
+Sequel also allows you to specify functions by using the Symbol#sql_function method:
items.literal(:avg.sql_function(:price)) #=> "avg(price)"
+If you are specifying a filter/selection/order, you can use a virtual row block:
+
+ items.select{avg(price)}
+
== Filtering using a hash
If you just need to compare records against values, you can supply a hash:
@@ -57,7 +66,7 @@ Sequel allows you to use ruby expressions directly in the call to filter:
items.filter(:price * 2 < 50).sql
#=> "SELECT * FROM items WHERE ((price * 2) < 50)
-This works for the standard inequality and arithmetic operators (though you can't use the inequality operators directly on a symbol in ruby 1.9):
+This works for the standard inequality and arithmetic operators (though you can't use the inequality operators directly on a symbol):
items.filter(:price + 100 < 200).sql
#=> "SELECT * FROM items WHERE ((price + 100) < 200)
@@ -94,7 +103,7 @@ This works with other hash values, such as arrays and ranges:
=== Negating conditions
-You can use the negation operator (~) in most cases:
+You can use the inversion operator (~) in most cases:
items.filter(~{:category => 'ruby'}).sql
#=> "SELECT * FROM items WHERE (category != 'ruby')"
@@ -109,12 +118,12 @@ You can use the negation operator (~) in most cases:
You can also compare against other columns:
- items.filter{|o| o.credit > :debit}.sql
+ items.filter{credit > debit}.sql
#=> "SELECT * FROM items WHERE (credit > debit)
Or against SQL functions:
- items.filter{|o| :price - 100 < o.max(:price)}.sql
+ items.filter{price - 100 < max(price)}.sql
#=> "SELECT * FROM items WHERE ((price - 100) < max(price))"
== String search functions
@@ -155,4 +164,4 @@ One of the best features of Sequel is the ability to use datasets as sub-queries
consumers.filter(:id => refs).sql
#=> "SELECT * FROM consumers WHERE (id IN (SELECT consumer_id FROM consumer_refs WHERE logged_in))"
-Note that if you compare against a sub-query, you must select a single column in the sub-query.
+Note that if you are checking for the inclusion of a single column in a subselect, the subselect should only select a single column.
View
2  doc/sharding.rdoc
@@ -4,7 +4,7 @@ Sequel has support for read only slave databases
with a writable master database, as well as database sharding (where you can
pick a server to use for a given dataset). Support for both
features is database independent, and should work for all database adapters
-included with Sequel.
+that ship with Sequel.
== The :servers Database option
Please sign in to comment.
Something went wrong with that request. Please try again.