Class: OData::QueryBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/ruby_odata/query_builder.rb

Overview

The query builder is used to call query operations against the service. This shouldn't be called directly, but rather it is returned from the dynamic methods created for the specific service that you are calling.

The Categories method would return a QueryBuilder

Examples:

For example, given the following code snippet:

svc = OData::Service.new "http://127.0.0.1:8989/SampleService/RubyOData.svc"
svc.Categories

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(root, additional_params = {}) ⇒ QueryBuilder

Creates a new instance of the QueryBuilder class



15
16
17
18
19
20
21
22
23
24
25
26
27
# File 'lib/ruby_odata/query_builder.rb', line 15

def initialize(root, additional_params = {})
  @root = Helpers.uri_escape(root.to_s)
  @expands = []
  @filters = []
  @order_bys = []
  @navigation_paths = []
  @select = []
  @skip = nil
  @top = nil
  @count = nil
  @links_navigation_property = nil
  @additional_params = additional_params
end

Instance Attribute Details

#additional_paramsObject

Returns the value of attribute additional_params



9
10
11
# File 'lib/ruby_odata/query_builder.rb', line 9

def additional_params
  @additional_params
end

Instance Method Details

#countObject

Used to return a count of objects instead of the objects themselves

Examples:

svc.Products
svc.count
product_count = svc.execute

Raises:



119
120
121
122
123
124
125
# File 'lib/ruby_odata/query_builder.rb', line 119

def count
  raise OData::NotSupportedError.new("You cannot call both the `links` method and the `count` method in the same query.") if @links_navigation_property
  raise OData::NotSupportedError.new("You cannot call both the `select` method and the `count` method in the same query.") unless @select.empty?

  @count = true
  self
end

#expand(path) ⇒ Object

Used to eagerly-load data for nested objects, for example, obtaining a Category for a Product within one call to the server

Examples:

# Without expanding the query (no Category will be filled in for the Product)
svc.Products(1)
prod1 = svc.execute

# With expanding the query (the Category will be filled in)
svc.Products(1).expand('Category')
prod1 = svc.execute


40
41
42
43
# File 'lib/ruby_odata/query_builder.rb', line 40

def expand(path)
  @expands << path
  self
end

#filter(filter) ⇒ Object

Used to filter data being returned

Examples:

svc.Products.filter("Name eq 'Product 2'")
products = svc.execute


52
53
54
55
# File 'lib/ruby_odata/query_builder.rb', line 52

def filter(filter)
  @filters << CGI.escape(filter)
  self
end

Used to return links instead of actual objects

Examples:

svc.Categories(1).links("Products")
product_links = svc.execute # => returns URIs for the products under the Category with an ID of 1

Raises:



104
105
106
107
108
109
# File 'lib/ruby_odata/query_builder.rb', line 104

def links(navigation_property)
  raise OData::NotSupportedError.new("You cannot call both the `links` method and the `count` method in the same query.") if @count
  raise OData::NotSupportedError.new("You cannot call both the `links` method and the `select` method in the same query.") unless @select.empty?
  @links_navigation_property = navigation_property
  self
end

Used to navigate to a child collection, typically used to filter or perform a similar function against the children

Examples:

svc.Genres('Horror Movies').navigate("Titles").filter("Name eq 'Halloween'")


133
134
135
136
# File 'lib/ruby_odata/query_builder.rb', line 133

def navigate(navigation_property)
  @navigation_paths << Helpers.uri_escape(navigation_property)
  self
end

#order_by(order_by) ⇒ Object

Used to order the data being returned

Examples:

svc.Products.order_by("Name")
products = svc.execute


64
65
66
67
# File 'lib/ruby_odata/query_builder.rb', line 64

def order_by(order_by)
  @order_bys << CGI.escape(order_by)
  self
end

#queryObject

Builds the query URI (path, not including root) incorporating expands, filters, etc. This is used internally when the execute method is called on the service



161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
# File 'lib/ruby_odata/query_builder.rb', line 161

def query
  q = @root.clone

  # Navigation paths come first in the query
  q << "/#{@navigation_paths.join("/")}" unless @navigation_paths.empty?

  # Handle links queries, this isn't just a standard query option
  q << "/$links/#{@links_navigation_property}" if @links_navigation_property

  # Handle count queries, this isn't just a standard query option
  q << "/$count" if @count
  query_options = generate_query_options

  q << "?#{query_options.join('&')}" if !query_options.empty?
  q
end

#select(*fields) ⇒ Object

Used to customize the properties that are returned for "ad-hoc" queries

Examples:

svc.Products.select('Price', 'Rating')

Raises:



144
145
146
147
148
149
150
151
152
153
154
155
156
157
# File 'lib/ruby_odata/query_builder.rb', line 144

def select(*fields)
  raise OData::NotSupportedError.new("You cannot call both the `links` method and the `select` method in the same query.") if @links_navigation_property
  raise OData::NotSupportedError.new("You cannot call both the `count` method and the `select` method in the same query.") if @count

  @select |= fields

  expands =  fields.find_all { |f| /\// =~ f }
  expands.each do |e|
    parts = e.split '/'
    @expands |= [parts[0...-1].join('/')]
  end

  self
end

#skip(num) ⇒ Object

Used to skip a number of records This is typically used for paging, where it would be used along with the top method.

Examples:

svc.Products.skip(5)
products = svc.execute # => skips the first 5 items


77
78
79
80
# File 'lib/ruby_odata/query_builder.rb', line 77

def skip(num)
  @skip = num
  self
end

#top(num) ⇒ Object

Used to take only the top X records This is typically used for paging, where it would be used along with the skip method.

Examples:

svc.Products.top(5)
products = svc.execute # => returns only the first 5 items


90
91
92
93
# File 'lib/ruby_odata/query_builder.rb', line 90

def top(num)
  @top = num
  self
end