Module: FulfilApi::Relation::QueryMethods

Included in:
FulfilApi::Relation
Defined in:
lib/fulfil_api/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.



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

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

#find_by!(conditions) ⇒ FulfilApi::Resource

Finds the first resource that matches the given conditions and raises

when no resource is found.

Parameters:

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

    The filter conditions as required by Fulfil.

Returns:

Raises:

See Also:



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

def find_by!(conditions)
  find_by(conditions) || raise(FulfilApi::Resource::NotFound, "Unable to find #{model_name} where #{conditions}")
end

#limit(value) ⇒ FulfilApi::Relation

Note:

If not specified, Fulfil will assume a request limit of 500.

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:



42
43
44
45
46
 
# File 'lib/fulfil_api/relation/query_methods.rb', line 42

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

#offset(value) ⇒ FulfilApi::Relation

Note:

If not specified, Fulfil will assume a request offset of 0.

Applies an offset to the API resources returned by Fulfil’s API.

This is useful when paginating over larger lists of API resources.

Parameters:

  • value (Integer) —

    The page offset for the API request.

Returns:



55
56
57
58
59
 
# File 'lib/fulfil_api/relation/query_methods.rb', line 55

def offset(value)
  clone.tap do |relation|
    relation.request_offset = value
  end
end

#select(*fields) ⇒ FulfilApi::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(model_name: "sale.line").select("sale.reference").find_by(["id", "=", 10])

Requesting additional fields

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

Parameters:

  • fields (Array<Symbol, String>) —

    The fields to include in the response.

Returns:



75
76
77
78
79
80
 
# File 'lib/fulfil_api/relation/query_methods.rb', line 75

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

#where(conditions) ⇒ FulfilApi::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(model_name: "sale.line").where(["sale.reference", "=", "ORDER-123"])

Parameters:

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

    The filter conditions as required by Fulfil.

Returns:



92
93
94
95
96
97
 
# File 'lib/fulfil_api/relation/query_methods.rb', line 92

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