class

PgORM::Collection(T)

Inherits PgORM::Pagination < PgORM::Query::Cache < PgORM::Query::Methods < Enumerable < Reference < Object

Build Database Queries.

A Collection is immutable: all methods will return a copy of the previous Collection with the added constraint(s). For example:

users = User.select(:id, :name).where(group_id: 2)

Termination methods such as #find_by, or #take will explicitly execute a SQL request against the database and load one record.

first_user = users.order(:name).take
# => SELECT "id", "name"
#    FROM "users"
#    WHERE "group_id" = 2
#    ORDER BY "name" ASC
#    LIMIT 1;

Termination methods such as #to_a or #each will execute a SQL request then cache loaded records into the Collection, so further accesses won't re-execute the SQL request. Some methods such as #first or #size will leverage this cache when it's available.

users.to_a
# => SELECT "id", "name" FROM "users" WHERE "group_id" = 2;

When specifying column names you should always use a Symbol, so they'll be properly quoted for the database server. In many cases you can specify raw SQL statements using a String. For example:

users = User.where("LENGTH(name) > $0", 10)
# => SELECT * FROM "users" WHERE LENGTH(name) > 10;

users = User.order("LENGTH(name) DESC")
# => SELECT * FROM "users" ORDER BY LENGTH(name) DESC;

count = User.count("LENGTH(name)", distinct: true)
# => SELECT COUNT(DISTINCT LENGTH(name)) FROM "users";

Instance methods

explain

Returns the query execution plan (useful for optimization) Note: This only works for SELECT queries (Collection is for queries, not mutations)

in_groups_of(size : Int, filled_up_with : U = nil, reuse = false, &) forall U

Yields a block with the chunks in the given size.

[1, 2, 4].in_groups_of(2, 0) { |e| p e.sum }
# => 3
# => 4

By default, a new array is created and yielded for each group.

If reuse is given, the array can be reused
If reuse is an Array, this array will be reused
If reuse is truthy, the method will create a new array and reuse it.

This can be used to prevent many memory allocations when each slice of interest is to be used in a read-only fashion.

search(query : String, columns : Array(String), config : String = "english") : self

Convenience method for full-text search

search(query : String, *columns : Symbol, config : String = "english") : self

Overload: Accepts Symbol columns

search(query : String, *columns : String, config : String = "english") : self

Overload: Accepts String columns

search_phrase(phrase : String, columns : Array(String), config : String = "english") : self

Convenience method for phrase search

search_phrase(phrase : String, *columns : Symbol, config : String = "english") : self

Overload: Accepts Symbol columns

search_phrase(phrase : String, *columns : String, config : String = "english") : self

Overload: Accepts String columns

search_plain(text : String, columns : Array(String), config : String = "english") : self

Convenience method for plain text search

search_plain(text : String, *columns : Symbol, config : String = "english") : self

Overload: Accepts Symbol columns

search_plain(text : String, *columns : String, config : String = "english") : self

Overload: Accepts String columns

search_prefix(prefix : String, columns : Array(String), config : String = "english") : self

Convenience method for prefix search

search_prefix(prefix : String, *columns : Symbol, config : String = "english") : self

Overload: Accepts Symbol columns

search_prefix(prefix : String, *columns : String, config : String = "english") : self

Overload: Accepts String columns

search_proximity(word1 : String, word2 : String, distance : Int32, columns : Array(String), config : String = "english") : self

Convenience method for proximity search

search_proximity(word1 : String, word2 : String, distance : Int32, *columns : Symbol, config : String = "english") : self

Overload: Accepts Symbol columns

search_proximity(word1 : String, word2 : String, distance : Int32, *columns : String, config : String = "english") : self

Overload: Accepts String columns

search_ranked(query : String, columns : Array(String), config : String = "english", rank_normalization : Int32 | Nil = nil, rank_function : FullTextSearch::RankFunction = FullTextSearch::RankFunction::Rank) : self

Convenience method for ranked full-text search

search_ranked(query : String, *columns : Symbol, config : String = "english", rank_normalization : Int32 | Nil = nil, rank_function : FullTextSearch::RankFunction = FullTextSearch::RankFunction::Rank) : self

Overload: Accepts Symbol columns

search_ranked(query : String, *columns : String, config : String = "english", rank_normalization : Int32 | Nil = nil, rank_function : FullTextSearch::RankFunction = FullTextSearch::RankFunction::Rank) : self

Overload: Accepts String columns

search_ranked_weighted(query : String, weighted_columns : Hash(String, FullTextSearch::Weight), config : String = "english", rank_normalization : Int32 | Nil = nil, rank_function : FullTextSearch::RankFunction = FullTextSearch::RankFunction::Rank) : self

Convenience method for ranked weighted search

search_ranked_weighted(query : String, weighted_columns : Hash(Symbol, FullTextSearch::Weight), config : String = "english", rank_normalization : Int32 | Nil = nil, rank_function : FullTextSearch::RankFunction = FullTextSearch::RankFunction::Rank) : self

Overload: Accepts Symbol keys

search_vector(query : String, vector_column : String, config : String = "english") : self

Convenience method for searching pre-computed tsvector column

search_vector(query : String, vector_column : Symbol, config : String = "english") : self

Overload: Accepts Symbol for vector column

search_vector_plain(text : String, vector_column : String, config : String = "english") : self

Convenience method for searching pre-computed tsvector column with plain text

search_vector_plain(text : String, vector_column : Symbol, config : String = "english") : self

Overload: Accepts Symbol for vector column

search_vector_ranked(query : String, vector_column : String, config : String = "english", rank_normalization : Int32 | Nil = nil, rank_function : FullTextSearch::RankFunction = FullTextSearch::RankFunction::Rank) : self

Convenience method for searching pre-computed tsvector column with ranking

search_vector_ranked(query : String, vector_column : Symbol, config : String = "english", rank_normalization : Int32 | Nil = nil, rank_function : FullTextSearch::RankFunction = FullTextSearch::RankFunction::Rank) : self

Overload: Accepts Symbol for vector column

search_weighted(query : String, weighted_columns : Hash(String, FullTextSearch::Weight), config : String = "english") : self

Convenience method for weighted full-text search

search_weighted(query : String, weighted_columns : Hash(Symbol, FullTextSearch::Weight), config : String = "english") : self

Overload: Accepts Symbol keys