class Cloudant::Client

Attributes

base_uri[RW]
database[RW]
password[R]
username[R]

Public Class Methods

new(args) click to toggle source
# File lib/cloudant/client.rb, line 7
def initialize(args)
  @username = args[:username]
  @password = args[:password]
  @database = args[:database]
  @base_uri = "https://#{username}.cloudant.com/"
  @conn     = start_connection(username,password,base_uri)

  @conn.cookie_auth
end

Public Instance Methods

all_dbs() click to toggle source

Returns all database for the current instance of Cloudant

# File lib/cloudant/client.rb, line 109
def all_dbs
  @conn.query({url_path: "_all_dbs", method: :get})
end
all_docs(*opts) click to toggle source

Retrieve all docs from the database

# File lib/cloudant/client.rb, line 18
def all_docs(*opts)
  q = "#{database}/_all_docs"
  q << build_query_string(opts.first,"all_docs") if opts && opts.any? && opts.first.is_a?(Hash)

  @conn.query({url_path: q, method: :get})
end
bookmark_query(q) { |docs| ... } click to toggle source

Paginate query results - best for large volume. TODO: add feature that allows users to view previous pages and generally move into own class.

# File lib/cloudant/client.rb, line 199
def bookmark_query(q,&blk)
  response = query(q)
  bookmark = response["bookmark"]
  docs     = response["docs"]

  until !docs || docs.empty?
    yield docs
    q["bookmark"] = bookmark
    response      = query(q)
    bookmark      = response["bookmark"]
    docs          = response["docs"]
  end

  docs
end
changes(*opts) click to toggle source

Get a hash {“results” => []}, containing a hash of seq, id, changes

# File lib/cloudant/client.rb, line 101
def changes(*opts)
  q = "#{database}/_changes"
  q << build_query_string(opts.first,"changes") if opts && opts.any? && opts.first.is_a?(Hash)

  @conn.query({url_path: q, method: :get})
end
close() click to toggle source

Delete the current cookie.

# File lib/cloudant/client.rb, line 216
def close
  @conn.close
end
create(doc)
Alias for: create_doc
create_db(database) click to toggle source

Create a new database for the current Cloudant instance

# File lib/cloudant/client.rb, line 120
def create_db(database)
  @conn.query({url_path: database, method: :put})
end
create_ddoc(id,doc)
Alias for: create_design_doc
create_design_doc(id,doc) click to toggle source

Need to provide valid design doc or returns an error hash.

# File lib/cloudant/client.rb, line 75
def create_design_doc(id,doc)
  @conn.query({url_path: "#{database}/_design/#{id}", opts: doc, method: :put})
end
Also aliased as: update_design_doc, create_ddoc
create_doc(doc) click to toggle source

A valid doc must be provided. The doc must be a hash that can. Use create_docs to create multiple documents at once.

# File lib/cloudant/client.rb, line 42
def create_doc(doc)
  @conn.query({url_path: "#{database}", opts: doc, method: :post})
end
Also aliased as: create, post
create_docs(docs_array) click to toggle source

Accepts an array of docs. Ids and revs are optional for creation but required for update.

# File lib/cloudant/client.rb, line 178
def create_docs(docs_array)
  bulk_docs(docs_array)
end
Also aliased as: update_docs
create_index(args) click to toggle source

Create a new index. A valid index must be given. Note: An index will be created if only a name is provided (see below)

# File lib/cloudant/client.rb, line 130
def create_index(args)
  if args[:name]
    new_index = create_new_index(args)

    @conn.query({url_path: "#{database}/_index", opts: new_index, method: :post})
  else
    raise ArgumentError.new('name is required')
  end
end
create_new_index(args) click to toggle source

If only a name is provided the default index doc is {“type”: “text”,“index”: {}} The default index, {}, will index all fields in all docs. This may take a long time with large databases.

# File lib/cloudant/client.rb, line 143
def create_new_index(args)
  new_index = {}
  
  args[:index] ? new_index["index"] = args[:index] : new_index["index"] = {}
  
  new_index["name"] = args[:name] if args[:name]
  new_index["ddoc"] = args[:ddoc] if args[:ddoc]

  args[:type] ? new_index["type"] = args[:type] : new_index["type"] = "text"

  new_index
end
create_view(id,doc) click to toggle source

Id of the design doc in which the view (doc) will be held. Views must be held in design docs; if no design doc matches the id provided, one will be created with said id.

# File lib/cloudant/client.rb, line 93
def create_view(id,doc)
  resp = get_design_doc(id)
  ddoc = set_views(resp,doc)

  create_design_doc(id,ddoc)
end
db_info() click to toggle source

Returns info about the database, including update_seq, db_name etc.

# File lib/cloudant/client.rb, line 114
def db_info
  @conn.query({url_path: "#{database}", method: :get})
end
Also aliased as: info
ddoc(id)
Alias for: get_design_doc
delete(id)
Alias for: delete_doc
delete_db(database) click to toggle source
# File lib/cloudant/client.rb, line 124
def delete_db(database)
  @conn.query({url_path: database, method: :delete})
end
delete_design_doc(id) click to toggle source

Intended behavior for this method to accept only an id to delete a doc. TODO: Add an optional param for rev.

# File lib/cloudant/client.rb, line 83
def delete_design_doc(id)
  doc = get_design_doc(id)
  rev = doc["_rev"] if doc && doc["_rev"]

  @conn.query({url_path: "#{database}/_design/#{id}?rev=#{rev}", opts: doc, method: :delete})
end
delete_doc(id) click to toggle source

Intended behavior for this method to accept only an id to delete a doc. TODO: Add an optional param for rev.

# File lib/cloudant/client.rb, line 58
def delete_doc(id)
  doc = get_doc(id)
  rev = doc["_rev"] if doc["_rev"]

  @conn.query({url_path: "#{database}/#{id}?rev=#{rev}", method: :delete})
end
Also aliased as: delete
delete_docs(docs_array) click to toggle source

Requires the original doc including id and rev fields. Accepts and array of docs. Unlike :delete_doc, this doesn't make a request to get the docs beforehand and won't accept just ids.

# File lib/cloudant/client.rb, line 186
def delete_docs(docs_array)
  docs_array.each { |doc| doc["_deleted"] = true }
  bulk_docs(docs_array)
end
delete_index(args) click to toggle source

Delete an index

# File lib/cloudant/client.rb, line 163
def delete_index(args)
  @conn.query({url_path: "#{database}/_index/#{args[:ddoc]}/#{args[:type]}/#{args[:name]}", method: :delete})
end
doc(id,*opts)
Alias for: get_doc
get(id,*opts)
Alias for: get_doc
get_current_rev(doc) click to toggle source
# File lib/cloudant/client.rb, line 35
def get_current_rev(doc)
  retrieved = get_doc(doc)
  retrieved["_rev"]
end
get_design_doc(id) click to toggle source

Convenience method: this is functionally equivalent to get_doc if “/_design” is prepended to the id. ie: get_doc(“/_design/:id”) == get_design_doc(“:id”)

# File lib/cloudant/client.rb, line 69
def get_design_doc(id)
  @conn.query({url_path: "#{database}/_design/#{id}", method: :get})
end
Also aliased as: ddoc
get_doc(id,*opts) click to toggle source

Accepts a single document id and returns it if found

# File lib/cloudant/client.rb, line 26
def get_doc(id,*opts)
  q = "#{database}/#{id}"
  q << build_query_string(opts.first,"doc") if opts && opts.any? && opts.first.is_a?(Hash)

  @conn.query({url_path: q, method: :get})
end
Also aliased as: get, doc
get_indexes()
Alias for: get_indices
get_indices() click to toggle source

Returns all in order of creation

# File lib/cloudant/client.rb, line 157
def get_indices
  @conn.query({url_path: "#{database}/_index", method: :get})
end
Also aliased as: get_indexes
info()
Alias for: db_info
post(doc)
Alias for: create_doc
put(doc)
Alias for: update_doc
query(q) click to toggle source

Query the database. Returns all found results at once. TODO: Expand query functionality.

# File lib/cloudant/client.rb, line 193
def query(q)
  @conn.query({url_path: "#{database}/_find", opts: q, method: :post})
end
update_design_doc(id,doc)
Alias for: create_design_doc
update_doc(doc) click to toggle source

Returns an error hash if a valid id isn't given

# File lib/cloudant/client.rb, line 49
def update_doc(doc)
  id = doc["_id"] if doc["_id"]

  @conn.query({url_path: "#{database}/#{id}", opts: doc, method: :put})
end
Also aliased as: put
update_docs(docs_array)
Alias for: create_docs
view(ddoc,view,*opts) click to toggle source

Use an existing view. Accepts an options hash containing valid args for a query string. If no options are given the returned value will be the value of the view's reduce function, if it has one, or rows containing keys, ids, and values if not.

# File lib/cloudant/client.rb, line 170
def view(ddoc,view,*opts)
  q  = "#{database}/_design/#{ddoc}/_view/#{view}"
  q << build_query_string(opts.first,"view") if opts && opts.any? && opts.first.is_a?(Hash)

  @conn.query({url_path: q, method: :get})
end

Private Instance Methods

bulk_docs(docs) click to toggle source
# File lib/cloudant/client.rb, line 225
def bulk_docs(docs)
  opts = { "docs" => docs }
  @conn.query({url_path: "#{database}/_bulk_docs", opts: opts, method: :post})
end
set_views(response,doc) click to toggle source
# File lib/cloudant/client.rb, line 230
def set_views(response,doc)
  response["views"] = {} unless response["views"]
  response["views"] = response["views"].merge(doc)
  response
end
start_connection(username,password,base_uri) click to toggle source
# File lib/cloudant/client.rb, line 221
def start_connection(username,password,base_uri)
  Connection.new({username: username, password: password, base_uri: base_uri})
end