class Orchestrate::Collection

Collections are groupings of KeyValue items. They are analagous to tables in SQL databases.

Attributes

app[R]

@return [Orchestrate::Application] The application this collection belongs to.

name[R]

@return [String] The name of this collection.

Public Class Methods

new(app, collection_name) click to toggle source

Instantiate the Collection @param app [Orchestrate::Client, Orchestrate::Application] The application the Collection belongs to. @param collection_name [#to_s] The name of the collection. @return Orchestrate::Collection

# File lib/orchestrate/collection.rb, line 15
def initialize(app, collection_name)
  if app.kind_of? Orchestrate::Client
    @app = Application.new(app)
  else
    @app = app
  end
  @name = collection_name.to_s
end

Public Instance Methods

<<(value) click to toggle source

[Creates a KeyValue item with an auto-generated key](orchestrate.io/docs/api/#key/value/post-(create-&-generate-key)) @param value [#to_json] The value to store @return [Orchestrate::KeyValue] The KeyValue created. @note If the create is considered a success but the client is unable to parse the key

from the location header, an API::ServiceError is raised.
# File lib/orchestrate/collection.rb, line 103
def <<(value)
  response = perform(:post, value)
  match_data = response.location.match(%r{#{name}/([^/]+)})
  raise API::ServiceError.new(response) unless match_data
  KeyValue.from_bodyless_response(self, match_data[1], value, response)
end
<=>(other) click to toggle source

Equivalent to ‘String#<=>`. Compares by name and app’s api_key. @param other [Orchestrate::Collection] the collection to compare against. @return [nil, -1, 0, 1]

# File lib/orchestrate/collection.rb, line 43
def <=>(other)
  return nil unless other.kind_of?(Orchestrate::Collection)
  return nil unless other.app.api_key == app.api_key
  other.name <=> name
end
==(other) click to toggle source

Equivalent to ‘String#==`. Compares by name and app’s api_key. @param other [Orchestrate::Collection] the collection to compare against. @return [true, false]

# File lib/orchestrate/collection.rb, line 33
def ==(other)
  other.kind_of?(Orchestrate::Collection) && \
    other.app.api_key == app.api_key && \
    other.name == name
end
Also aliased as: eql?
[](key_name) click to toggle source

[Retrieves a KeyValue item by key](orchestrate.io/docs/api/#key/value/get). @param key_name [#to_s] The key of the item @return [Orchestrate::KeyValue, nil] The KeyValue item if found, nil if not.

# File lib/orchestrate/collection.rb, line 64
def [](key_name)
  begin
    KeyValue.load(self, key_name)
  rescue API::NotFound
    nil
  end
end
[]=(key_name, value) click to toggle source

[Sets a KeyValue item by key](orchestrate.io/docs/api/#key/value/put-(create/update)). @param key_name [#to_s] The key of the item. @param value [#to_json] The value to store at the key. @return [value] The item provided for ‘value’. @note Ruby will return the value provided to ‘something=` methods. If you want the KeyValue returned, use set. @raise Orchestrate::API::BadRequest the body is not valid JSON. @see set

# File lib/orchestrate/collection.rb, line 79
def []=(key_name, value)
  set(key_name, value)
end
after(start_key) click to toggle source

Sets the exclusive start key for enumeration over the KeyValue items in the collection. @see KeyValueList#after @return [KeyValueList]

# File lib/orchestrate/collection.rb, line 212
def after(start_key)
  KeyValueList.new(self).after(start_key)
end
before(end_key) click to toggle source

Sets the exclusive end key for enumeration over the KeyValue items in the collection. @see KeyValueList#before @return [KeyValueList]

# File lib/orchestrate/collection.rb, line 219
def before(end_key)
  KeyValueList.new(self).before(end_key)
end
build(key_name, value={}) click to toggle source

Builds a new, unsaved KeyValue with the given key_name and value. @param key_name [#to_s] The key of the item @param value [#to_json] The value to store at the key. @return [KeyValue]

# File lib/orchestrate/collection.rb, line 141
def build(key_name, value={})
  kv = KeyValue.new(self, key_name)
  kv.value = value
  kv
end
create(key_name_or_value, value=nil) click to toggle source

Creates a KeyValue item in the collection. @overload create(value)

(see #<<)
[Creates a KeyValue item with an auto-generated
key](http://orchestrate.io/docs/api/#key/value/post-\(create-&-generate-key\))
@param value [#to_json] The value to store
@return [Orchestrate::KeyValue] The KeyValue created.
@note If the create is considered a success but the client is unable to parse the key
  from the location header, an API::ServiceError is raised.

@overload create(key_name, value)

[Creates a KeyValue item by key, if the key doesn't have
a value](http://orchestrate.io/docs/api/#key/value/put-\(create/update\)).
@param key_name [#to_s] The name of the key
@param value [#to_json] The value to store at the key
@return [Orchestrate::KeyValue, nil] The KeyValue if created, false if not
# File lib/orchestrate/collection.rb, line 125
def create(key_name_or_value, value=nil)
  if value.nil? and key_name_or_value.respond_to?(:to_json)
    self << key_name_or_value
  else
    begin
      set(key_name_or_value, value, false)
    rescue Orchestrate::API::AlreadyPresent
      false
    end
  end
end
delete(key_name) click to toggle source

[Deletes the value for a KeyValue item](orchestrate.io/docs/api/#key/value/delete12). @param key_name [#to_s] The name of the key @return [true] If the request suceeds.

# File lib/orchestrate/collection.rb, line 161
def delete(key_name)
  perform(:delete, key_name)
  true
end
destroy!() click to toggle source

Deletes the collection. @return Orchestrate::API::Response

# File lib/orchestrate/collection.rb, line 53
def destroy!
  perform :delete_collection
end
each(&block) click to toggle source

Iterates over each KeyValue item in the collection. Used as the basis for Enumerable methods. Items are provided in lexicographically sorted order by key name. @overload each

@return [Enumerator]

@overload each(&block)

@yieldparam [Orchestrate::KeyValue] key_value The KeyValue item

@see KeyValueList#each @example

keys = collection.take(20).map(&:key)
# returns the first 20 keys in the collection.
# File lib/orchestrate/collection.rb, line 191
def each(&block)
  KeyValueList.new(self).each(&block)
end
end(end_key) click to toggle source

Sets the inclusive end key for enumeration over the KeyValue items in the collection. @see KeyValueList#end @return [KeyValueList]

# File lib/orchestrate/collection.rb, line 226
def end(end_key)
  KeyValueList.new(self).end(end_key)
end
eql?(other)
Alias for: ==
in(field, box={}) click to toggle source

Performs a search for items within a particular area, using a specified bounding box [Search for items in a geographic bounding box](orchestrate.io/docs/apiref#geo-queries-bounding) @param field [#to_s] The field containing location data (latitude & longitude) @param box [#to_json] The values to create the bounding box, @example

collection.in(:field, {north: 12.5, south: 15, east: 14, west: 3})

@return [Orchestrate::Search::QueryBuilder] A builder object to construct the query.

# File lib/orchestrate/collection.rb, line 380
def in(field, box={})
  box = box.flatten.each_slice(2).map {|dir, val| "#{dir}:#{val}" }.join(" ")
  query = "#{field}:IN:{#{box}}"
  Search::QueryBuilder.new(self, query)
end
inspect()
Alias for: to_s
lazy() click to toggle source

Creates a Lazy Enumerator for the Collection’s KeyValue List. If called inside the app’s ‘#in_parallel` block, pre-fetches the first page of results. @return [Enumerator::Lazy]

# File lib/orchestrate/collection.rb, line 198
def lazy
  KeyValueList.new(self).lazy
end
near(field, latitude, longitude, distance, units=nil) click to toggle source

@!group Geo Queries Performs a search for items near a specified geographic point in a collection. [Search for items near a geographic point](orchestrate.io/docs/apiref#geo-queries-near) @param field [#to_s] The field containing location data (latitude & longitude) @param latitude [Float] The number representing latitude of a geographic point @param longitude [Float] The number representing longitude of a geographic point @param distance [Integer] The number of distance units. @param units [#to_s] Unit of measurement for distance, default to kilometers (km), supported units: km, m, cm, mm, mi, yd, ft, in, nmi @return [Orchestrate::Search::QueryBuilder] A builder object to construct the query.

# File lib/orchestrate/collection.rb, line 366
def near(field, latitude, longitude, distance, units=nil)
  units ||= 'km'
  query = "#{field}:NEAR:{lat:#{latitude} lon:#{longitude} dist:#{distance}#{units}}"
  Search::QueryBuilder.new(self, query)
end
perform(api_method, *args) click to toggle source

Tells the Applicaiton to perform a request on its client, automatically providing the collection name. @param api_method [Symbol] The method on the client to call. @param args [#to_s, to_json, Hash] The arguments for the method. @return API::Response

# File lib/orchestrate/collection.rb, line 392
def perform(api_method, *args)
  app.perform(api_method, name, *args)
end
purge(key_name) click to toggle source

[Purges a KeyValue item and its Ref history](orchestrate.io/docs/api/#key/value/delete12). @param key_name [#to_s] The name of the key @return [true] If the request suceeds.

# File lib/orchestrate/collection.rb, line 170
def purge(key_name)
  perform(:purge, key_name)
  true
end
set(key_name, value, condition=nil) click to toggle source

[Sets a KeyValue item by key](orchestrate.io/docs/api/#key/value/put-(create/update)). @param key_name [#to_s] The key of the item. @param value [#to_json] The value to store at the key. @param condition [nil, false, to_s] (see Orchestraate::Client#put) @return [Orchestrate::KeyValue] The new KeyValue item. @raise Orchestrate::API::BadRequest the body is not valid JSON. @raise Orchestrate::API::VersionMismatch a String condition was provided, but does not match the ref for the current value. @raise Orchestrate::API::AlreadyPresent a false condition was provided, but a value already exists for this key @see []=

# File lib/orchestrate/collection.rb, line 92
def set(key_name, value, condition=nil)
  response = perform(:put, key_name, value, condition)
  KeyValue.from_bodyless_response(self, key_name, value, response)
end
start(start_key) click to toggle source

Sets the inclusive start key for enumeration over the KeyValue items in the collection. @see KeyValueList#start @return [KeyValueList]

# File lib/orchestrate/collection.rb, line 205
def start(start_key)
  KeyValueList.new(self).start(start_key)
end
stub(key_name) click to toggle source

Returns an unloaded KeyValue object with the given key_name, if you need to access Refs, Relations or Events without loading the KeyValue’s value. @param key_name [#to_s] The key of the item. @return [KeyValue]

# File lib/orchestrate/collection.rb, line 151
def stub(key_name)
  kv = KeyValue.new(self, key_name)
  kv.value = nil
  kv
end
take(count) click to toggle source

Returns the first n items. Equivalent to Enumerable#take. Sets the ‘limit` parameter on the query to Orchestrate, so we don’t ask for more than is needed. @param count [Integer] The number of items to limit to. @return [Array<KeyValue>]

# File lib/orchestrate/collection.rb, line 234
def take(count)
  KeyValueList.new(self).take(count)
end
to_s() click to toggle source

@return a pretty-printed representation of the collection.

# File lib/orchestrate/collection.rb, line 25
def to_s
  "#<Orchestrate::Collection name=#{name} api_key=#{app.api_key[0..7]}...>"
end
Also aliased as: inspect