Module: FulfilApi::Resource::Relation::QueryMethods

Included in:
FulfilApi::Resource::Relation
Defined in:
lib/fulfil_api/resource/relation/query_methods.rb

Overview

The QueryMethods extends the relation by

adding query methods to it.

Instance Method Summary collapse

Instance Method Details

#find_by(conditions) ⇒ FulfilApi::Resource?

Note:

Unlike the other methods in this module, ‘#find_by` will immediately trigger an HTTP request to retrieve the resource, rather than allowing for lazy evaluation.

Finds the first resource that matches the given conditions.

It constructs a query using the ‘where` method, limits the result to one record,

and then returns the first result.

Parameters:

  • conditions (Array<String, String, String>) —

    The filter conditions as required by Fulfil.

Returns:

  • (FulfilApi::Resource, nil) —

    The first resource that matches the conditions, or nil if no match is found.



20
21
22
 
# File 'lib/fulfil_api/resource/relation/query_methods.rb', line 20

def find_by(conditions)
  where(conditions).limit(1).first
end

#limit(value) ⇒ FulfilApi::Resource::Relation

Note:

If not specified, Fulfil’s API defaults to returning up to 500 resources per call.

Limits the number of resources returned by Fulfil’s API. This is useful when only

a specific number of resources are needed.

Parameters:

  • value (Integer) —

    The maximum number of resources to return.

Returns:



31
32
33
34
35
 
# File 'lib/fulfil_api/resource/relation/query_methods.rb', line 31

def limit(value)
  clone.tap do |relation|
    relation.request_limit = value
  end
end

#select(*fields) ⇒ FulfilApi::Resource::Relation

Specifies the fields to include in the response from Fulfil’s API. By default, only

the ID is returned.

Supports dot notation for nested data fields, though not all nested data may be available

depending on the API's limitations.

Examples:

Requesting nested data fields

FulfilApi::Resource.set(name: "sale.line").select("sale.reference").find_by(["id", "=", 10])

Requesting additional fields

FulfilApi::Resource.set(name: "sale.sale").select(:reference).find_by(["id", "=", 10])

Parameters:

  • fields (Array<Symbol, String>) —

    The fields to include in the response.

Returns:



51
52
53
54
55
56
 
# File 'lib/fulfil_api/resource/relation/query_methods.rb', line 51

def select(*fields)
  clone.tap do |relation|
    relation.fields.concat(fields.map(&:to_s))
    relation.fields.uniq!
  end
end

#where(conditions) ⇒ FulfilApi::Resource::Relation

TODO:

Enhance the #where method to allow more natural and flexible queries.

Adds filter conditions for querying Fulfil’s API. Conditions should be formatted

as arrays according to the Fulfil API documentation.

Examples:

Simple querying with conditions

FulfilApi::Resource.set(name: "sale.line").where(["sale.reference", "=", "ORDER-123"])

Parameters:

  • conditions (Array<String, String, String>) —

    The filter conditions as required by Fulfil.

Returns:



68
69
70
71
72
73
 
# File 'lib/fulfil_api/resource/relation/query_methods.rb', line 68

def where(conditions)
  clone.tap do |relation|
    relation.conditions << conditions.flatten
    relation.conditions.uniq!
  end
end