Class: Cloudant::Client

Inherits:
Object
  • Object
show all
Includes:
API
Defined in:
lib/cloudant/client.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Security

check_roles, #create_api_keys, #delete_user, #new_user, #permissions, #roles, #update_roles

Methods included from QueryBuilder

#build_query_string, #get_fields

Constructor Details

#initialize(args) ⇒ Client

Returns a new instance of Client.



7
8
9
10
11
12
13
14
15
 
# 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

Instance Attribute Details

#base_uri ⇒ Object

Returns the value of attribute base_uri.



4
5
6
 
# File 'lib/cloudant/client.rb', line 4

def base_uri
  @base_uri
end

#database ⇒ Object

Returns the value of attribute database.



4
5
6
 
# File 'lib/cloudant/client.rb', line 4

def database
  @database
end

#password ⇒ Object (readonly)

Returns the value of attribute password.



5
6
7
 
# File 'lib/cloudant/client.rb', line 5

def password
  @password
end

#username ⇒ Object (readonly)

Returns the value of attribute username.



5
6
7
 
# File 'lib/cloudant/client.rb', line 5

def username
  @username
end

Instance Method Details

#all_dbs ⇒ Object

Returns all database for the current instance of Cloudant



104
105
106
 
# File 'lib/cloudant/client.rb', line 104

def all_dbs
  @conn.query({url_path: "_all_dbs", method: :get})
end

#all_docs(*opts) ⇒ Object

Retrieve all docs from the database



18
19
20
21
22
23
 
# 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, &blk) ⇒ Object

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



194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/cloudant/client.rb', line 194

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) ⇒ Object

Get a hash => [], containing a hash of seq, id, changes



96
97
98
99
100
101
 
# File 'lib/cloudant/client.rb', line 96

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 ⇒ Object

Delete the current cookie.



211
212
213
 
# File 'lib/cloudant/client.rb', line 211

def close
  @conn.close
end

#create_db(database) ⇒ Object

Create a new database for the current Cloudant instance



115
116
117
 
# File 'lib/cloudant/client.rb', line 115

def create_db(database)
  @conn.query({url_path: database, method: :put})
end

#create_design_doc(id, doc) ⇒ Object Also known as: update_design_doc, create_ddoc

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



70
71
72
 
# File 'lib/cloudant/client.rb', line 70

def create_design_doc(id,doc)
  @conn.query({url_path: "#{database}/_design/#{id}", opts: doc, method: :put})
end

#create_doc(doc) ⇒ Object Also known as: create, post

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



37
38
39
 
# File 'lib/cloudant/client.rb', line 37

def create_doc(doc)
  @conn.query({url_path: "#{database}", opts: doc, method: :post})
end

#create_docs(docs_array) ⇒ Object Also known as: update_docs

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



173
174
175
 
# File 'lib/cloudant/client.rb', line 173

def create_docs(docs_array)
  bulk_docs(docs_array)
end

#create_index(args) ⇒ Object

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



125
126
127
128
129
130
131
132
133
 
# File 'lib/cloudant/client.rb', line 125

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) ⇒ Object

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



138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/cloudant/client.rb', line 138

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) ⇒ Object

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.



88
89
90
91
92
93
 
# File 'lib/cloudant/client.rb', line 88

def create_view(id,doc)
  resp = get_design_doc(id)
  ddoc = set_views(resp,doc)

  create_design_doc(id,ddoc)
end

#db_info ⇒ Object Also known as: info

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



109
110
111
 
# File 'lib/cloudant/client.rb', line 109

def db_info
  @conn.query({url_path: "#{database}", method: :get})
end

#delete_db(database) ⇒ Object 



119
120
121
 
# File 'lib/cloudant/client.rb', line 119

def delete_db(database)
  @conn.query({url_path: database, method: :delete})
end

#delete_design_doc(id) ⇒ Object

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



78
79
80
81
82
83
 
# File 'lib/cloudant/client.rb', line 78

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) ⇒ Object Also known as: delete

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



53
54
55
56
57
58
 
# File 'lib/cloudant/client.rb', line 53

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

#delete_docs(docs_array) ⇒ Object

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.



181
182
183
184
 
# File 'lib/cloudant/client.rb', line 181

def delete_docs(docs_array)
  docs_array.each { |doc| doc["_deleted"] = true }
  bulk_docs(docs_array)
end

#delete_index(args) ⇒ Object

Delete an index



158
159
160
 
# File 'lib/cloudant/client.rb', line 158

def delete_index(args)
  @conn.query({url_path: "#{database}/_index/#{args[:ddoc]}/#{args[:type]}/#{args[:name]}", method: :delete})
end

#get_design_doc(id) ⇒ Object Also known as: ddoc

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”)



64
65
66
 
# File 'lib/cloudant/client.rb', line 64

def get_design_doc(id)
  @conn.query({url_path: "#{database}/_design/#{id}", method: :get})
end

#get_doc(id, *opts) ⇒ Object Also known as: get, doc

Accepts a single document id and returns it if found



26
27
28
29
30
31
 
# 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

#get_indices ⇒ Object Also known as: get_indexes

Returns all in order of creation



152
153
154
 
# File 'lib/cloudant/client.rb', line 152

def get_indices
  @conn.query({url_path: "#{database}/_index", method: :get})
end

#query(q) ⇒ Object

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



188
189
190
 
# File 'lib/cloudant/client.rb', line 188

def query(q)
  @conn.query({url_path: "#{database}/_find", opts: q, method: :post})
end

#update_doc(doc) ⇒ Object Also known as: put

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



44
45
46
47
48
 
# File 'lib/cloudant/client.rb', line 44

def update_doc(doc)
  id = doc["_id"] if doc["_id"]

  @conn.query({url_path: "#{database}/#{id}", opts: doc, method: :put})
end

#view(ddoc, view, *opts) ⇒ Object

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.



165
166
167
168
169
170
 
# File 'lib/cloudant/client.rb', line 165

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