elastic-app-search 7.4.0 → 7.8.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +332 -34
- data/lib/elastic/app-search/client.rb +18 -2
- data/lib/elastic/app-search/client/analytics.rb +25 -0
- data/lib/elastic/app-search/client/click.rb +15 -0
- data/lib/elastic/app-search/client/credentials.rb +35 -0
- data/lib/elastic/app-search/client/curations.rb +35 -0
- data/lib/elastic/app-search/client/engines.rb +2 -0
- data/lib/elastic/app-search/client/logs.rb +15 -0
- data/lib/elastic/app-search/client/meta_engines.rb +23 -0
- data/lib/elastic/app-search/client/schema.rb +20 -0
- data/lib/elastic/app-search/client/synonyms.rb +35 -0
- data/lib/elastic/app-search/version.rb +1 -1
- data/spec/analytics_spec.rb +82 -0
- data/spec/click_spec.rb +30 -0
- data/spec/client_spec.rb +27 -455
- data/spec/config_helper.rb +4 -0
- data/spec/credentials_spec.rb +75 -0
- data/spec/curations_spec.rb +82 -0
- data/spec/documents_spec.rb +130 -0
- data/spec/engines_spec.rb +74 -0
- data/spec/list_documents_spec.rb +25 -0
- data/spec/logs_spec.rb +33 -0
- data/spec/meta_engines_spec.rb +73 -0
- data/spec/query_suggestion_spec.rb +37 -0
- data/spec/schema_spec.rb +23 -0
- data/spec/search_settings_spec.rb +65 -0
- data/spec/search_spec.rb +96 -0
- data/spec/spec_helper.rb +73 -0
- data/spec/synonyms_spec.rb +65 -0
- metadata +39 -4
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 3ace14a91577b5aa735c0fa0949830c7c79e02fba58ed7cf3c51b2189a74abbd
|
4
|
+
data.tar.gz: 3af818ab74bd2485069f2f3adcdb7edd595d91a23960fd4a68cce7f1fbc52f3e
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 7f4a064d8e3e556f746cfcb9c7fe50753951aa2d7b75a05d91f5073b36520c019d1f8e1ea0d73927730193cfa0e7c75d73fa9dde9f8f3a8f24aff0ef7d26b8e1
|
7
|
+
data.tar.gz: c87f7b6b9a72115bcc76d5f903bc5d7dafd00c680670ed2fcf15faef7dcc9b7dd59d6b2e7df6a9d2a66d6c91fcca81c75cfc1b8b12dfb4529d3ed3991b5c141e
|
data/README.md
CHANGED
@@ -2,7 +2,7 @@
|
|
2
2
|
|
3
3
|
<p align="center"><a href="https://circleci.com/gh/elastic/app-search-ruby"><img src="https://circleci.com/gh/elastic/app-search-ruby.svg?style=svg" alt="CircleCI build"></a></p>
|
4
4
|
|
5
|
-
> A first-party Ruby client for building excellent, relevant search experiences with Elastic App Search.
|
5
|
+
> A first-party Ruby client for building excellent, relevant search experiences with [Elastic App Search](https://www.elastic.co/products/app-search).
|
6
6
|
|
7
7
|
## Contents
|
8
8
|
|
@@ -25,7 +25,7 @@ To install the gem, execute:
|
|
25
25
|
gem install elastic-app-search
|
26
26
|
```
|
27
27
|
|
28
|
-
Or place `gem 'elastic-app-search', '~> 7.
|
28
|
+
Or place `gem 'elastic-app-search', '~> 7.8.0'` in your `Gemfile` and run `bundle install`.
|
29
29
|
|
30
30
|
## Versioning
|
31
31
|
|
@@ -35,34 +35,37 @@ To guarantee compatibility, use the most recent version of this library within t
|
|
35
35
|
|
36
36
|
For example, for App Search `7.3`, use `7.3` of this library or above, but not `8.0`.
|
37
37
|
|
38
|
-
If you are
|
38
|
+
If you are using the [SaaS version available on swiftype.com](https://app.swiftype.com/as) of App Search, you should use the version 7.5.x of the client.
|
39
39
|
|
40
40
|
## Usage
|
41
41
|
|
42
|
-
|
42
|
+
#### Setup: Configuring the client and authentication
|
43
43
|
|
44
|
-
|
45
|
-
identifies the unique hostname of the App Search API that is associated with your App Search account.
|
46
|
-
It also requires a valid `[API_KEY]`, which authenticates requests to the API. You can use any key type with the client, however each has a different scope. For more information on keys, check out the [documentation](https://swiftype.com/documentation/app-search/credentials).
|
44
|
+
Using this client assumes that you have already an instance of [Elastic App Search](https://www.elastic.co/products/app-search) up and running.
|
47
45
|
|
48
|
-
|
46
|
+
Once done, a client can be instantiated using the `[API_KEY]` and the `[API_ENDPOINT]` URL of your App Search setup:
|
49
47
|
|
50
48
|
```ruby
|
51
49
|
require 'elastic-app-search'
|
52
50
|
|
53
|
-
client = Elastic::AppSearch::Client.new(:
|
51
|
+
client = Elastic::AppSearch::Client.new(:api_key => 'private-xxxxxxxxxxxxxxxxxxx', :api_endpoint => 'http://localhost:3002/api/as/v1/')
|
54
52
|
```
|
55
53
|
|
56
|
-
|
54
|
+
Note:
|
57
55
|
|
58
|
-
The
|
59
|
-
|
60
|
-
,
|
56
|
+
The `[API_KEY]` authenticates requests to the API.
|
57
|
+
You can use any key type with the client, however each has a different scope.
|
58
|
+
For more information on keys, check out the [documentation](https://swiftype.com/documentation/app-search/api/credentials).
|
59
|
+
|
60
|
+
##### Swiftype.com App Search users:
|
61
|
+
|
62
|
+
When using the [SaaS version available on swiftype.com](https://app.swiftype.com/as) of App Search, you can configure the client using your `[HOST_IDENTIFIER]` instead of the `[API_ENDPOINT]`.
|
63
|
+
The `[HOST_IDENTIFIER]` can be found within the [Credentials](https://app.swiftype.com/as#/credentials) menu.
|
61
64
|
|
62
65
|
```ruby
|
63
66
|
require 'elastic-app-search'
|
64
67
|
|
65
|
-
client = Elastic::AppSearch::Client.new(:
|
68
|
+
client = Elastic::AppSearch::Client.new(:host_identifier => 'host-c5s2mj', :api_key => 'private-xxxxxxxxxxxxxxxxxxx')
|
66
69
|
```
|
67
70
|
|
68
71
|
### API Methods
|
@@ -176,6 +179,33 @@ engine_name = 'favorite-videos'
|
|
176
179
|
client.destroy_engine(engine_name)
|
177
180
|
```
|
178
181
|
|
182
|
+
#### Creating Meta Engines
|
183
|
+
|
184
|
+
```ruby
|
185
|
+
engine_name = 'videos-engine'
|
186
|
+
sources_engines = ['favorite-videos', 'all-videos']
|
187
|
+
|
188
|
+
client.create_meta_engine(engine_name, source_engines)
|
189
|
+
```
|
190
|
+
|
191
|
+
#### Adding Meta Engines Source
|
192
|
+
|
193
|
+
```ruby
|
194
|
+
engine_name = 'videos-engine'
|
195
|
+
sources_engines = ['fun-videos', 'cat-videos']
|
196
|
+
|
197
|
+
client.add_meta_engine_sources(engine_name, source_engines)
|
198
|
+
```
|
199
|
+
|
200
|
+
#### Adding Meta Engines Source
|
201
|
+
|
202
|
+
```ruby
|
203
|
+
engine_name = 'videos-engine'
|
204
|
+
sources_engines = ['nsfw-videos']
|
205
|
+
|
206
|
+
client.delete_meta_engine_sources(engine_name, source_engines)
|
207
|
+
```
|
208
|
+
|
179
209
|
#### Searching
|
180
210
|
|
181
211
|
```ruby
|
@@ -192,7 +222,6 @@ client.search(engine_name, query, options)
|
|
192
222
|
|
193
223
|
```ruby
|
194
224
|
engine_name = 'favorite-videos'
|
195
|
-
|
196
225
|
queries = [{
|
197
226
|
:query => 'cat',
|
198
227
|
:options => { :search_fields => { :title => {} }}
|
@@ -208,7 +237,6 @@ client.multi_search(engine_name, queries)
|
|
208
237
|
|
209
238
|
```ruby
|
210
239
|
engine_name = 'favorite-videos'
|
211
|
-
|
212
240
|
options = {
|
213
241
|
:size => 3,
|
214
242
|
:types => {
|
@@ -233,30 +261,29 @@ client.show_settings(engine_name)
|
|
233
261
|
|
234
262
|
```ruby
|
235
263
|
engine_name = 'favorite-videos'
|
236
|
-
|
237
264
|
settings = {
|
238
|
-
|
239
|
-
|
240
|
-
|
265
|
+
'search_fields' => {
|
266
|
+
'id' => {
|
267
|
+
'weight' => 1
|
241
268
|
},
|
242
|
-
|
243
|
-
|
269
|
+
'url' => {
|
270
|
+
'weight' => 1
|
244
271
|
},
|
245
|
-
|
246
|
-
|
272
|
+
'title' => {
|
273
|
+
'weight' => 1
|
247
274
|
},
|
248
|
-
|
249
|
-
|
275
|
+
'body' => {
|
276
|
+
'weight' => 1
|
250
277
|
},
|
251
278
|
},
|
252
|
-
|
253
|
-
|
279
|
+
'boosts' => {
|
280
|
+
'title' => [
|
254
281
|
{
|
255
|
-
|
256
|
-
|
257
|
-
|
258
|
-
|
259
|
-
|
282
|
+
'type' => 'value',
|
283
|
+
'factor' => 9.5,
|
284
|
+
'operation' => 'multiply',
|
285
|
+
'value' => [
|
286
|
+
'Titanic'
|
260
287
|
]
|
261
288
|
}
|
262
289
|
]
|
@@ -288,14 +315,284 @@ enforced_options = {
|
|
288
315
|
|
289
316
|
signed_search_key = Elastic::AppSearch::Client.create_signed_search_key(public_search_key, public_search_key_name, enforced_options)
|
290
317
|
|
291
|
-
client = Elastic::AppSearch::Client.new(
|
318
|
+
client = Elastic::AppSearch::Client.new(:api_key => signed_search_key, :api_endpoint => 'http://localhost:3002/api/as/v1/')
|
319
|
+
|
292
320
|
client.search('national-parks-demo', 'everglade')
|
293
321
|
```
|
294
322
|
|
323
|
+
#### Log click-through
|
324
|
+
|
325
|
+
Logging a click through
|
326
|
+
|
327
|
+
```ruby
|
328
|
+
engine_name = 'favorite-videos'
|
329
|
+
options = {
|
330
|
+
:query => 'cat videos',
|
331
|
+
:document_id => 'INscMGmhmX4',
|
332
|
+
:request_id => 'e4c4dea0bd7ad3d2f676575ef16dc7d2',
|
333
|
+
:tags => ['firefox', 'web browser']
|
334
|
+
}
|
335
|
+
|
336
|
+
client.log_click_through(engine_name, options)
|
337
|
+
```
|
338
|
+
|
339
|
+
#### Analytics - Number of clicks-throughs received by a document
|
340
|
+
|
341
|
+
```ruby
|
342
|
+
engine_name = 'favorite-videos'
|
343
|
+
options = {
|
344
|
+
:query => 'cats',
|
345
|
+
:page => {
|
346
|
+
:size => 20,
|
347
|
+
},
|
348
|
+
:filters => {
|
349
|
+
:date => {
|
350
|
+
:from => '2019-04-11T00:00:00+00:00',
|
351
|
+
:to => '2019-04-13T00:00:00+00:00'
|
352
|
+
}
|
353
|
+
}
|
354
|
+
}
|
355
|
+
|
356
|
+
client.get_top_clicks_analytics(engine_name, options)
|
357
|
+
```
|
358
|
+
|
359
|
+
#### Analytics - Queries, number of queries, and clicks received
|
360
|
+
|
361
|
+
```ruby
|
362
|
+
engine_name = 'favorite-videos'
|
363
|
+
options = {
|
364
|
+
:page => {
|
365
|
+
:size => 20
|
366
|
+
},
|
367
|
+
:filters => {
|
368
|
+
:date => {
|
369
|
+
:from => '2019-04-11T00:00:00+00:00',
|
370
|
+
:to => '2019-04-13T00:00:00+00:00'
|
371
|
+
}
|
372
|
+
}
|
373
|
+
}
|
374
|
+
|
375
|
+
client.get_top_queries_analytics(engine_name, options)
|
376
|
+
```
|
377
|
+
|
378
|
+
#### Analytics - Number of clicks and total number of queries
|
379
|
+
|
380
|
+
```ruby
|
381
|
+
engine_name = 'favorite-videos'
|
382
|
+
options = {
|
383
|
+
:filters => {
|
384
|
+
:all => [
|
385
|
+
{
|
386
|
+
:tag => ['mobile', 'web']
|
387
|
+
},{
|
388
|
+
:query => 'cats'
|
389
|
+
}, {
|
390
|
+
:document_id => '163'
|
391
|
+
}, {
|
392
|
+
:date => {
|
393
|
+
:from => '2018-07-05T12:00:00+00:00',
|
394
|
+
:to => '2018-07-05T14:00:00+00:00'
|
395
|
+
}
|
396
|
+
}
|
397
|
+
]
|
398
|
+
},
|
399
|
+
:interval => 'hour'
|
400
|
+
}
|
401
|
+
|
402
|
+
client.get_count_analytics(engine_name, options)
|
403
|
+
```
|
404
|
+
|
405
|
+
#### Creating Synonym Sets
|
406
|
+
|
407
|
+
```ruby
|
408
|
+
engine_name = 'us-national-parks'
|
409
|
+
|
410
|
+
client.create_synonym_set(engine_name, :synonyms => ['park', 'trail'])
|
411
|
+
```
|
412
|
+
|
413
|
+
#### Retrieving Synonym Sets
|
414
|
+
|
415
|
+
```ruby
|
416
|
+
engine_name = 'us-national-parks'
|
417
|
+
|
418
|
+
client.get_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c')
|
419
|
+
```
|
420
|
+
|
421
|
+
#### Listing Synonym Sets
|
422
|
+
|
423
|
+
```ruby
|
424
|
+
engine_name = 'us-national-parks'
|
425
|
+
|
426
|
+
client.list_synonym_sets(engine_name, :current => 1, :size => 20)
|
427
|
+
```
|
428
|
+
|
429
|
+
#### Updating Synonym Sets
|
430
|
+
|
431
|
+
```ruby
|
432
|
+
engine_name = 'us-national-parks'
|
433
|
+
|
434
|
+
client.update_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c', :synonyms => ['park', 'trail', 'ground'])
|
435
|
+
```
|
436
|
+
|
437
|
+
#### Destroying Synonym Sets
|
438
|
+
|
439
|
+
```ruby
|
440
|
+
engine_name = 'us-national-parks'
|
441
|
+
|
442
|
+
client.destroy_synonym_set(engine_name, 'syn-5d8e6b5d40caae7dcb6e1b9c')
|
443
|
+
```
|
444
|
+
|
445
|
+
#### Listing Credentials
|
446
|
+
|
447
|
+
```ruby
|
448
|
+
client.list_credentials(:current => 1, :size => 20)
|
449
|
+
```
|
450
|
+
|
451
|
+
#### Retrieving Credentials
|
452
|
+
|
453
|
+
```ruby
|
454
|
+
client.get_credential('reading-private-key')
|
455
|
+
```
|
456
|
+
|
457
|
+
#### Creating Credentials
|
458
|
+
|
459
|
+
```ruby
|
460
|
+
client.create_credential({
|
461
|
+
:name => 'reading-private-key',
|
462
|
+
:type => 'private',
|
463
|
+
:read => true,
|
464
|
+
:write => false,
|
465
|
+
:access_all_engines => false,
|
466
|
+
:engines => [
|
467
|
+
'favorite-videos'
|
468
|
+
]
|
469
|
+
})
|
470
|
+
```
|
471
|
+
|
472
|
+
#### Updating Credentials
|
473
|
+
|
474
|
+
```ruby
|
475
|
+
client.update_credential('reading-private-key', {
|
476
|
+
:name => 'reading-private-key',
|
477
|
+
:type => 'private',
|
478
|
+
:read => true,
|
479
|
+
:write => true,
|
480
|
+
:access_all_engines => false,
|
481
|
+
:engines => [
|
482
|
+
'favorite-videos'
|
483
|
+
]
|
484
|
+
})
|
485
|
+
```
|
486
|
+
|
487
|
+
#### Destroying Credentials
|
488
|
+
|
489
|
+
```ruby
|
490
|
+
client.destroy_credential('reading-private-key')
|
491
|
+
```
|
492
|
+
|
493
|
+
#### Retrieving an Engine's Schema
|
494
|
+
|
495
|
+
```ruby
|
496
|
+
engine_name = 'us-national-parks'
|
497
|
+
|
498
|
+
client.get_schema(engine_name)
|
499
|
+
```
|
500
|
+
|
501
|
+
#### Updating an Engine's Schema or Creating a New Schema Field
|
502
|
+
|
503
|
+
```ruby
|
504
|
+
engine_name = 'us-national-parks'
|
505
|
+
|
506
|
+
client.update_schema(engine_name, 'square_km' => 'number')
|
507
|
+
```
|
508
|
+
|
509
|
+
#### Creating Curations
|
510
|
+
|
511
|
+
```ruby
|
512
|
+
engine_name = 'us-national-parks'
|
513
|
+
options = {
|
514
|
+
'queries' => [
|
515
|
+
'zion'
|
516
|
+
],
|
517
|
+
'promoted' => [
|
518
|
+
'doc-5d8e413b40caaedab76e3c96'
|
519
|
+
],
|
520
|
+
'hidden' => [
|
521
|
+
'doc-5d8e413d40caae335e06c374'
|
522
|
+
]
|
523
|
+
}
|
524
|
+
|
525
|
+
client.create_curation(engine_name, options)
|
526
|
+
```
|
527
|
+
|
528
|
+
#### Retrieving Curations
|
529
|
+
|
530
|
+
```ruby
|
531
|
+
engine_name = 'us-national-parks'
|
532
|
+
|
533
|
+
client.get_curation(engine_name, 'cur-5d9240d640caaeca6506b600')
|
534
|
+
```
|
535
|
+
|
536
|
+
#### Listing Curations
|
537
|
+
|
538
|
+
```ruby
|
539
|
+
engine_name = 'us-national-parks'
|
540
|
+
|
541
|
+
client.list_curations(engine_name, current: 1, size: 20)
|
542
|
+
```
|
543
|
+
|
544
|
+
#### Updating Curations
|
545
|
+
|
546
|
+
```ruby
|
547
|
+
engine_name = 'us-national-parks'
|
548
|
+
id = 'cur-5d9240d640caaeca6506b600'
|
549
|
+
options = {
|
550
|
+
'queries' => [
|
551
|
+
'zion'
|
552
|
+
],
|
553
|
+
'promoted' => [
|
554
|
+
'doc-5d8e413b40caaedab76e3c96'
|
555
|
+
]
|
556
|
+
}
|
557
|
+
|
558
|
+
client.update_curation(engine_name, id, options)
|
559
|
+
```
|
560
|
+
|
561
|
+
#### Destroying Curations
|
562
|
+
|
563
|
+
```ruby
|
564
|
+
engine_name = 'us-national-parks'
|
565
|
+
|
566
|
+
client.destroy_curation(engine_name, 'cur-5d9240d640caaeca6506b600')
|
567
|
+
```
|
568
|
+
|
569
|
+
#### Retrieving API Logs
|
570
|
+
|
571
|
+
```ruby
|
572
|
+
engine_name = 'us-national-parks'
|
573
|
+
options = {
|
574
|
+
'filters' => {
|
575
|
+
'date' => {
|
576
|
+
'from' => '2019-09-23T00:00:00+00:00',
|
577
|
+
'to' => '2019-09-28T00:00:00+00:00'
|
578
|
+
}
|
579
|
+
},
|
580
|
+
'page' => {
|
581
|
+
'total_results' => 100,
|
582
|
+
'size' => 20
|
583
|
+
},
|
584
|
+
'query' => 'search',
|
585
|
+
'sort_direction' => 'desc'
|
586
|
+
}
|
587
|
+
|
588
|
+
client.get_api_logs(engine_name, options)
|
589
|
+
```
|
590
|
+
|
295
591
|
## Running Tests
|
296
592
|
|
297
593
|
```bash
|
298
594
|
export AS_API_KEY="[API_KEY]"
|
595
|
+
export AS_ADMIN_KEY="[ADMIN_API_KEY]"
|
299
596
|
export AS_HOST_IDENTIFIER="[HOST_IDENTIFIER]"
|
300
597
|
bundle exec rspec
|
301
598
|
```
|
@@ -304,6 +601,7 @@ You can also run tests against a local environment by passing a `AS_API_ENDPOINT
|
|
304
601
|
|
305
602
|
```bash
|
306
603
|
export AS_API_KEY="[API_KEY]"
|
604
|
+
export AS_ADMIN_KEY="[ADMIN_API_KEY]"
|
307
605
|
export AS_API_ENDPOINT="http://[HOST_IDENTIFIER].api.127.0.0.1.ip.es.io:3002/api/as/v1"
|
308
606
|
bundle exec rspec
|
309
607
|
```
|