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 Attachment

#create_attachment, #delete_attachment, make_attachment, #read_attachment

Methods included from Replicator

#active_tasks, #build_doc, #replicate_db, #replicate_dbs, #replication, #sync

Methods included from Security

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

Methods included from QueryBuilder

#build_attachment_query, #build_query_string, #get_fields

Methods included from Utility

generate_doc_name

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



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

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.



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# 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) ⇒ Object

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



101
102
103
104
105
106
 
# 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 ⇒ Object

Delete the current cookie.



216
217
218
 
# File 'lib/cloudant/client.rb', line 216

def close
  @conn.close
end

#create_db(database) ⇒ Object

Create a new database for the current Cloudant instance



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

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.



75
76
77
 
# 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

#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.



42
43
44
 
# File 'lib/cloudant/client.rb', line 42

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.



178
179
180
 
# File 'lib/cloudant/client.rb', line 178

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)



130
131
132
133
134
135
136
137
138
 
# 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) ⇒ 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.



143
144
145
146
147
148
149
150
151
152
153
154
 
# 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) ⇒ 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.



93
94
95
96
97
98
 
# 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 ⇒ Object Also known as: info

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



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

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

#delete_db(database) ⇒ Object 



124
125
126
 
# File 'lib/cloudant/client.rb', line 124

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.



83
84
85
86
87
88
 
# 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) ⇒ 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.



58
59
60
61
62
63
 
# 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

#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.



186
187
188
189
 
# 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) ⇒ Object

Delete an index



163
164
165
 
# 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

#get_current_rev(doc) ⇒ Object 



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

def get_current_rev(doc)
  retrieved = get_doc(doc)
  retrieved["_rev"]
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”)



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

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



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

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.



193
194
195
 
# File 'lib/cloudant/client.rb', line 193

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



49
50
51
52
53
 
# 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

#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.



170
171
172
173
174
175
 
# 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