gcloud 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. checksums.yaml +8 -8
  2. data/CHANGELOG.md +8 -0
  3. data/lib/gcloud.rb +48 -30
  4. data/lib/gcloud/bigquery.rb +4 -6
  5. data/lib/gcloud/bigquery/connection.rb +2 -14
  6. data/lib/gcloud/bigquery/dataset.rb +41 -42
  7. data/lib/gcloud/bigquery/project.rb +50 -46
  8. data/lib/gcloud/bigquery/query_job.rb +7 -8
  9. data/lib/gcloud/bigquery/table.rb +54 -55
  10. data/lib/gcloud/bigquery/table/schema.rb +30 -40
  11. data/lib/gcloud/bigquery/view.rb +10 -11
  12. data/lib/gcloud/credentials.rb +19 -25
  13. data/lib/gcloud/datastore.rb +4 -6
  14. data/lib/gcloud/datastore/dataset.rb +3 -5
  15. data/lib/gcloud/dns.rb +4 -6
  16. data/lib/gcloud/dns/connection.rb +17 -16
  17. data/lib/gcloud/dns/importer.rb +5 -11
  18. data/lib/gcloud/dns/project.rb +11 -12
  19. data/lib/gcloud/dns/zone.rb +52 -92
  20. data/lib/gcloud/dns/zone/transaction.rb +2 -2
  21. data/lib/gcloud/pubsub.rb +4 -6
  22. data/lib/gcloud/pubsub/connection.rb +1 -12
  23. data/lib/gcloud/pubsub/project.rb +30 -36
  24. data/lib/gcloud/pubsub/subscription.rb +18 -26
  25. data/lib/gcloud/pubsub/topic.rb +16 -26
  26. data/lib/gcloud/resource_manager.rb +5 -6
  27. data/lib/gcloud/resource_manager/connection.rb +4 -4
  28. data/lib/gcloud/resource_manager/manager.rb +10 -14
  29. data/lib/gcloud/resource_manager/project.rb +3 -5
  30. data/lib/gcloud/search.rb +295 -0
  31. data/lib/gcloud/search/api_client.rb +144 -0
  32. data/lib/gcloud/search/connection.rb +146 -0
  33. data/lib/gcloud/search/credentials.rb +30 -0
  34. data/lib/gcloud/search/document.rb +301 -0
  35. data/lib/gcloud/search/document/list.rb +85 -0
  36. data/lib/gcloud/search/errors.rb +67 -0
  37. data/lib/gcloud/search/field_value.rb +164 -0
  38. data/lib/gcloud/search/field_values.rb +263 -0
  39. data/lib/gcloud/search/fields.rb +267 -0
  40. data/lib/gcloud/search/index.rb +613 -0
  41. data/lib/gcloud/search/index/list.rb +90 -0
  42. data/lib/gcloud/search/project.rb +197 -0
  43. data/lib/gcloud/search/result.rb +169 -0
  44. data/lib/gcloud/search/result/list.rb +95 -0
  45. data/lib/gcloud/storage.rb +4 -6
  46. data/lib/gcloud/storage/bucket.rb +55 -43
  47. data/lib/gcloud/storage/bucket/cors.rb +5 -7
  48. data/lib/gcloud/storage/file.rb +35 -30
  49. data/lib/gcloud/storage/file/acl.rb +12 -16
  50. data/lib/gcloud/storage/project.rb +56 -22
  51. data/lib/gcloud/version.rb +1 -1
  52. metadata +20 -3
@@ -199,18 +199,16 @@ module Gcloud
199
199
  #
200
200
  # === Parameters
201
201
  #
202
- # +options+::
203
- # An optional Hash for controlling additional behavior. (+Hash+)
204
- # <code>options[:immediate]</code>::
202
+ # +immediate+::
205
203
  # When +true+ the system will respond immediately even if it is not able
206
204
  # to return messages. When +false+ the system is allowed to wait until
207
205
  # it can return least one message. No messages are returned when a
208
206
  # request times out. The default value is +true+. (+Boolean+)
209
- # <code>options[:max]</code>::
207
+ # +max+::
210
208
  # The maximum number of messages to return for this request. The Pub/Sub
211
209
  # system may return fewer than the number specified. The default value
212
210
  # is +100+, the maximum value is +1000+. (+Integer+)
213
- # <code>options[:autoack]</code>::
211
+ # +autoack+::
214
212
  # Automatically acknowledge the message as it is pulled. The default
215
213
  # value is +false+. (+Boolean+)
216
214
  #
@@ -250,14 +248,15 @@ module Gcloud
250
248
  # msgs = sub.pull immediate: false
251
249
  # msgs.each { |msg| msg.acknowledge! }
252
250
  #
253
- def pull options = {}
251
+ def pull immediate: true, max: 100, autoack: false
254
252
  ensure_connection!
253
+ options = { immediate: immediate, max: max }
255
254
  resp = connection.pull name, options
256
255
  if resp.success?
257
256
  messages = Array(resp.data["receivedMessages"]).map do |gapi|
258
257
  ReceivedMessage.from_gapi gapi, self
259
258
  end
260
- acknowledge messages if options[:autoack]
259
+ acknowledge messages if autoack
261
260
  messages
262
261
  else
263
262
  fail ApiError.from_response(resp)
@@ -274,13 +273,11 @@ module Gcloud
274
273
  #
275
274
  # === Parameters
276
275
  #
277
- # +options+::
278
- # An optional Hash for controlling additional behavior. (+Hash+)
279
- # <code>options[:max]</code>::
276
+ # +max+::
280
277
  # The maximum number of messages to return for this request. The Pub/Sub
281
278
  # system may return fewer than the number specified. The default value
282
279
  # is +100+, the maximum value is +1000+. (+Integer+)
283
- # <code>options[:autoack]</code>::
280
+ # +autoack+::
284
281
  # Automatically acknowledge the message as it is pulled. The default
285
282
  # value is +false+. (+Boolean+)
286
283
  #
@@ -299,8 +296,8 @@ module Gcloud
299
296
  # msgs = sub.wait_for_messages
300
297
  # msgs.each { |msg| msg.acknowledge! }
301
298
  #
302
- def wait_for_messages options = {}
303
- pull options.merge(immediate: false)
299
+ def wait_for_messages max: 100, autoack: false
300
+ pull immediate: false, max: max, autoack: autoack
304
301
  end
305
302
 
306
303
  ##
@@ -309,16 +306,14 @@ module Gcloud
309
306
  #
310
307
  # === Parameters
311
308
  #
312
- # +options+::
313
- # An optional Hash for controlling additional behavior. (+Hash+)
314
- # <code>options[:max]</code>::
309
+ # +max+::
315
310
  # The maximum number of messages to return for this request. The Pub/Sub
316
311
  # system may return fewer than the number specified. The default value
317
312
  # is +100+, the maximum value is +1000+. (+Integer+)
318
- # <code>options[:autoack]</code>::
313
+ # +autoack+::
319
314
  # Automatically acknowledge the message as it is pulled. The default
320
315
  # value is +false+. (+Boolean+)
321
- # <code>options[:delay]</code>::
316
+ # +delay+::
322
317
  # The number of seconds to pause between requests when the Google Cloud
323
318
  # service has no messages to return. The default value is +1+.
324
319
  # (+Number+)
@@ -361,10 +356,9 @@ module Gcloud
361
356
  # # process msg
362
357
  # end
363
358
  #
364
- def listen options = {}
365
- delay = options.fetch(:delay, 1)
359
+ def listen max: 100, autoack: false, delay: 1
366
360
  loop do
367
- msgs = wait_for_messages options
361
+ msgs = wait_for_messages max: max, autoack: autoack
368
362
  if msgs.any?
369
363
  msgs.each { |msg| yield msg }
370
364
  else
@@ -456,9 +450,7 @@ module Gcloud
456
450
  #
457
451
  # === Parameters
458
452
  #
459
- # +options+::
460
- # An optional Hash for controlling additional behavior. (+Hash+)
461
- # <code>options[:force]</code>::
453
+ # +force+::
462
454
  # Force the latest policy to be retrieved from the Pub/Sub service when
463
455
  # +true. Otherwise the policy will be memoized to reduce the number of
464
456
  # API calls made to the Pub/Sub service. The default is +false+.
@@ -501,8 +493,8 @@ module Gcloud
501
493
  # subscription = pubsub.subscription "my-subscription"
502
494
  # policy = subscription.policy force: true
503
495
  #
504
- def policy options = {}
505
- @policy = nil if options[:force]
496
+ def policy force: nil
497
+ @policy = nil if force
506
498
  @policy ||= begin
507
499
  ensure_connection!
508
500
  resp = connection.get_subscription_policy name
@@ -108,12 +108,10 @@ module Gcloud
108
108
  # periods (.), tildes (~), plus (+) or percent signs (%). It must be
109
109
  # between 3 and 255 characters in length, and it must not start with
110
110
  # "goog". (+String+)
111
- # +options+::
112
- # An optional Hash for controlling additional behavior. (+Hash+)
113
- # <code>options[:deadline]</code>::
111
+ # +deadline+::
114
112
  # The maximum number of seconds after a subscriber receives a message
115
113
  # before the subscriber should acknowledge the message. (+Integer+)
116
- # <code>options[:endpoint]</code>::
114
+ # +endpoint+::
117
115
  # A URL locating the endpoint to which messages should be pushed.
118
116
  # e.g. "https://example.com/push" (+String+)
119
117
  #
@@ -156,8 +154,9 @@ module Gcloud
156
154
  # deadline: 120,
157
155
  # endpoint: "https://example.com/push"
158
156
  #
159
- def subscribe subscription_name, options = {}
157
+ def subscribe subscription_name, deadline: nil, endpoint: nil
160
158
  ensure_connection!
159
+ options = { deadline: deadline, endpoint: endpoint }
161
160
  resp = connection.create_subscription name, subscription_name, options
162
161
  if resp.success?
163
162
  Subscription.from_gapi resp.data, connection
@@ -175,9 +174,7 @@ module Gcloud
175
174
  #
176
175
  # +subscription_name+::
177
176
  # Name of a subscription. (+String+)
178
- # +options+::
179
- # An optional Hash for controlling additional behavior. (+Hash+)
180
- # <code>options[:skip_lookup]</code>::
177
+ # +skip_lookup+::
181
178
  # Optionally create a Subscription object without verifying the
182
179
  # subscription resource exists on the Pub/Sub service. Calls made on
183
180
  # this object will raise errors if the service resource does not exist.
@@ -210,10 +207,10 @@ module Gcloud
210
207
  # subscription = pubsub.subscription "my-sub", skip_lookup: true
211
208
  # puts subscription.name
212
209
  #
213
- def subscription subscription_name, options = {}
210
+ def subscription subscription_name, skip_lookup: nil
214
211
  ensure_connection!
215
- if options[:skip_lookup]
216
- return Subscription.new_lazy(subscription_name, connection, options)
212
+ if skip_lookup
213
+ return Subscription.new_lazy(subscription_name, connection)
217
214
  end
218
215
  resp = connection.get_subscription subscription_name
219
216
  return Subscription.from_gapi(resp.data, connection) if resp.success?
@@ -228,13 +225,11 @@ module Gcloud
228
225
  #
229
226
  # === Parameters
230
227
  #
231
- # +options+::
232
- # An optional Hash for controlling additional behavior. (+Hash+)
233
- # <code>options[:token]</code>::
228
+ # +token+::
234
229
  # The +token+ value returned by the last call to +subscriptions+;
235
230
  # indicates that this is a continuation of a call, and that the system
236
231
  # should return the next page of data. (+String+)
237
- # <code>options[:max]</code>::
232
+ # +max+::
238
233
  # Maximum number of subscriptions to return. (+Integer+)
239
234
  #
240
235
  # === Returns
@@ -275,8 +270,9 @@ module Gcloud
275
270
  # tmp_subs = topic.subscriptions token: tmp_subs.token
276
271
  # end
277
272
  #
278
- def subscriptions options = {}
273
+ def subscriptions token: nil, max: nil
279
274
  ensure_connection!
275
+ options = { token: token, max: max }
280
276
  resp = connection.list_topics_subscriptions name, options
281
277
  if resp.success?
282
278
  Subscription::List.from_response resp, connection
@@ -351,9 +347,7 @@ module Gcloud
351
347
  #
352
348
  # === Parameters
353
349
  #
354
- # +options+::
355
- # An optional Hash for controlling additional behavior. (+Hash+)
356
- # <code>options[:force]</code>::
350
+ # +force+::
357
351
  # Force the latest policy to be retrieved from the Pub/Sub service when
358
352
  # +true. Otherwise the policy will be memoized to reduce the number of
359
353
  # API calls made to the Pub/Sub service. The default is +false+.
@@ -396,8 +390,8 @@ module Gcloud
396
390
  # topic = pubsub.topic "my-topic"
397
391
  # policy = topic.policy force: true
398
392
  #
399
- def policy options = {}
400
- @policy = nil if options[:force]
393
+ def policy force: nil
394
+ @policy = nil if force
401
395
  @policy ||= begin
402
396
  ensure_connection!
403
397
  resp = connection.get_topic_policy name
@@ -612,11 +606,7 @@ module Gcloud
612
606
  ##
613
607
  # Make the hash look like it was returned from the Cloud API.
614
608
  def jsonify_hash hash
615
- if hash.respond_to? :to_h
616
- hash = hash.to_h
617
- else
618
- hash = Hash.try_convert(hash) || {}
619
- end
609
+ hash = (hash || {}).to_h
620
610
  return hash if hash.empty?
621
611
  JSON.parse(JSON.dump(hash))
622
612
  end
@@ -27,9 +27,7 @@ module Gcloud
27
27
  # +keyfile+::
28
28
  # Keyfile downloaded from Google Cloud. If file path the file must be
29
29
  # readable. (+String+ or +Hash+)
30
- # +options+::
31
- # An optional Hash for controlling additional behavior. (+Hash+)
32
- # <code>options[:scope]</code>::
30
+ # +scope+::
33
31
  # The OAuth 2.0 scopes controlling the set of resources and operations that
34
32
  # the connection can access. See {Using OAuth 2.0 to Access Google
35
33
  # APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
@@ -52,11 +50,12 @@ module Gcloud
52
50
  # puts projects.project_id
53
51
  # end
54
52
  #
55
- def self.resource_manager keyfile = nil, options = {}
53
+ def self.resource_manager keyfile = nil, scope: nil
56
54
  if keyfile.nil?
57
- credentials = Gcloud::ResourceManager::Credentials.default options
55
+ credentials = Gcloud::ResourceManager::Credentials.default scope: scope
58
56
  else
59
- credentials = Gcloud::ResourceManager::Credentials.new keyfile, options
57
+ credentials = Gcloud::ResourceManager::Credentials.new keyfile,
58
+ scope: scope
60
59
  end
61
60
  Gcloud::ResourceManager::Manager.new credentials
62
61
  end
@@ -36,10 +36,10 @@ module Gcloud
36
36
  @res_man = @client.discovered_api "cloudresourcemanager", API_VERSION
37
37
  end
38
38
 
39
- def list_project options = {}
40
- params = { filter: options.delete(:filter),
41
- pageToken: options.delete(:token),
42
- maxResults: options.delete(:max)
39
+ def list_project filter: nil, token: nil, max: nil
40
+ params = { filter: filter,
41
+ pageToken: token,
42
+ maxResults: max
43
43
  }.delete_if { |_, v| v.nil? }
44
44
 
45
45
  @client.execute(
@@ -54,9 +54,7 @@ module Gcloud
54
54
  #
55
55
  # === Parameters
56
56
  #
57
- # +options+::
58
- # An optional Hash for controlling additional behavior. (+Hash+)
59
- # <code>options[:filter]</code>::
57
+ # +filter+::
60
58
  # An expression for filtering the results of the request. Filter rules
61
59
  # are case insensitive. (+String+)
62
60
  #
@@ -74,10 +72,10 @@ module Gcloud
74
72
  # * +labels.color:red+ - The project's label color has the value red.
75
73
  # * <code>labels.color:red labels.size:big</code> - The project's label
76
74
  # color has the value red and its label size has the value big.
77
- # <code>options[:token]</code>::
75
+ # +token+::
78
76
  # A previously-returned page token representing part of the larger set
79
77
  # of results to view. (+String+)
80
- # <code>options[:max]</code>::
78
+ # +max+::
81
79
  # Maximum number of projects to return. (+Integer+)
82
80
  #
83
81
  # === Returns
@@ -119,8 +117,8 @@ module Gcloud
119
117
  # puts project.project_id
120
118
  # end
121
119
  #
122
- def projects options = {}
123
- resp = connection.list_project options
120
+ def projects filter: nil, token: nil, max: nil
121
+ resp = connection.list_project filter: filter, token: token, max: max
124
122
  if resp.success?
125
123
  Project::List.from_response resp, self
126
124
  else
@@ -174,16 +172,14 @@ module Gcloud
174
172
  # The unique, user-assigned ID of the project. It must be 6 to 30
175
173
  # lowercase letters, digits, or hyphens. It must start with a letter.
176
174
  # Trailing hyphens are prohibited. (+String+)
177
- # +options+::
178
- # An optional Hash for controlling additional behavior. (+Hash+)
179
- # <code>options[:name]</code>::
175
+ # +name+::
180
176
  # The user-assigned name of the project. This field is optional and can
181
177
  # remain unset.
182
178
  #
183
179
  # Allowed characters are: lowercase and uppercase letters, numbers,
184
180
  # hyphen, single-quote, double-quote, space, and exclamation point.
185
181
  # (+String+)
186
- # <code>options[:labels]</code>::
182
+ # +labels+::
187
183
  # The labels associated with this project.
188
184
  #
189
185
  # Label keys must be between 1 and 63 characters long and must conform
@@ -218,10 +214,10 @@ module Gcloud
218
214
  # name: "Todos Development",
219
215
  # labels: {env: :development}
220
216
  #
221
- def create_project project_id, options = {}
217
+ def create_project project_id, name: nil, labels: nil
222
218
  resp = connection.create_project project_id,
223
- options[:name],
224
- options[:labels]
219
+ name,
220
+ labels
225
221
  if resp.success?
226
222
  Project.from_gapi resp.data, connection
227
223
  else
@@ -366,9 +366,7 @@ module Gcloud
366
366
  #
367
367
  # === Parameters
368
368
  #
369
- # +options+::
370
- # An optional Hash for controlling additional behavior. (+Hash+)
371
- # <code>options[:force]</code>::
369
+ # +force+::
372
370
  # Force load the latest policy when +true+. Otherwise the policy will be
373
371
  # memoized to reduce the number of API calls made. The default is
374
372
  # +false+. (+Boolean+)
@@ -411,8 +409,8 @@ module Gcloud
411
409
  # project = resource_manager.project "tokyo-rain-123"
412
410
  # policy = project.policy force: true
413
411
  #
414
- def policy options = {}
415
- @policy = nil if options[:force]
412
+ def policy force: nil
413
+ @policy = nil if force
416
414
  @policy ||= begin
417
415
  ensure_connection!
418
416
  resp = connection.get_policy project_id
@@ -0,0 +1,295 @@
1
+ # Copyright 2015 Google Inc. All rights reserved.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ require "gcloud"
16
+ require "gcloud/search/project"
17
+
18
+ #--
19
+ # Google Cloud Search
20
+ module Gcloud
21
+ ##
22
+ # Creates a new +Project+ instance connected to the Search service.
23
+ # Each call creates a new connection.
24
+ #
25
+ # === Parameters
26
+ #
27
+ # +project+::
28
+ # Identifier for a Search project. If not present, the default project for
29
+ # the credentials is used. (+String+)
30
+ # +keyfile+::
31
+ # Keyfile downloaded from Google Cloud. If file path the file must be
32
+ # readable. (+String+ or +Hash+)
33
+ # +scope::
34
+ # The OAuth 2.0 scopes controlling the set of resources and operations that
35
+ # the connection can access. See {Using OAuth 2.0 to Access Google
36
+ # APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
37
+ # or +Array+)
38
+ #
39
+ # The default scopes are:
40
+ #
41
+ # * +https://www.googleapis.com/auth/cloudsearch+
42
+ # * +https://www.googleapis.com/auth/userinfo.email+
43
+ #
44
+ # === Returns
45
+ #
46
+ # Gcloud::Search::Project
47
+ def self.search project = nil, keyfile = nil, scope: nil
48
+ project ||= Gcloud::Search::Project.default_project
49
+ if keyfile.nil?
50
+ credentials = Gcloud::Search::Credentials.default scope: scope
51
+ else
52
+ credentials = Gcloud::Search::Credentials.new keyfile, scope: scope
53
+ end
54
+ Gcloud::Search::Project.new project, credentials
55
+ end
56
+
57
+ # rubocop:disable Metrics/LineLength
58
+ # Disabled because there are links in the docs that are long.
59
+
60
+ ##
61
+ # = Google Cloud Search
62
+ #
63
+ # Google Cloud Search allows an application to quickly perform full-text and
64
+ # geo-spatial searches without having to spin up instances and without the
65
+ # hassle of managing and maintaining a search service.
66
+ #
67
+ # Cloud Search provides a model for indexing documents containing structured
68
+ # data, with documents and indexes saved to a separate persistent store
69
+ # optimized for search operations. The API supports full text matching on
70
+ # string fields and allows indexing any number of documents in any number of
71
+ # indexes.
72
+ #
73
+ # The Cloud Search API is an Alpha release, and might be changed in
74
+ # backward-incompatible ways. It is not currently recommended for production
75
+ # use. It is not subject to any SLA or deprecation policy.
76
+ #
77
+ # == Accessing the Service
78
+ #
79
+ # Currently, the Cloud Search API is available only to white-listed users.
80
+ # Contact your account manager or a member of the Google Cloud sales team if
81
+ # you are interested in access.
82
+ #
83
+ # == Authentication
84
+ #
85
+ # Authentication is handled by Gcloud#search. You can provide the project and
86
+ # credential information to connect to the Cloud Search service, or if you are
87
+ # running on Google Compute Engine this configuration is taken care of for
88
+ # you. You can read more about the options for connecting in the
89
+ # {Authentication Guide}[link:AUTHENTICATION.md].
90
+ #
91
+ # == Managing Indexes
92
+ #
93
+ # An Index is a searchable collection of documents that belongs to a Project.
94
+ #
95
+ # You can list the indexes in your current project:
96
+ #
97
+ # require "gcloud"
98
+ #
99
+ # gcloud = Gcloud.new
100
+ # search = gcloud.search
101
+ #
102
+ # indexes = search.indexes # API call
103
+ # indexes.each do |index|
104
+ # puts index.index_id
105
+ # end
106
+ #
107
+ # And you can use the project to create new indexes:
108
+ #
109
+ # require "gcloud"
110
+ #
111
+ # gcloud = Gcloud.new
112
+ # search = gcloud.search
113
+ #
114
+ # index = search.index "products", skip_lookup: true
115
+ #
116
+ # A new index is an unsaved value object. Indexes cannot be created,
117
+ # updated, or deleted directly in the service: They are derived from the
118
+ # documents which are created "within" them. A new index will exist in the
119
+ # service once you save a document that references it.
120
+ #
121
+ # == Managing Documents
122
+ #
123
+ # Using an index, create a new, unsaved Document instance, providing
124
+ # your own unique document ID, as shown below, or omitting this argument to
125
+ # let the service assign the ID.
126
+ #
127
+ # require "gcloud"
128
+ #
129
+ # gcloud = Gcloud.new
130
+ # search = gcloud.search
131
+ #
132
+ # index = search.index "products"
133
+ # document = index.document "product-sku-000001"
134
+ # index.find document # API call
135
+ # #=> nil
136
+ # document.rank #=> nil
137
+ #
138
+ # Add one or more fields to the document. (See {Adding document fields}[#module-Gcloud::Search-label-Adding+document+fields], below.)
139
+ #
140
+ # document.add "price", 24.95
141
+ #
142
+ # When your document is complete, save it:
143
+ #
144
+ # index.save document # API call
145
+ # document.rank # set by the server
146
+ # #=> 1443648166
147
+ #
148
+ # You can list the documents in an index:
149
+ #
150
+ # require "gcloud"
151
+ #
152
+ # gcloud = Gcloud.new
153
+ # search = gcloud.search
154
+ # index = search.index "products"
155
+ #
156
+ # documents = index.documents # API call
157
+ # documents.map &:doc_id #=> ["product-sku-000001"]
158
+ #
159
+ # And you can delete documents:
160
+ #
161
+ # require "gcloud"
162
+ #
163
+ # gcloud = Gcloud.new
164
+ # search = gcloud.search
165
+ # index = search.index "products"
166
+ #
167
+ # document = index.find "product-sku-000001"
168
+ #
169
+ # document.delete # API call
170
+ # index.find document # API call
171
+ # #=> nil
172
+ #
173
+ # To update a document after manipulating its fields or rank, just re-save it:
174
+ #
175
+ # require "gcloud"
176
+ #
177
+ # gcloud = Gcloud.new
178
+ # search = gcloud.search
179
+ # index = search.index "products"
180
+ #
181
+ # document = index.find "product-sku-000001"
182
+ #
183
+ # document.rank = 12345
184
+ # document.add "price", 9.95 # replace existing number value
185
+ # index.save document # API call
186
+ #
187
+ # == Adding document fields
188
+ #
189
+ # Fields belong to documents and are the data that actually gets searched.
190
+ # Each field has a FieldValues collection, which facilitates access to
191
+ # FieldValue objects. Each FieldValue object will be saved as one of the
192
+ # {Cloud Search types}[https://cloud.google.com/search/documents_indexes#document_fields_field_names_and_multi-valued_fields].
193
+ # The type will be inferred from the value when possible, or you can
194
+ # explicitly specify it by passing a symbol with the +type+ option to
195
+ # Document#add.
196
+ #
197
+ # - String (+:atom+, +:html+, +:text+, or +:default+)
198
+ # - Number (+:number+)
199
+ # - Timestamp (+:datetime+)
200
+ # - Geovalue (+:geo+)
201
+ #
202
+ # String values can be tokenized using one of three different types of
203
+ # tokenization, which can be passed with the +type+ option when the value is
204
+ # added:
205
+ #
206
+ # - +:atom+ means "don't tokenize this string", treat it as one
207
+ # thing to compare against
208
+ #
209
+ # - +:html+ means "treat this string as HTML", not comparing against the
210
+ # tags, and treating the rest of the content like +:text+
211
+ #
212
+ # - +:text+ means "treat this string as normal text" and split words
213
+ # apart to be compared against
214
+ #
215
+ # Again, you can add more than one value to a field, and the values may be of
216
+ # different types.
217
+ #
218
+ # require "gcloud"
219
+ #
220
+ # gcloud = Gcloud.new
221
+ # search = gcloud.search
222
+ #
223
+ # index = search.index "products"
224
+ # document = index.find "product-sku-000001"
225
+ # document.add "description", "The best T-shirt ever.", type: :text, lang: "en"
226
+ # document.add "description", "<p>The best T-shirt ever.</p>", type: :html, lang: "en"
227
+ # document["description"].size #=> 2
228
+ #
229
+ # == Searching
230
+ #
231
+ # After populating an index with documents, you can request search results
232
+ # with a query:
233
+ #
234
+ # require "gcloud"
235
+ #
236
+ # gcloud = Gcloud.new
237
+ # search = gcloud.search
238
+ # index = search.index "books"
239
+ #
240
+ # results = index.search "dark stormy"
241
+ # results.each do |result|
242
+ # puts result.doc_id
243
+ # end
244
+ #
245
+ # By default, Result objects are sorted by document rank. For more information
246
+ # see the {REST API documentation for Document.rank}[https://cloud.google.com/search/reference/rest/v1/projects/indexes/documents#resource_representation.google.cloudsearch.v1.Document.rank].
247
+ #
248
+ # You can specify how to sort results with the +order+ option:
249
+ #
250
+ # require "gcloud"
251
+ #
252
+ # gcloud = Gcloud.new
253
+ # search = gcloud.search
254
+ # index = search.index "books"
255
+ #
256
+ # results = index.search "dark stormy", order: "published, avg_review desc"
257
+ # documents = index.search query # API call
258
+ #
259
+ # You can add computed fields with the +expressions+ option, and specify the
260
+ # fields that are returned with the +fields+ option. No document data will be
261
+ # returned if you omit the +fields+ option, only `doc_id` references to any
262
+ # matched documents.
263
+ #
264
+ # require "gcloud"
265
+ #
266
+ # gcloud = Gcloud.new
267
+ # search = gcloud.search
268
+ # index = search.index "products"
269
+ #
270
+ # results = index.search "cotton T-shirt",
271
+ # expressions: { total_price: "(price + tax)" },
272
+ # fields: ["name", "total_price", "highlight"]
273
+ #
274
+ # Just as in documents, Result data is accessible via Fields methods:
275
+ #
276
+ # require "gcloud"
277
+ #
278
+ # gcloud = Gcloud.new
279
+ # search = gcloud.search
280
+ # index = search.index "products"
281
+ # document = index.find "product-sku-000001"
282
+ # results = index.search "cotton T-shirt"
283
+ # values = results[0]["description"]
284
+ #
285
+ # values[0] #=> "100% organic cotton ruby gem T-shirt"
286
+ # values[0].type #=> :text
287
+ # values[0].lang #=> "en"
288
+ # values[1] #=> "<p>100% organic cotton ruby gem T-shirt</p>"
289
+ # values[1].type #=> :html
290
+ # values[1].lang #=> "en"
291
+ #
292
+ module Search
293
+ end
294
+ # rubocop:enable Metrics/LineLength
295
+ end