Class: Queries::Query::Filter

Inherits:
Queries::Query show all
Includes:
Concerns::Users
Defined in:
lib/queries/query/filter.rb

Overview

Overview

This class manages params and nesting of filter queries.

Each inheriting class defines a PARAMS variable. Each concern defines self.params. Together these two lists are used to compose a list of acceptable params, dynamically, based on the nature of the nested queries.

Test coverage is currently in /spec/lib/queries/.

!! When adding a new query tests do some linting of parameters, constants etc. Run them early and often !!

Constant Summary collapse

SUBQUERIES =

Registry of nested filters. Each key is a filter, each value lists the filters whose results it accepts as a scope. For example

loan: [:collection_object, :otu]

lets the Loan filter take collection_object_query: {...} or otu_query: {...} and return the loans of the matching collection objects / OTUs. Registering an entry:

- permits the nested params (see #permitted_params)
- builds the nested filter (see #set_nested_queries)

!! A nested <model>_query that is not registered for that filter, or !! more than one nested query at the same level, raises !! TaxonWorks::Error::NestedQuery (a 400 for JSON requests). Ignoring !! it would run the filter WITHOUT that scope, e.g. a batch update !! touching records outside the intended set.

Two kinds of entries:

  1. Filters with a Filter task (UI). These drive the radial filter "funnel" and must be mirrored in app/javascript/vue/components/radials/filter/links/*.js (spec/lib/queries/query/filter_spec.rb checks this). See also app/javascript/vue/components/radials/filter/constants/queryParam.js app/javascript/vue/components/radials/filter/constants/filterLinks.js and possibly app/javascript/vue/routes/routes.js app/javascript/vue/components/radials/linker/links

  2. Internal-only filters with no Filter task (:biological_associations_graph, :controlled_vocabulary_term, :conveyance, :data_attribute, :depiction). Used by other code, not the funnel, and skipped by the JS links spec.

!! If you add a def <model>_query_facet to a filter you will get !! spec failures if that model is not referenced here.

{
  anatomical_part: [:collection_object, :field_occurrence, :otu, :observation, :extract, :sound, :biological_association],
  asserted_distribution: [:source, :otu, :biological_association, :taxon_name, :dwc_occurrence, :observation],
  asserted_environment: [:collecting_event, :otu],
  biological_association: [:source, :collecting_event, :otu, :collection_object, :field_occurrence, :taxon_name, :asserted_distribution, :anatomical_part],
  biological_associations_graph: [:biological_association, :source],
  collecting_event: [:source, :collection_object, :field_occurrence, :biological_association, :otu, :image, :taxon_name, :dwc_occurrence, :asserted_environment],
  collection_object: [:source, :loan, :otu, :taxon_name, :collecting_event, :biological_association, :extract, :image, :observation, :dwc_occurrence, :anatomical_part],
  content: [:source, :otu, :taxon_name, :image],
  conveyance: [:sound],
  controlled_vocabulary_term: [:data_attribute],
  data_attribute: [:anatomical_part, :asserted_distribution, :asserted_environment, :biological_association, :collection_object, :collecting_event, :content, :depiction, :descriptor, :extract, :field_occurrence, :loan, :observation, :otu, :person, :sound, :source, :taxon_name],
  dwc_occurrence: [:asserted_distribution, :collection_object, :collecting_event, :field_occurrence, :otu],
  depiction: [:image],
  descriptor: [:source, :observation, :otu],
  extract: [:source, :otu, :collection_object, :observation, :anatomical_part],
  field_occurrence: [:collecting_event, :otu, :biological_association, :dwc_occurrence, :image, :observation, :taxon_name, :anatomical_part], # [:source, :otu, :collecting_event, :biological_association, :observation, :taxon_name, :extract],
  image: [:content, :collection_object, :collecting_event, :field_occurrence, :otu, :observation, :source, :taxon_name ],
  loan: [:collection_object, :otu],
  observation: [:asserted_distribution, :collection_object, :descriptor, :extract, :field_occurrence, :image, :otu, :sound, :source, :taxon_name, :anatomical_part],
  otu: [:asserted_distribution, :biological_association, :collection_object, :dwc_occurrence, :field_occurrence, :collecting_event, :content, :descriptor, :extract, :image, :loan, :observation, :source, :taxon_name, :anatomical_part, :sound, :asserted_environment ],
  person: [],
  source: [:asserted_distribution,  :biological_association, :collecting_event, :collection_object, :content, :descriptor, :extract, :image, :observation, :otu, :taxon_name, :taxon_name_relationship],
  sound: [:observation, :anatomical_part, :otu, :taxon_name],
  taxon_name: [:asserted_distribution, :biological_association, :collection_object, :collecting_event, :image, :otu, :source, :taxon_name_relationship, :sound],
  taxon_name_relationship: [:taxon_name, :source],
}.freeze
FILTER_QUERIES =

We could consider .safe_constantize to make this a f(n), but we'd have to have a list somewhere else anyways to further restrict allowed classes.

{
  anatomical_part_query: '::Queries::AnatomicalPart::Filter',
  asserted_distribution_query: '::Queries::AssertedDistribution::Filter',
  asserted_environment_query: '::Queries::AssertedEnvironment::Filter',
  biological_association_query: '::Queries::BiologicalAssociation::Filter',
  biological_associations_graph_query: '::Queries::BiologicalAssociationsGraph::Filter',
  collecting_event_query: '::Queries::CollectingEvent::Filter',
  collection_object_query: '::Queries::CollectionObject::Filter',
  content_query: '::Queries::Content::Filter',
  controlled_vocabulary_term_query: '::Queries::ControlledVocabularyTerm::Filter',
  conveyance_query: '::Queries::Conveyance::Filter',
  data_attribute_query: '::Queries::DataAttribute::Filter',
  depiction_query: '::Queries::Depiction::Filter',
  descriptor_query: '::Queries::Descriptor::Filter',
  document_query: '::Queries::Document::Filter',
  dwc_occurrence_query: '::Queries::DwcOccurrence::Filter',
  extract_query: '::Queries::Extract::Filter',
  field_occurrence_query: '::Queries::FieldOccurrence::Filter',
  image_query: '::Queries::Image::Filter',
  loan_query: '::Queries::Loan::Filter',
  observation_query: '::Queries::Observation::Filter',
  otu_query: '::Queries::Otu::Filter',
  person_query: '::Queries::Person::Filter',
  sound_query: '::Queries::Sound::Filter',
  source_query: '::Queries::Source::Filter',
  taxon_name_query: '::Queries::TaxonName::Filter',
  taxon_name_relationship_query: '::Queries::TaxonNameRelationship::Filter',
}.freeze

Instance Attribute Summary collapse

Attributes inherited from Queries::Query

#query_string, #terms

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Queries::Query

#alphabetic_strings, #alphanumeric_strings, base_name, #base_name, #base_query, #build_terms, #cached_facet, #end_wildcard, #levenshtein_distance, #match_ordered_wildcard_pieces_in_cached, #no_terms?, referenced_klass, #referenced_klass, #referenced_klass_except, #referenced_klass_intersection, #referenced_klass_union, #start_and_end_wildcard, #start_wildcard, #table, #wildcard_pieces

Constructor Details

#initialize(query_params) ⇒ Filter

Returns a new instance of Filter.

Parameters:

  • query_params (ActionController::Parameters) 


316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
 
# File 'lib/queries/query/filter.rb', line 316

def initialize(query_params)

  # Reference to query_params, i.e. always permitted
  @api = boolean_param(query_params, :api)

  @recent = boolean_param(query_params, :recent)
  @recent_target = query_params[:recent_target]

  @object_global_id = query_params[:object_global_id]

  @venn = query_params[:venn]
  @venn_mode = query_params[:venn_mode]
  @venn_ignore_pagination = boolean_param(query_params, :venn_ignore_pagination)

  # !! This is the *only* place Current.project_id should be seen !! It's still not the best
  # way to implement this, but we use it to optimize the scope of sub/nested-queries efficiently.
  # Ideally we'd have a global class param that stores this that all Filters would have access to,
  # rather than an instance variable
  @project_id = case
                when query_params[:project_id] == false # !! Only internal should pass this, therefor no type conversions
                  nil
                when query_params[:project_id].blank?
                  Current.project_id
                else
                  query_params[:project_id]
                end

  @paginate = boolean_param(query_params, :paginate)
  @per = query_params[:per]
  @page = query_params[:page]

  @order_by = query_params[:order_by]

  @roll_call = false

  # After this point, if you started with ActionController::Parameters,
  # then all values have been explicitly permitted.
  if query_params.kind_of?(Hash)
    @params = query_params
  elsif query_params.kind_of?(ActionController::Parameters)
    @params = deep_permit(query_params).to_hash.deep_symbolize_keys
  elsif query_params.nil?
    @params = {}
  else
    raise TaxonWorks::Error, "can not initialize filter with #{query_params.class.name}"
  end
  set_identifier_params(params)
  set_nested_queries(params)
  set_user_dates(params)
end

Instance Attribute Details

#anatomical_part_query ⇒ Query::AnatomicalPart::Filter?

Returns:

  • (Query::AnatomicalPart::Filter, nil) 


179
180
181
 
# File 'lib/queries/query/filter.rb', line 179

def anatomical_part_query
  @anatomical_part_query
end

#api ⇒ Boolean

Returns When true api_except_params is applied and other restrictions are placed:

- :venn param is ignored
- is_public=true is applied.

Returns:

  • (Boolean) —

    When true api_except_params is applied and other restrictions are placed:

    - :venn param is ignored
- is_public=true is applied


266
267
268
 
# File 'lib/queries/query/filter.rb', line 266

def api
  @api
end

#asserted_distribution_query ⇒ Query::AssertedDistribution::Filter?

Returns:

  • (Query::AssertedDistribution::Filter, nil) 


182
183
184
 
# File 'lib/queries/query/filter.rb', line 182

def asserted_distribution_query
  @asserted_distribution_query
end

#asserted_environment_query ⇒ Query::AssertedEnvironment::Filter?

Returns:

  • (Query::AssertedEnvironment::Filter, nil) 


185
186
187
 
# File 'lib/queries/query/filter.rb', line 185

def asserted_environment_query
  @asserted_environment_query
end

#biological_association_query ⇒ Query::BiologicalAssociation::Filter?

Returns:

  • (Query::BiologicalAssociation::Filter, nil) 


188
189
190
 
# File 'lib/queries/query/filter.rb', line 188

def biological_association_query
  @biological_association_query
end

#biological_associations_graph_query ⇒ Query::BiologicalAssociationsGraph::Filter?

Returns:

  • (Query::BiologicalAssociationsGraph::Filter, nil) 


191
192
193
 
# File 'lib/queries/query/filter.rb', line 191

def biological_associations_graph_query
  @biological_associations_graph_query
end

#collecting_event_query ⇒ Query::CollectingEvent::Filter?

Returns:

  • (Query::CollectingEvent::Filter, nil) 


200
201
202
 
# File 'lib/queries/query/filter.rb', line 200

def collecting_event_query
  @collecting_event_query
end

#collection_object_query ⇒ Query::TaxonName::Filter?

Returns:

  • (Query::TaxonName::Filter, nil) 


197
198
199
 
# File 'lib/queries/query/filter.rb', line 197

def collection_object_query
  @collection_object_query
end

#content_query ⇒ Query::Content::Filter?

Returns:

  • (Query::Content::Filter, nil) 


203
204
205
 
# File 'lib/queries/query/filter.rb', line 203

def content_query
  @content_query
end

#controlled_vocabulary_term_query ⇒ Query::ControlledVocabularyTerm::Filter?

Returns:

  • (Query::ControlledVocabularyTerm::Filter, nil) 


194
195
196
 
# File 'lib/queries/query/filter.rb', line 194

def controlled_vocabulary_term_query
  @controlled_vocabulary_term_query
end

#conveyance_query ⇒ Query::Conveyance::Filter?

Returns:

  • (Query::Conveyance::Filter, nil) 


206
207
208
 
# File 'lib/queries/query/filter.rb', line 206

def conveyance_query
  @conveyance_query
end

#data_attribute_query ⇒ Query::DataAttribute::Filter?

Returns:

  • (Query::DataAttribute::Filter, nil) 


209
210
211
 
# File 'lib/queries/query/filter.rb', line 209

def data_attribute_query
  @data_attribute_query
end

#depiction_query ⇒ Query::Depiction::Filter?

Returns:

  • (Query::Depiction::Filter, nil) 


215
216
217
 
# File 'lib/queries/query/filter.rb', line 215

def depiction_query
  @depiction_query
end

#descriptor_query ⇒ Query::Descriptor::Filter?

Returns:

  • (Query::Descriptor::Filter, nil) 


212
213
214
 
# File 'lib/queries/query/filter.rb', line 212

def descriptor_query
  @descriptor_query
end

#document_query ⇒ Query::Document::Filter?

Returns:

  • (Query::Document::Filter, nil) 


218
219
220
 
# File 'lib/queries/query/filter.rb', line 218

def document_query
  @document_query
end

#dwc_occurrence_query ⇒ Query::DwcOccurrence::Filter?

Returns:

  • (Query::DwcOccurrence::Filter, nil) 


221
222
223
 
# File 'lib/queries/query/filter.rb', line 221

def dwc_occurrence_query
  @dwc_occurrence_query
end

#extract_query ⇒ Query::Extract::Filter?

Returns:

  • (Query::Extract::Filter, nil) 


239
240
241
 
# File 'lib/queries/query/filter.rb', line 239

def extract_query
  @extract_query
end

#field_occurrence_query ⇒ Query::TaxonName::Filter?

Returns:

  • (Query::TaxonName::Filter, nil) 


224
225
226
 
# File 'lib/queries/query/filter.rb', line 224

def field_occurrence_query
  @field_occurrence_query
end

#image_query ⇒ Query::Image::Filter?

Returns:

  • (Query::Image::Filter, nil) 


227
228
229
 
# File 'lib/queries/query/filter.rb', line 227

def image_query
  @image_query
end

#loan_query ⇒ Query::Loan::Filter?

Returns:

  • (Query::Loan::Filter, nil) 


245
246
247
 
# File 'lib/queries/query/filter.rb', line 245

def loan_query
  @loan_query
end

#object_global_id ⇒ Array

Locally these look like gid://taxon-works/Otu/1 Using a global id is equivalent to using _id. I.e. it simply restricts the filter to those matching Model#id.

!! If any global id model name does not match the current filter, then then facet is completely rejected.

Parameters:

  • object_global_id —

    Rails global ids.

Returns:

  • (Array) 


174
175
176
 
# File 'lib/queries/query/filter.rb', line 174

def object_global_id
  @object_global_id
end

#observation_query ⇒ Query::Observation::Filter?

Returns:

  • (Query::Observation::Filter, nil) 


242
243
244
 
# File 'lib/queries/query/filter.rb', line 242

def observation_query
  @observation_query
end

#order_by ⇒ Object

Supported values:

* `match_identifiers` - sort by the order of the identifiers in provided

!! Does not sub-sort

Parameters:

  • order_by (String, Symbol) —

    the kind of sort to apply.

Returns:

  • symbol must match a existing parameter name (used to check if values provided)



295
296
297
 
# File 'lib/queries/query/filter.rb', line 295

def order_by
  @order_by
end

#otu_query ⇒ Query::Otu::Filter?

Returns:

  • (Query::Otu::Filter, nil) 


236
237
238
 
# File 'lib/queries/query/filter.rb', line 236

def otu_query
  @otu_query
end

#page ⇒ Integer?

Returns required if paginate == true.

Returns:

  • (Integer, nil) —

    required if paginate == true



156
157
158
 
# File 'lib/queries/query/filter.rb', line 156

def page
  @page
end

#paginate ⇒ Object

Apply pagination within Filter scope true - apply per and page false, nil - ignored



152
153
154
 
# File 'lib/queries/query/filter.rb', line 152

def paginate
  @paginate
end

#params ⇒ Hash (readonly)

!! Using setters directly on query parameters will not alter this variable !! !! This is used strictly during the permission process of ActionController::Parameters !!

Returns:

  • (Hash) —

    the parsed/permitted params that were used to on initialize() only!!



302
303
304
 
# File 'lib/queries/query/filter.rb', line 302

def params
  @params
end

#per ⇒ Integer?

Returns paginate must equal true page must be !nil?.

Returns:

  • (Integer, nil) —

    paginate must equal true page must be !nil?



161
162
163
 
# File 'lib/queries/query/filter.rb', line 161

def per
  @per
end

#person_query ⇒ Query::Person::Filter?

Returns:

  • (Query::Person::Filter, nil) 


248
249
250
 
# File 'lib/queries/query/filter.rb', line 248

def person_query
  @person_query
end

#project_id ⇒ Array

Parameters:

  • project_id (Array, Integer, false) —

    !! when passed false then Current.project_id is not applied, i.e. the result will be [] !! use the false pattern only for internal calls (e.g. rewriting

Returns:

  • (Array) 


147
148
149
 
# File 'lib/queries/query/filter.rb', line 147

def project_id
  @project_id
end

#recent ⇒ Boolean

Returns Applies an order on updated.

Returns:

  • (Boolean) —

    Applies an order on updated.



255
256
257
 
# File 'lib/queries/query/filter.rb', line 255

def recent
  @recent
end

#recent_target ⇒ Object

Returns symbol :created_at, :updated_at defaults to :updated_at if blank.

Returns:

  • symbol :created_at, :updated_at defaults to :updated_at if blank



259
260
261
 
# File 'lib/queries/query/filter.rb', line 259

def recent_target
  @recent_target
end

#roll_call ⇒ Boolean

If true then *_facet methods need only return scope.none to indicate that the facet is active given the current parameters. Facet return scopes are never actually queried in this case. If you're a facet that does work to create your scope then you should check this attribute and not do that work when it's true. Otherwise you can safely ignore this.

Returns:

  • (Boolean) 


313
314
315
 
# File 'lib/queries/query/filter.rb', line 313

def roll_call
  @roll_call
end

#sound_query ⇒ Query::Sound::Filter?

Returns:

  • (Query::Sound::Filter, nil) 


251
252
253
 
# File 'lib/queries/query/filter.rb', line 251

def sound_query
  @sound_query
end

#taxon_name_query ⇒ Query::TaxonName::Filter?

Returns:

  • (Query::TaxonName::Filter, nil) 


230
231
232
 
# File 'lib/queries/query/filter.rb', line 230

def taxon_name_query
  @taxon_name_query
end

#taxon_name_relationship_query ⇒ Query::TaxonNameRelationship::Filter?

Returns:

  • (Query::TaxonNameRelationship::Filter, nil) 


233
234
235
 
# File 'lib/queries/query/filter.rb', line 233

def taxon_name_relationship_query
  @taxon_name_relationship_query
end

#venn ⇒ String

Returns A JSON full URL containing the base string for a query.

Returns:

  • (String) —

    A JSON full URL containing the base string for a query



270
271
272
 
# File 'lib/queries/query/filter.rb', line 270

def venn
  @venn
end

#venn_ignore_pagination ⇒ Boolean

When true, all paging parameters will be removed from the B query and it will return its full result set for venn processing. When false, the B venn query will use only the single page indicated by whatever paging parameters are set on the query.

Returns:

  • (Boolean) 


282
283
284
 
# File 'lib/queries/query/filter.rb', line 282

def venn_ignore_pagination
  @venn_ignore_pagination
end

#venn_mode ⇒ Symbol

( A ( B ) C )

Returns:

  • (Symbol) —

    one of :a, :ab, :b :a :ab :b



275
276
277
 
# File 'lib/queries/query/filter.rb', line 275

def venn_mode
  @venn_mode
end

Class Method Details

.annotator_params ⇒ Array?

to be merged into included params

Returns:

  • (Array, nil) —

    a [:a, :b, []] formatted Array



492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
 
# File 'lib/queries/query/filter.rb', line 492

def self.annotator_params
  h = nil
  if i = included_annotator_facets
    # Setup with the first
    a = i.shift
    h = a.params

    if !h.last.kind_of?(Hash)
      h << {}
    end

    c = h.last

    # Now do the rest
    i.each do |j|
      p = j.params

      if p.last.kind_of?(Hash)
        c.merge!(p.pop)
      end

      h = p + h
    end
  end
  h
end

.api_except_params ⇒ Object

Any params set here, and in corresponding subclasses will not be permitted when api: true is present



485
486
487
 
# File 'lib/queries/query/filter.rb', line 485

def self.api_except_params
  [:venn, :venn_mode]
end

.api_excluded_params ⇒ Object 



519
520
521
522
523
 
# File 'lib/queries/query/filter.rb', line 519

def self.api_excluded_params
  [
    # if there are things like created_by_id that we deem universally out they go here
  ] + api_except_params
end

.base_filter(params) ⇒ Filter?

Returns the class of filter that is referenced at the base of this parameter set.

Parameters:

  • params (ActionController::Parameters)

Returns:

  • (Filter, nil) —

    the class of filter that is referenced at the base of this parameter set



403
404
405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/queries/query/filter.rb', line 403

def self.base_filter(params)
  if s = base_query_name(params)
    t = s.gsub('_query', '').to_sym

    if SUBQUERIES.include?(t)
      k = t.to_s.camelcase
      return "Queries::#{k}::Filter".constantize
    else
      return nil
    end
  else
    nil
  end
end

.base_query_name(params) ⇒ Object

Returns the single top-level <model>_query key, or nil raises TaxonWorks::Error::NestedQuery when there is more than one: using just the first would run e.g. a batch without the others' scope.

Returns:

  • the single top-level <model>_query key, or nil raises TaxonWorks::Error::NestedQuery when there is more than one: using just the first would run e.g. a batch without the others' scope



430
431
432
433
434
435
436
437
 
# File 'lib/queries/query/filter.rb', line 430

def self.base_query_name(params)
  a = params.keys.select { |s| s =~ /\A.+_query\z/ }
  if a.count > 1
    raise TaxonWorks::Error::NestedQuery,
      "only one top-level query is permitted, got #{a.join(', ')}"
  end
  a.first
end

.base_query_to_h(params) ⇒ Object

base_query, as params, like {otu_query: {}} This sanitizes params.

Returns:

  • the params use to instantiate the full



442
443
444
 
# File 'lib/queries/query/filter.rb', line 442

def self.base_query_to_h(params)
  return { base_query_name(params) => instantiated_base_filter(params).params }
end

.included_annotator_facets ⇒ Object 



446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/queries/query/filter.rb', line 446

def self.included_annotator_facets
  f = [
    ::Queries::Concerns::Users
  ]

  if referenced_klass.annotates?
    f.push ::Queries::Concerns::Polymorphic if self < ::Queries::Concerns::Polymorphic
  else
    # TODO There is room for an AlternateValue concern here
    f.push ::Queries::Concerns::Attributes if self < ::Queries::Concerns::Attributes
    f.push ::Queries::Concerns::Citations if self < ::Queries::Concerns::Citations
    f.push ::Queries::Concerns::Confidences if self < ::Queries::Concerns::Confidences
    f.push ::Queries::Concerns::Containable if self < ::Queries::Concerns::Containable
    f.push ::Queries::Concerns::Conveyances if self < ::Queries::Concerns::Conveyances
    f.push ::Queries::Concerns::DataAttributes if self < ::Queries::Concerns::DataAttributes
    f.push ::Queries::Concerns::DateRanges if self < ::Queries::Concerns::DateRanges
    f.push ::Queries::Concerns::Depictions if self < ::Queries::Concerns::Depictions
    f.push ::Queries::Concerns::Identifiers if self < ::Queries::Concerns::Identifiers
    f.push ::Queries::Concerns::Notes if self < ::Queries::Concerns::Notes
    f.push ::Queries::Concerns::Protocols if self < ::Queries::Concerns::Protocols
    f.push ::Queries::Concerns::Tags if self < ::Queries::Concerns::Tags
    f.push ::Queries::Concerns::TaxonDetermination if self < ::Queries::Concerns::TaxonDetermination
    f.push ::Queries::Concerns::Verifiers if self < ::Queries::Concerns::Verifiers
    f.push ::Queries::Concerns::PreparationTypes if self < ::Queries::Concerns::PreparationTypes
  end

  f
end

.instantiated_base_filter(params) ⇒ Object

An instiatied filter, with params set, for params with patterns like otu_query={}



419
420
421
422
423
424
425
 
# File 'lib/queries/query/filter.rb', line 419

def self.instantiated_base_filter(params)
  if s = base_filter(params)
    s.new(params[base_query_name(params)])
  else
    nil
  end
end

.inverted_subqueries ⇒ Hash

Returns only referenced in specs.

Returns:

  • (Hash) —

    only referenced in specs



97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/queries/query/filter.rb', line 97

def self.inverted_subqueries
  r = {}
  SUBQUERIES.each do |k,v|
    v.each do |m|
      if r[m]
        r[m].push k
      else
        r[m] = [k]
      end
    end
  end
  r
end

.params ⇒ Array

Returns merges [:a, {a: []}] into [:a].

Returns:

  • (Array) —

    merges [:a, {a: []}] into [:a]



477
478
479
480
481
 
# File 'lib/queries/query/filter.rb', line 477

def self.params
  a = self::PARAMS.dup
  b = a.pop.keys
  (a + b).uniq
end

.query_name ⇒ Object 



89
90
91
 
# File 'lib/queries/query/filter.rb', line 89

def self.query_name
  base_name + '_query'
end

.set_paging(query, state) ⇒ ActiveQuery

Returns query with paging set to state.

Parameters:

  • query (ActiveQuery)
  • state (Hash) —

    see #paging_state

Returns:

  • (ActiveQuery) —

    query with paging set to state



720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
 
# File 'lib/queries/query/filter.rb', line 720

def self.set_paging(query, state)
  return query if !state
  state = state.symbolize_keys

  if state[:paginate]
    if state[:ordered]
      # Order has already been set.
      query = query.page(state[:page]).per(state[:per])
    else
      query = query.order(:id).page(state[:page]).per(state[:per])
    end
  end

  query
end

Instance Method Details

#all(nil_empty = false) ⇒ ActiveRecord::Relation

See /lib/queries/ARCHITECTURE.md for additional explanation.

TODO: consider "true" for default, changing to false on controller Filter calls

Parameters:

  • nil_empty (Boolean) (defaults to: false) —

    If true then if there are no clauses return nil not .all

Returns:

  • (ActiveRecord::Relation) 


934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
 
# File 'lib/queries/query/filter.rb', line 934

def all(nil_empty = false)

  # TODO: should turn off/on project_id here on nil empty?

  a = all_and_clauses
  b = all_merge_clauses

  # TODO: do not consider project_id alone a parameter on nil_empty

  # Limited use within the UI because project_id is set
  return nil if nil_empty && a.nil? && b.nil?

  # !! Do not apply `.distinct here`

  q = nil
  if a && b
    q = b.where(a)
  elsif a
    q = referenced_klass.where(a)
  elsif b
    q = b
  else
    q = referenced_klass.all
  end

  if venn_mode && venn && !api
    q = apply_venn(q)
  end

  # TODO: collides with recent, and needs isolation/generic application
  # probably through native .order() use.
  # Order in general likely belongs outside the scope of filters, but
  # see this param use, where we depend on the incoming values
  #
  # See spec/lib/queries/otu/filter_spec.rb for tests

  # See lib/queries/concerns/identifiers.rb
  if order_by
    q = match_identifier_order_by(q)
  end

  if recent
    q = referenced_klass.from(q.all, table.name).order(recent_target => :desc)
  end

  if api
    if referenced_klass.column_names.include?('is_public')
      q = q.where(is_public: [nil, true])
    end
  end

  q = set_paging(q)

  # TODO: canonically address whether or not to use `.distinct` at this point, we should be able to, however
  # some incoming queries may have joins/group/etc. alone?! I.e. why can't we?

  q
end

#all_and_clauses ⇒ ActiveRecord::Relation?

Returns:

  • (ActiveRecord::Relation, nil) 


834
835
836
837
838
839
840
841
842
843
 
# File 'lib/queries/query/filter.rb', line 834

def all_and_clauses
  clauses = target_and_clauses
  return nil if clauses.empty?

  a = clauses.shift
  clauses.each do |b|
    a = a.and(b)
  end
  a
end

#all_merge_clauses ⇒ Scope?

Of interest, the previous native merge() (and `and()``) make things complicated:

For example a.merge(b) != b.merge(a) in some cases. This is because certain clauses are tossed without warning (notably .from()). See:

We presently use SQL with INTERSECTION to combine facets.

Returns:

  • (Scope, nil) 


865
866
867
868
869
870
871
872
873
874
875
876
877
878
 
# File 'lib/queries/query/filter.rb', line 865

def all_merge_clauses
  clauses = merge_clauses + annotator_merge_clauses
  clauses.compact!

  return nil if clauses.empty?

  # TODO: consider whether to implement this.
  # It should be safe, except, possibly for aggregate based queries
  # that include custom attributes, would these get cleared.
  # We could requier that at this level they are wrapped in a From etc.
  # a = clauses.collect{|q| q.unscope(:select).select(:id) }

  referenced_klass_intersection(clauses)
end

#and_clauses ⇒ Object

Defined in inheriting classes



829
830
831
 
# File 'lib/queries/query/filter.rb', line 829

def and_clauses
  []
end

#annotator_and_clauses ⇒ Object 



806
807
808
809
810
811
812
813
814
815
816
817
818
 
# File 'lib/queries/query/filter.rb', line 806

def annotator_and_clauses
  a = []
  self.class.included_annotator_facets.each do |c|
    if c.respond_to?(:and_clauses)
      c.and_clauses.each do |f|
        if v = send(f)
          a.push v
        end
      end
    end
  end
  a
end

#annotator_merge_clauses ⇒ Object 



787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
 
# File 'lib/queries/query/filter.rb', line 787

def annotator_merge_clauses
  a = []

  # !! Interesting `.compact` removes #<ActiveRecord::Relation []>,
  # so patterns that us collect.flatten.compact return empty,
  #  `.present?` fails as well, so verbose loops here
  self.class.included_annotator_facets.each do |c|
    if c.respond_to?(:merge_clauses)
      next if c.name == 'Queries::Concerns::Identifiers' && no_identifier_clauses
      c.merge_clauses.each do |f|
        if v = send(f)
          a.push v
        end
      end
    end
  end
  a
end

#apply_venn(query) ⇒ Object 



880
881
882
 
# File 'lib/queries/query/filter.rb', line 880

def apply_venn(query)
  Queries.venn(query, venn_query.all, venn_mode)
end

#attribute_exact_facet(attribute = nil) ⇒ Object

params attribute [Symbol] a facet for use when params include author, and exact_author pattern combinations See queries/source/filter.rb for example use See /spec/lib/queries/source/filter_spec.rb !! Whitespace (e.g. tabs, newlines) is ignored when exact is used !!!



768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
 
# File 'lib/queries/query/filter.rb', line 768

def attribute_exact_facet(attribute = nil)
  a = attribute.to_sym
  return nil if send(a).blank?
  if send("exact_#{a}".to_sym)

    # TODO: Think we need to handle ' and '

    v = send(a)
    v.gsub!(/\s+/, ' ')
    v = ::Regexp.escape(v)
    v.gsub!(/\\\s+/, '\s*') # spaces are escaped, but we need to expand them in case we dont' get them caught
    v = '^\s*' + v + '\s*$'

    table[a].matches_regexp(v)
  else
    table[a].matches('%' + send(a).strip.gsub(/\s+/, '%') + '%')
  end
end

#deep_permit(params) ⇒ Object

Returns ActionController::Parameters.

Parameters:

  • params —

    ActionController::Parameters

Returns:

  • ActionController::Parameters



646
647
648
 
# File 'lib/queries/query/filter.rb', line 646

def deep_permit(params)
  params.permit( permitted_params(params.to_unsafe_hash))
end

#disable_paging ⇒ Object 



704
705
706
707
708
709
710
 
# File 'lib/queries/query/filter.rb', line 704

def disable_paging
  r = paging_state

  self.paginate = false

  r
end

#merge_clauses ⇒ Object

Defined in inheriting classes



850
851
852
 
# File 'lib/queries/query/filter.rb', line 850

def merge_clauses
  []
end

#model_id_facet ⇒ Object

Returns id= facet, automatically added to all queries. Over-ridden in some base classes.



739
740
741
742
743
 
# File 'lib/queries/query/filter.rb', line 739

def model_id_facet
  m = (base_name + '_id').to_sym
  return nil if send(m).empty?
  table[:id].in(send(m))
end

#object_global_id_facet ⇒ Object 



750
751
752
753
754
755
756
757
758
759
760
761
 
# File 'lib/queries/query/filter.rb', line 750

def object_global_id_facet
  return nil if object_global_id.empty?
  ids = []
  object_global_id.each do |i|
    g = GlobalID.parse(i)
    # If any global_ids do not reference this Class, abort
    return nil unless g.model_class.base_class.name == referenced_klass.name
    ids.push g.model_id
  end

  table[:id].in(ids)
end

#only_project? ⇒ Boolean

!! WARNING: this will "fail" (i.e. return false) in background jobs where Current.project_id isn't set. !! You may want only_project_or_less? instead.

Returns:

  • (Boolean) —

    true - the only param pasted is project_id !! Note that this is the default for all queries, it is set on initialize false - there are no params at ALL or at least one that is not project_id, and project_id != false



910
911
912
913
914
915
916
917
918
 
# File 'lib/queries/query/filter.rb', line 910

def only_project?
  @roll_call = true
  a = project_id_facet &&
    target_and_clauses.size == 1 &&
    all_merge_clauses.nil?
  @roll_call = false

  a
end

#only_project_or_less? ⇒ Boolean

See also only_project?

Returns:

  • (Boolean) 


921
922
923
924
 
# File 'lib/queries/query/filter.rb', line 921

def only_project_or_less?
  only_project? ||
  (target_and_clauses.size == 0 && all_merge_clauses.nil?)
end

#paging_state ⇒ Object 



689
690
691
692
693
694
695
696
697
698
699
700
701
702
 
# File 'lib/queries/query/filter.rb', line 689

def paging_state
  if paginate
    {
      paginate: true,
      per:,
      page:,
      # This shouldn't be here, but see order_by processing for identifiers
      # in #all.
      ordered: order_by.present?
    }
  else
    { paginate: false }
  end
end

#permitted_params(hsh) ⇒ Array

This method is a preprocessor that discovers, by finding the nested subqueries, which params should be permitted. It is used to build a permitable profile of parameters.

That profile is then used in the actual .permit() call.

An alternate solution, first tried, is to permit the params directly during inspection for subqueries. This also would work, however there are some nice benefits to having a profile of the allowed params available as an Array, for example we can use it for API documentation a little easier(?!).

In essence what we needed was for ActionController::Parameters to be able to accumulate (remember) all permitted params (not just their actual data) over multiple .permit() calls. If we had that, then we could do something like params.permitted_params => Array after multiple calls like params.permit(:a), params.permit(:b).

any parameter set for the query.

Parameters:

  • hsh —

    Hash Uses an unsafe hash from an instance of ActionController::Parameters or

Returns:

  • (Array) —

    like [:a,:b, :c, []]



546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
 
# File 'lib/queries/query/filter.rb', line 546

def permitted_params(hsh)
  h = self.class::PARAMS.deep_dup
  h.unshift(:venn_ignore_pagination)
  h.unshift(:venn_mode)
  h.unshift(:venn)
  h.unshift(:per)
  h.unshift(:page)
  h.unshift(:paginate)

  # Rails' permit() format requires a specific structure:
  #   [:scalar_param1, :scalar_param2, {array_or_nested: [...]}]
  #
  # The hash at the end is where we put:
  #   1. Array parameters (e.g., collection_object_id: [])
  #   2. Nested structures (e.g., otu_query: [...])
  #
  # Ensure the array has a hash at the end to hold these.
  if !h.last.kind_of?(Hash)
    h << {}
  end

  c = h.last # Reference to the hash where nested/array params go.

  if n = self.class.annotator_params
    c.merge!(n.pop)
    h = n + h
  end

  b = subquery_vector(hsh)

  parent = self.class

  while !b.empty?
    a = b.shift

    if !SUBQUERIES.fetch(parent.base_name.to_sym, []).include?( a.to_s.gsub('_query', '').to_sym )
      raise_unregistered_nested_query(parent, a)
    end

    q = FILTER_QUERIES[a].safe_constantize
    p = q::PARAMS.deep_dup

    p.unshift(:venn_ignore_pagination)
    p.unshift(:venn_mode)
    p.unshift(:venn)
    p.unshift(:per)
    p.unshift(:page)
    p.unshift(:paginate)

    if !p.last.kind_of?(Hash)
      p << {}
    end

    if n = q.annotator_params
      p.last.merge!(n.pop)
      p = n + p
    end

    # Exclusions apply at every nesting level, not just the top.
    if api
      q.api_excluded_params.each do |e|
        p.delete_if { |k,v| e == k }
        p.last.delete_if { |k,v| e == k }
      end
    end

    c[a] = p

    c = p.last

    parent = q
  end

  if api
    self.class.api_excluded_params.each do |a|
      h.delete_if{|k,v| a == k}
      h.last.delete_if{|k,v| a == k }
    end
  end

  h
end

#process_url_into_params(url) ⇒ Object 



396
397
398
 
# File 'lib/queries/query/filter.rb', line 396

def process_url_into_params(url)
  Rack::Utils.parse_nested_query(url)
end

#project_id_facet ⇒ Object 



745
746
747
748
 
# File 'lib/queries/query/filter.rb', line 745

def project_id_facet
  return nil if project_id.empty?
  table[:project_id].in(project_id)
end

#raise_multiple_nested_queries(query_names) ⇒ Object

Raises:

  • (TaxonWorks::Error::NestedQuery) 


655
656
657
658
 
# File 'lib/queries/query/filter.rb', line 655

def raise_multiple_nested_queries(query_names)
  raise TaxonWorks::Error::NestedQuery,
    "only one nested query is permitted per level, got #{query_names.join(', ')}"
end

#raise_unregistered_nested_query(parent, query_name) ⇒ Object

Raises:

  • (TaxonWorks::Error::NestedQuery) 


650
651
652
653
 
# File 'lib/queries/query/filter.rb', line 650

def raise_unregistered_nested_query(parent, query_name)
  raise TaxonWorks::Error::NestedQuery,
    "#{query_name} is not a permitted nested query for #{parent.base_name}"
end

#set_nested_queries(params) ⇒ True

Returns raises TaxonWorks::Error::NestedQuery on unregistered or multiple nested queries.

Parameters:

  • params (Hash) —

    set all nested queries variables, e.g. @otu_filter_query

Returns:

  • (True) —

    raises TaxonWorks::Error::NestedQuery on unregistered or multiple nested queries



664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
 
# File 'lib/queries/query/filter.rb', line 664

def set_nested_queries(params)

  if n = params.select{|k, p| k.to_s =~ /_query/ }
    # !!! can't have multiple nested queries inside one level !!! This lets us
    # eliminate infinite loops at the cost of expressiveness?!
    raise_multiple_nested_queries(n.keys) if n.keys.count > 1
    return nil if n.keys.count == 0

    query_name = n.first.first

    if !SUBQUERIES.fetch(base_name.to_sym, []).include?( query_name.to_s.gsub('_query', '').to_sym )
      raise_unregistered_nested_query(self.class, query_name)
    end

    query_params = n.first.last

    q = FILTER_QUERIES[query_name].safe_constantize.new(query_params)

    # assign to @<model>_query
    send("#{query_name}=".to_sym, q)
  end

  true
end

#set_paging(query) ⇒ Object

Parameters:

  • query (ActiveQuery) 


713
714
715
 
# File 'lib/queries/query/filter.rb', line 713

def set_paging(query)
  self.class.set_paging(query, paging_state)
end

#shared_and_clauses ⇒ Object 



820
821
822
823
824
825
826
 
# File 'lib/queries/query/filter.rb', line 820

def shared_and_clauses
  [
    project_id_facet,
    model_id_facet,
    object_global_id_facet,
  ]
end

#subquery_vector(hsh) ⇒ Array of Symbol

Since queries nest linearly we don't need recursion.

Parameters:

  • hsh —

    Hash

Returns:

  • (Array of Symbol) —

    all queries, in nested order



633
634
635
636
637
638
639
640
641
642
 
# File 'lib/queries/query/filter.rb', line 633

def subquery_vector(hsh)
  result = []
  while !hsh.keys.select{|k| k =~ /_query/}.empty?
    a = hsh.keys.select{|k| k =~ /_query/}
    raise_multiple_nested_queries(a) if a.count > 1
    result += a
    hsh = hsh[a.first]
  end
  result.map(&:to_sym)
end

#target_and_clauses ⇒ Object 



845
846
847
 
# File 'lib/queries/query/filter.rb', line 845

def target_and_clauses
  [and_clauses + annotator_and_clauses + shared_and_clauses].flatten.compact
end

#venn_query ⇒ Object 



884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
 
# File 'lib/queries/query/filter.rb', line 884

def venn_query
  u = ::Addressable::URI.parse(venn).query
  # Brackets may be multi-encoded
  t = nil
  i = 0
  max = 10
  while t != u && i < max
    t = u
    u = Addressable::URI.unencode(t)
    i += 1
  end

  p = ::Rack::Utils.parse_nested_query(u) # nested supports brackets
  p = p.except('per', 'page', 'paginate') if venn_ignore_pagination

  a = ActionController::Parameters.new(p)

  self.class.new(a)
end