module OccamsRecord
Main entry point for using OccamsRecord
.
Constants
- Measurement
- Measurements
- VERSION
Library version
Public Class Methods
Starts building a OccamsRecord::Query
. Pass it a scope from any of ActiveRecord's query builder methods or associations. If you want to eager loaded associations, do NOT use ActiveRecord for it. Instead use OccamsRecord::Query#eager_load
. Finally, call `run` (or any Enumerable method) to run the query and get back an array of objects.
results = OccamsRecord. query(Widget.order("name")). eager_load(:category). eager_load(:order_items, ->(q) { q.select("widget_id, order_id") }) { eager_load(:orders) { eager_load(:customer, ->(q) { q.select("name") }) } }. run
@param scope [ActiveRecord::Relation] @param use [Module] optional Module to include in the result class @param query_logger [Array] (optional) an array into which all queries will be inserted for logging/debug purposes @return [OccamsRecord::Query]
# File lib/occams-record/query.rb, line 25 def self.query(scope, use: nil, query_logger: nil) Query.new(scope, use: use, query_logger: query_logger) end
Starts building a OccamsRecord::RawQuery
. Pass it a raw SQL statement, optionally followed by a Hash of binds. While this doesn't offer an additional performance boost, it's a nice way to write safe, complicated SQL by hand while also supporting eager loading.
results = OccamsRecord.sql(" SELECT * FROM widgets WHERE category_id = %{cat_id} ", { cat_id: 5 }).run
If you want to do eager loading, you must first the define a model to pull the associations from (unless you're using the raw SQL eager loaders `eager_load_one` or `eager_load_many`).
results = OccamsRecord. sql(" SELECT * FROM widgets WHERE category_id IN (%{cat_ids}) ", { cat_ids: [5, 10] }). model(Widget). eager_load(:category). run
NOTE To use find_each/find_in_batches, your SQL string must include 'LIMIT %{batch_limit} OFFSET %{batch_offset}', and an ORDER BY is strongly recomended. OccamsRecord
will provide the bind values for you.
NOTE There is variation of the types of values returned (e.g. a Date object vs a date string) depending on the database and ActiveRecord version being used:
Postgres always returns native Ruby types.
SQLite will return native types for the following: integers, floats, string/text. For booleans it will return 0|1 for AR 6+, and “t|f” for AR 5-. Dates and times will be ISO8601 formatted strings. It is possible to coerce the SQLite adapter into returning native types for everything IF they're columns of a table that you have an AR model for. e.g. if you're selecting from the widgets, table: `OccamsRecord.sql(“…”).model(Widget)…`.
MySQL ?
@param sql [String] The SELECT statement to run. Binds should use Ruby's named string substitution. @param binds [Hash] Bind values (Symbol keys) @param use [Array<Module>] optional Module to include in the result class (single or array) @param query_logger [Array] (optional) an array into which all queries will be inserted for logging/debug purposes @return [OccamsRecord::RawQuery]
# File lib/occams-record/raw_query.rb, line 50 def self.sql(sql, binds, use: nil, query_logger: nil) RawQuery.new(sql, binds, use: use, query_logger: nil) end