Module Hoodoo::ActiveRecord::Finder::ClassMethods

“Polymorphic” find - support for finding a model by fields other than just :id, based on a single unique identifier. Use acquire just like you'd use find_by_id and only bother with it if you support finding a resource instance by id and one or more other model fields. Otherwise, just use find_by_id.

In the model, you declare the list of fields in addition to id by calling acquire_with thus:

class SomeModel < ActiveRecord::Base
  include Hoodoo::ActiveRecord::Finder
  acquire_with ... # <list-of-other-fields>
end

For example, maybe you allow some resource to be looked up by fields id or code, both of which are independently unique sets. Since id is always automatically included, you only need to do this:

class SomeModel < ActiveRecord::Base
  include Hoodoo::ActiveRecord::Finder
  acquire_with :code
end

Then, in a resource's implementation:

def show( context )
  found = SomeModel.acquire( context.request.ident )
  return context.response.not_found( context.request.ident ) if found.nil?

  # ...map 'found' to whatever resource you're representing,
  # e.g. via a Hoodoo::Presenters::Base subclass with resource
  # schema and the subclass's Hoodoo::Presenters::Base::render
  # call, then...

  context.response.set_resource( resource_representation_of_found )
end

There is nothing magic “under the hood” - Hoodoo just tries to find records with a value matching the incoming identifier for each of the fields in turn. It starts with id then runs through any other fields in the order given through acquire_with.

This can only be used if your searched fields are strings in the database. This includes, for example, the id column; Hoodoo usually expects to be a string field holding a 32-character UUID. If any of the fields contain non-string types, attempts to use the acquire mechanism (or a related one) may result in database errors due to type mismatches, depending upon the database engine in use.

In more complex scenarious, you can just call acquire at the end of any chain of AREL queries just as you would call ActiveRecord's own find_by_id method, e.g.:

SomeModel.where( :foo => :bar ).acquire( context.request.ident )

Usually for convenience you should use acquire_in! or #acquire_in instead, or only call acquire with (say) a secure scope via for example a call to Hoodoo::ActiveRecord::Secure::ClassMethods#secure. Other scopes may be needed depending on the mixins your model uses.

ident

The value to search for in the fields (attributes) specified via acquire_with, matched using calls to where( attr => ident ).

Returns a found model instance or nil for no match.

Implicily secure, translated, dated etc. etc. version of acquire, according to which modules are mixed into your model class. Uses scoped_in to obtain a base scope in which to operate, so it is “mixin aware” and incorporates other Hoodoo extensions within the wider scope chain. See that method's documentation for more information.

For example, if you are using or at some point intend to mix in and use the mechanism described by the likes of Hoodoo::ActiveRecord::Secure::ClassMethods#secure, call here as a convenience to both obtain a secure context and find a record (with or without additional find-by fields other than id) in one go. Building on the example from Hoodoo::ActiveRecord::Secure::ClassMethods#secure, we might have an Audit model as follows:

class Audit < ActiveRecord::Base
  include Hoodoo::ActiveRecord::Secure

  secure_with( {
    :creating_caller_uuid => :authorised_caller_uuid
  } )

  # Plus perhaps a call to "acquire_with"
end

Then, in a resource's implementation:

def show( context )
  found = SomeModel.acquire_in( context )
  return context.response.not_found( context.request.ident ) if found.nil?

  # ...map 'found' to whatever resource you're representing,
  # e.g. via a Hoodoo::Presenters::Base subclass with resource
  # schema and the subclass's Hoodoo::Presenters::Base::render
  # call, then...

  context.response.set_resource( resource_representation_of_found )
end

The value of found will be acquired within the secure context determined by the prevailing call context (and its session), so the data it finds is inherently correctly scoped - provided your model's Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with call describes things correctly.

This method is for convenience and safety - you can't accidentally forget the secure scope:

SomeModel.secure( context ).acquire( context.request.ident )

# ...has the same result as...

SomeModel.acquire_in( context )

The same applies to forgetting dated scopes, translated scopes, or anything else that scoped_in might include for you.

An even higher-level method, taking care of error handling as well, is acquire_in!. You may prefer to call this higher level interface if you don't object to the way it modifies context.

Parameters:

context

Hoodoo::Services::Context instance describing a call context. This is typically a value passed to one of the Hoodoo::Services::Implementation instance methods that a resource subclass implements.

See also:

• #acquire_in!

• Hoodoo::Services::Response#not_found

• Hoodoo::Services::Response#contemporary_exists

Returns a found model instance or nil for no match / on error.

A higher level equivalent of acquire_in in which the given context will be updated with error information if the requested item cannot be found. Although modifying the passed-in context may be considered an unclean pattern, it does allow extensions to that mechanism. For example, in the presence of the Hoodoo::ActiveRecord::Dated or Hoodoo::ActiveRecord::ManuallyDated modules, an additional error entry of generic.contemporary_exists will be added if conditions warrant it.

At the time of writing only this and/or generic.not_found can be added, but in future other mixin modules may cause other additions, making preferential use of this method over acquire_in a good way to future-proof against such changes.

To be sure that these additions work, always include this module before any others (unless documentation indicates a differing inclusion order requirement), so that the dating module is able to detect the presence of this Finder module and enable the extensions.

Parameters:

context

Hoodoo::Services::Context instance describing a call context. This is typically a value passed to one of the Hoodoo::Services::Implementation instance methods that a resource subclass implements.

See also:

• #acquire_in

• Hoodoo::Services::Response#not_found

• Hoodoo::Services::Response#contemporary_exists

Returns a found model instance or nil for no match / on error, wherein context will have been updated with error details.

Example, following on from those for acquire_in:

def show( context )
  resource = SomeModel.acquire_in!( context )
  return if context.response.halt_processing? # Or just use 'if resource.nil?'

  # ...else render...
end

Describe the list of model fields in addition to id which are to be used to “find-by-identifier” through calls acquire, acquire_in and acquire_in!. See those methods for more details.

Fields will be searched in the order listed. If duplicate items are present, the first occurrence is kept and the rest are removed.

*args

One or more field names as Strings or Symbols.

See also:

• acquired_with

• acquire_with_id_substitute

The acquire_with method allows methods like acquire, acquire_in and acquire_in! to transparently find a record based on one or more columns in the database. The columns (and corresponding model attributes) specified through a call to acquire_with will normally be used in addition to a lookup on the id column, but in rare circumstances you might need to bypass that and use an entirely different field. This is distinct from the ActiveRecord-level concept of the model's primary key column.

To permanently change the use of the id attribute as the first search parameter in acquire, acquire_in and acquire_in! by modifying the behaviour of acquisition_scope, call here and pass in the new attribute name.

attr

Attribute name as a Symbol or String to use instead of id, as a default mandatory column in acquisition_scope.

Return the list of model fields in addition to id which are being used to “find-by-identifier” through calls to acquire, acquire_in and acquire_in!. The returned Array contains de-duplicated String values only.

See also:

• acquire_with

• acquire_with_id_substitute

Back-end to acquire and therefore, in turn, acquire_in and acquire_in!. Returns an ActiveRecord::Relation instance which scopes the search for a record by id and across any other columns specified by acquire_with, via SQL OR.

If you need to change the use of attribute id, specify a different attribute with acquire_with_id_substitute. In that case, the given attribute is searched for instead of id; either way, a default starting attribute will be used in scope in addition to any extra fields specified using acquire_with.

Normally such a scope could only ever return a single record based on an assuption of uniqueness constraints around columns which one might use in an equivalent of a find call. This scope is often chained on top of a wider listing scope provided by scoped_in to create a fully context-aware, secure, dated, translated etc. query. It is possible however that the chosen ident value might not resolve to a single unique record depending on how your data works and you may need to manually apply additional constraints to the returned ActiveRecord::Relation instance.

Given some scope - typically that obtained from a prior call to list or list_in, with possibly other query modifiers too - return the total dataset size. This is basically a COUNT operation, but run without offset or limit considerations (ignoring pagination).

This is particularly useful if you are calling Hoodoo::Services::Response#set_resources and want to fill in its dataset_size parameter.

This method is related to estimated_count, so read the documentation for that as an introduction first.

In estimated_count, a PostgreSQL example is given. Continuing with this, we could implement an estimation mechanism via Hoodoo's fast counter with something like the approach described here:

• wiki.postgresql.org/wiki/Count_estimate

• www.verygoodindicators.com/blog/2015/04/07/faster-count-queries/

First, you would need a migration in your service to implement the estimation method as a PLPGSQL function:

class CreateFastCountFunction < ActiveRecord::Migration
  def up
    execute <<-SQL
      CREATE FUNCTION estimated_count(query text) RETURNS integer AS
      $func$
      DECLARE
          rec   record;
          rows  integer;
      BEGIN
          FOR rec IN EXECUTE 'EXPLAIN ' || query LOOP
              rows := substring(rec."QUERY PLAN" FROM ' rows=([[:digit:]]+)');
              EXIT WHEN rows IS NOT NULL;
          END LOOP;

          RETURN rows;
      END
      $func$ LANGUAGE plpgsql;
    SQL
  end

  def down
    execute "DROP FUNCTION estimated_count(query text);"
  end
end

This takes arbitrary query text so should cope with pretty much any kind of ActiveRecord query chain and resulting SQL. Run the database migration, then define a Proc which calls the new function:

counter = Proc.new do | sql |
  begin
    escaped_sql = sql.gsub( "'", "''" )
    ActiveRecord::Base.connection.execute(
      "SELECT estimated_count('#{ escaped_sql }')"
    ).first[ 'estimated_count' ].to_i
  rescue
    nil
end

Suppose we have a model called Purchase; next tell this model to use the above Proc for fast counting and use it:

Purchase.estimate_counts_with( counter )

Purchase.estimated_count()
# => An integer; and you can use scope chains, just like #count:
Purchase.where(...conditions...).estimated_count()
# => An integer

A real-life example showing how running PostgreSQL's ANALYZE command can make a difference:

[1] pry(main)> Purchase.estimated_count
=> 68
[2] pry(main)> Purchase.count
=> 76
[3] pry(main)> ActiveRecord::Base.connection.execute( 'ANALYZE' )
=> #<PG::Result:0x007f89b62cdcc8 status=PGRES_COMMAND_OK ntuples=0 nfields=0 cmd_tuples=0>
[4] pry(main)> Purchase.estimated_count
=> 76

Parameters:

proc

The Proc to call. It must accept one parameter, which is the SQL query for which the count is to be run, as a String. It must evaluate to an Integer estimation, or nil if it is not able to provide any/useful estimations, in its opinion.

Pass nil to remove the custom counter method and restore default behaviour.

In absence of other configuration, this method just calls through to Active Record's count, but you can override the counting mechanism with a Proc which gets called to do the counting instead.

The use case is for databases where counting may be slow for some reason. For example, in PostgreSQL 9, the MVCC model means that big tables under heavy write load may take extremely long times to be counted as a full sequential row scan gets activated. In the case of PostgreSQL, there's an estimation available as an alternative; its accuracy depends on how often the ANALYZE command is run, but at least its execution speed is always very small.

The estimated_dataset_size method runs through here for counting so you need to ensure that your count estimation method can cope with whatever queries that might arise from the scope chains involved in instances of the model at hand, within the service code that uses that model.

Specify a count estimation Proc with estimate_counts_with. Such blocks are permitted to return nil if the estimation is considered to be wildly wrong or unobtainable; in that case, the returned value for the estimated count will be nil too.

As dataset_size, but allows a configurable counting back-end via estimated_count and estimate_counts_with. This method is intended to be used for fast count estimations, usually for performance reasons if an accurate dataset_size count is too slow to compute.

As search_with, but used in where.not queries.

IMPORTANT: Beware null column values and filters given SQL's strange behaviour with such things. The search helpers in Hoodoo::ActiveRecord::Finder::SearchHelper class will work as logically expected (“field not 'foo'” will find fields with a null value), though if you're expecting SQL-like behaviour it might come as a surprise! Using ...AND field IS NOT NULL in queries for filter_with tends to work reasonably when the query is negated for filter use via ...NOT(...).... Examining the implementation of Hoodoo::ActiveRecord::Finder::SearchHelper may help if confused.

See also:

• en.wikipedia.org/wiki/Null_(SQL)

map

As search_with.

Generate an ActiveRecord::Relation instance which can be used to count, retrieve or further refine a list of model instances from the database.

Usually for convenience you should use list_in instead, or only call acquire with (say) a secure scope via for example a call to Hoodoo::ActiveRecord::Secure::ClassMethods#secure. An example of this second option is shown below.

Pass a Hoodoo::Services::Request::ListParameters instance, e.g. via the Hoodoo::Services::Context instance passed to resource endpoint implementations and accessor context.request.list. It takes into account the list offset, limit, sort key and sort direction automatically. In addition, it can do simple search and filter operations if search and filter mappings are set up via search_with and filter_with.

For exampe, in a simple case where a model can be listed without any unusual constraints, we might do this:

class SomeModel < ActiveRecord::Base
  include Hoodoo::ActiveRecord::Finder

  search_with # ...<field-to-search-info mapping>
  # ...and/or...
  filter_with # ...<field-to-search-info mapping>
end

# ...then, in the resource implementation...

def list( context )
  finder = SomeModel.list( context.request.list )
  results = finder.all.map do | item |
    # ...map database objects to response objects...
  end
  context.response.set_resources( results, finder.dataset_size )
end

Note the use of helper method dataset_size to count the total amount of results in the dataset without pagination. A resource may alternatively choose to use estimated_dataset_size for a fast count estimation, or neither (though this is generally not recommended) or

• permissible but unusual - include both.

  context.response.set_resources( results, nil, finder.estimated_dataset_size )
  

The service middleware enforces sane values for things like list offsets, sort keys and so-on according to service interface definitions, so if using the middleware you don't need to do any extra checking yourself.

Since the returned object is just a relation, adding further constraints is easy - call things like where, group and so-on as normal. You can also list in a secure context via the included Hoodoo::ActiveRecord::Secure::ClassMethods#secure, assuming appropriate data is set in the model via Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with:

def list( context )
  finder = SomeModel.secure( context ).list( context.request.list )
  finder = finder.where( :additional_filter => 'some value' )
  results = finder.all.map do | item |
    # ...map database objects to response objects...
  end
  context.response.set_resources( results, finder.dataset_size )
end

Since it's just a chained scope, you can call in any order:

SomeModel.secure( context ).list( context.request.list )

# ...has the same result as...

SomeModel.list( context.request.list ).secure( context )

Any of the ActiveRecord::QueryMethods can be called on the returned value. See:

api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html

list_parameters

Hoodoo::Services::Request::ListParameters instance, typically obtained from the Hoodoo::Services::Context instance passed to a service implementation in Hoodoo::Services::Implementation#list, via context.request.list (i.e. Hoodoo::Services::Context#request / Hoodoo::Services::Request#list).

Deprecated interface replaced by filter_with (this is an alias).

map

Passed to filter_with.

Deprecated interface replaced by list (this is an alias).

list_parameters

Passed to list.

Implicily secure, translated, dated etc. etc. version of list, according to which modules are mixed into your model class. See scoped_in to see the list of things that get included in the scope according to the mixins that are in use.

For example, if you have included Hoodoo::ActiveRecord::Secure, this method provides you with an implicitly secure query. Read the documentation on acquire_in versus acquire for information on the use of secure scopes; as with acquire_in and the “Secure” mixin, this method becomes for convenience and safety - you can't accidentally forget the secure scope:

SomeModel.secure( context ).list( context.request.list )

# ...has the same result as...

SomeModel.list_in( context )

The same applies to forgetting dated scopes, translated scopes, or anything else that scoped_in might include for you.

context

Hoodoo::Services::Context instance describing a call context. This is typically a value passed to one of the Hoodoo::Services::Implementation instance methods that a resource subclass implements.

Returns a secure list scope, for either further modification with query methods like where or fetching from the database with all.

Deprecated interface replaced by search_with (this is an alias).

map

Passed to search_with.

Deprecated interface replaced by acquire. Instead of:

Model.polymorphic_find( foo, ident )

…use:

foo.acquire( ident )

This implementation is for legacy support and just calls through to acquire.

finder

acquire is called on this.

ident

Passed to acquire.

Returns a found model instance or nil for no match.

Deprecated interface replaced by acquire_with (this is an alias).

*args

Passed to acquire_with.

Returns an ActiveRecord::Relation instance representing a primitive base scope that includes various context-related aspects according to the prevailing mixins included by “this” class, if any - e.g. security, dating and/or translation.

See Hoodoo::ActiveRecord::Support#full_scope_for to see the list of things that get included. If there are no “interesting” mixins, the returned scope will just return the same thing that the all method in ActiveRecord would have returned. Consequently, a default scope will be honoured if one has been declared, though default scopes are generally considered an anti-pattern to be avoided.

context

Hoodoo::Services::Context instance describing a call context. This is typically a value passed to one of the Hoodoo::Services::Implementation instance methods that a resource subclass implements.

As scoped_in, but intentionally omits any historical dating modules from the returned scope. The scope might then address both historic and contemporary records, depending on whether you are using manual or automatic dating.

context

Hoodoo::Services::Context instance describing a call context. This is typically a value passed to one of the Hoodoo::Services::Implementation instance methods that a resource subclass implements.

See also:

• Hoodoo::ActiveRecord::Dated

• Hoodoo::ActiveRecord::ManuallyDated

Specify a search mapping for use by list to automatically restrict list results.

In the simplest case, search query string entries and model field (attribute) names are assumed to be the same; if you wanted to search for values of model attributes name and colour using query string entries of name and colour you would just do this:

class SomeModel < ActiveRecord::Base
  search_with(
    :name   => nil,
    :colour => nil
  )
end

The nil values mean a default, case sensitive match is performed with the query string keys and values mapping directly to model query attribute names and values.

More complex example where colour is matched verbatim, but name is matched case-insensitive, assuming PostgreSQL's ILIKE is there:

class SomeModel < ActiveRecord::Base
  search_with(
    :name => Proc.new { | attr, value |
      [ 'name ILIKE ?', value ]
    },
    :colour => nil
  )
end

Extending the above to use a single Proc that handles case insensitive matches across all attributes:

class SomeModel < ActiveRecord::Base
  CI_MATCH = Proc.new { | attr, value |
    [ "#{ attr } ILIKE ?", value ]
  }

  search_with(
    :name   => CI_MATCH,
    :colour => CI_MATCH
  )
end

If you wanted to match against an array of possible matches, something like this would work:

ARRAY_MATCH = Proc.new { | attr, value |
  [ { attr => [ value ].flatten } ]
}

Note the returned array (see input parameter details) inside which the usual hash syntax for AREL .where-style queries is present.

To help out with common cases other than just specifying nil, the Hoodoo::ActiveRecord::Finder::SearchHelper class provides a method chaining approach which builds up the Hash used by search_with and filter_with. See that class's API documentation for details.

*args

A Hash. Keys are both search field names and model attribute names, unless overridden by values; values of nil are used for simple cases - “where( { attr_name => value } )” will be the resulting query modification. Alternatively, pass a callable Proc/Lambda. This is pased the attribute under consideration (and so you can ignore that and query against one or more different-named model attributes) and the context-caller-supplied value to search for. Return AN ARRAY of parameters to pass to where. For parameters to where, see:

api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where

The Hash keys giving the search attribute names can be specified as Strings or Symbols.

See Hoodoo::ActiveRecord::Finder::SearchHelper for methods which assist with filling in non-nil values for this Hash.