class Orchestrate::Collection
Collections are groupings of KeyValue
items. They are analagous to tables in SQL databases.
Attributes
@return [Orchestrate::Application] The application this collection belongs to.
@return [String] The name of this collection.
Public Class Methods
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
[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
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
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
[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
[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
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
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
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
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
[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
Deletes the collection. @return Orchestrate::API::Response
# File lib/orchestrate/collection.rb, line 53 def destroy! perform :delete_collection end
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
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
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
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
@!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
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
[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
@param query [#to_s] The [Lucene Query
String](http://lucene.apache.org/core/4_3_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#Overview) to query the collection with.
@return [Orchestrate::Search::QueryBuilder] A builder object to construct the query.
# File lib/orchestrate/collection.rb, line 352 def search(query) Search::QueryBuilder.new(self, query) end
[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
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
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
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
@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