algoliasearch 1.3.1 → 1.4.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.rspec +1 -0
- data/.travis.yml +8 -2
- data/ChangeLog +4 -0
- data/Gemfile +4 -1
- data/Gemfile.lock +69 -67
- data/README.md +259 -190
- data/lib/algolia/client.rb +30 -21
- data/lib/algolia/index.rb +7 -6
- data/lib/algolia/version.rb +1 -1
- data/lib/algolia/webmock.rb +1 -1
- data/spec/client_spec.rb +19 -1
- data/spec/mock_spec.rb +2 -2
- data/spec/stub_spec.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 60f96e5a2607dcefc2d61bfd860ee85334fc4974
|
|
4
|
+
data.tar.gz: 13a0e314c0fb5df77b4189030e6505e76a7f8924
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 84e2f40e68e6a1114196025eba308416ddcf6156d4bec2bf99cba69a5d0420d279c0d1294df2200eb07c6dc5d0749d3ff943f1c17f80ed62e707799e20dcb796
|
|
7
|
+
data.tar.gz: b2fd8567ef442cd5b987a684fb56a5c83d5b753034a62dffdc551b16a69862ea92d733a95eda3ddf532d2b99105ea8761c48a86e48e8f9fb57a8d58617cef635
|
data/.rspec
CHANGED
data/.travis.yml
CHANGED
data/ChangeLog
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
CHANGELOG
|
|
2
2
|
|
|
3
|
+
2015-03-17 1.4.0
|
|
4
|
+
* High-available DNS: search queries are now targeting "APPID-DSN.algolia.net" first, then the main cluster using NSOne, then the main cluster using Route53.
|
|
5
|
+
Indexing queries are targeting "APPID.algolia.net" first, then the main cluster using NSOne, then the main cluster using Route53.
|
|
6
|
+
|
|
3
7
|
2014-11-29 1.3.1
|
|
4
8
|
* Fixed wrong deployed version (1.3.0 was based on 1.2.13 instead of 1.2.14)
|
|
5
9
|
|
data/Gemfile
CHANGED
|
@@ -5,13 +5,16 @@ gem 'json', '>= 1.5.1'
|
|
|
5
5
|
gem 'rubysl', '~> 2.0', :platform => :rbx
|
|
6
6
|
|
|
7
7
|
group :development do
|
|
8
|
+
gem 'highline', '< 1.7.0'
|
|
8
9
|
gem 'coveralls'
|
|
10
|
+
gem 'safe_yaml', '~> 1.0.4'
|
|
11
|
+
gem 'rest-client', '1.6.8'
|
|
9
12
|
gem 'travis'
|
|
10
13
|
gem 'rake'
|
|
11
14
|
gem 'rdoc'
|
|
12
15
|
end
|
|
13
16
|
|
|
14
|
-
group :test do
|
|
17
|
+
group :test do
|
|
15
18
|
gem 'rspec', '>= 2.5.0'
|
|
16
19
|
gem 'autotest'
|
|
17
20
|
gem 'autotest-fsevent'
|
data/Gemfile.lock
CHANGED
|
@@ -1,35 +1,35 @@
|
|
|
1
1
|
GEM
|
|
2
2
|
remote: http://rubygems.org/
|
|
3
3
|
specs:
|
|
4
|
-
ZenTest (4.
|
|
5
|
-
addressable (2.3.
|
|
4
|
+
ZenTest (4.11.0)
|
|
5
|
+
addressable (2.3.7)
|
|
6
6
|
autotest (4.4.6)
|
|
7
7
|
ZenTest (>= 4.4.1)
|
|
8
|
-
autotest-fsevent (0.2.
|
|
8
|
+
autotest-fsevent (0.2.10)
|
|
9
9
|
sys-uname
|
|
10
10
|
autotest-growl (0.2.16)
|
|
11
|
-
backports (3.6.
|
|
11
|
+
backports (3.6.4)
|
|
12
12
|
coderay (1.1.0)
|
|
13
|
-
coveralls (0.7.
|
|
14
|
-
multi_json (~> 1.
|
|
15
|
-
rest-client
|
|
16
|
-
simplecov (
|
|
17
|
-
term-ansicolor
|
|
18
|
-
thor
|
|
13
|
+
coveralls (0.7.11)
|
|
14
|
+
multi_json (~> 1.10)
|
|
15
|
+
rest-client (>= 1.6.8, < 2)
|
|
16
|
+
simplecov (~> 0.9.1)
|
|
17
|
+
term-ansicolor (~> 1.3)
|
|
18
|
+
thor (~> 0.19.1)
|
|
19
19
|
crack (0.4.2)
|
|
20
20
|
safe_yaml (~> 1.0.0)
|
|
21
21
|
diff-lcs (1.2.5)
|
|
22
|
-
docile (1.1.
|
|
23
|
-
ethon (0.7.
|
|
22
|
+
docile (1.1.5)
|
|
23
|
+
ethon (0.7.3)
|
|
24
24
|
ffi (>= 1.3.0)
|
|
25
|
-
faraday (0.9.
|
|
25
|
+
faraday (0.9.1)
|
|
26
26
|
multipart-post (>= 1.2, < 3)
|
|
27
27
|
faraday_middleware (0.9.1)
|
|
28
28
|
faraday (>= 0.7.4, < 0.10)
|
|
29
|
-
ffi (1.9.
|
|
30
|
-
ffi (1.9.
|
|
29
|
+
ffi (1.9.6)
|
|
30
|
+
ffi (1.9.6-java)
|
|
31
31
|
ffi2-generators (0.1.1)
|
|
32
|
-
gh (0.
|
|
32
|
+
gh (0.14.0)
|
|
33
33
|
addressable
|
|
34
34
|
backports
|
|
35
35
|
faraday (~> 0.8)
|
|
@@ -37,12 +37,12 @@ GEM
|
|
|
37
37
|
net-http-persistent (>= 2.7)
|
|
38
38
|
net-http-pipeline
|
|
39
39
|
highline (1.6.21)
|
|
40
|
-
httpclient (2.
|
|
41
|
-
json (1.8.
|
|
42
|
-
json (1.8.
|
|
43
|
-
launchy (2.4.
|
|
40
|
+
httpclient (2.6.0.1)
|
|
41
|
+
json (1.8.2)
|
|
42
|
+
json (1.8.2-java)
|
|
43
|
+
launchy (2.4.3)
|
|
44
44
|
addressable (~> 2.3)
|
|
45
|
-
launchy (2.4.
|
|
45
|
+
launchy (2.4.3-java)
|
|
46
46
|
addressable (~> 2.3)
|
|
47
47
|
spoon (~> 0.0.1)
|
|
48
48
|
method_source (0.8.2)
|
|
@@ -63,25 +63,27 @@ GEM
|
|
|
63
63
|
pusher-client (0.6.0)
|
|
64
64
|
json
|
|
65
65
|
websocket (~> 1.0)
|
|
66
|
-
rake (10.
|
|
67
|
-
rdoc (4.
|
|
66
|
+
rake (10.4.2)
|
|
67
|
+
rdoc (4.2.0)
|
|
68
68
|
json (~> 1.4)
|
|
69
69
|
redgreen (1.2.2)
|
|
70
|
-
rest-client (1.6.
|
|
71
|
-
mime-types (
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
rspec-
|
|
75
|
-
rspec-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
70
|
+
rest-client (1.6.8)
|
|
71
|
+
mime-types (~> 1.16)
|
|
72
|
+
rdoc (>= 2.4.2)
|
|
73
|
+
rspec (3.2.0)
|
|
74
|
+
rspec-core (~> 3.2.0)
|
|
75
|
+
rspec-expectations (~> 3.2.0)
|
|
76
|
+
rspec-mocks (~> 3.2.0)
|
|
77
|
+
rspec-core (3.2.1)
|
|
78
|
+
rspec-support (~> 3.2.0)
|
|
79
|
+
rspec-expectations (3.2.0)
|
|
79
80
|
diff-lcs (>= 1.2.0, < 2.0)
|
|
80
|
-
rspec-support (~> 3.
|
|
81
|
-
rspec-mocks (3.
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
81
|
+
rspec-support (~> 3.2.0)
|
|
82
|
+
rspec-mocks (3.2.1)
|
|
83
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
|
84
|
+
rspec-support (~> 3.2.0)
|
|
85
|
+
rspec-support (3.2.2)
|
|
86
|
+
rubysl (2.1.0)
|
|
85
87
|
rubysl-abbrev (~> 2.0)
|
|
86
88
|
rubysl-base64 (~> 2.0)
|
|
87
89
|
rubysl-benchmark (~> 2.0)
|
|
@@ -115,7 +117,7 @@ GEM
|
|
|
115
117
|
rubysl-io-nonblock (~> 2.0)
|
|
116
118
|
rubysl-io-wait (~> 2.0)
|
|
117
119
|
rubysl-ipaddr (~> 2.0)
|
|
118
|
-
rubysl-irb (~> 2.
|
|
120
|
+
rubysl-irb (~> 2.1)
|
|
119
121
|
rubysl-logger (~> 2.0)
|
|
120
122
|
rubysl-mathn (~> 2.0)
|
|
121
123
|
rubysl-matrix (~> 2.0)
|
|
@@ -144,7 +146,6 @@ GEM
|
|
|
144
146
|
rubysl-pstore (~> 2.0)
|
|
145
147
|
rubysl-pty (~> 2.0)
|
|
146
148
|
rubysl-rational (~> 2.0)
|
|
147
|
-
rubysl-readline (~> 2.0)
|
|
148
149
|
rubysl-resolv (~> 2.0)
|
|
149
150
|
rubysl-rexml (~> 2.0)
|
|
150
151
|
rubysl-rinda (~> 2.0)
|
|
@@ -186,14 +187,14 @@ GEM
|
|
|
186
187
|
rubysl-csv (2.0.2)
|
|
187
188
|
rubysl-english (~> 2.0)
|
|
188
189
|
rubysl-curses (2.0.1)
|
|
189
|
-
rubysl-date (2.0.
|
|
190
|
+
rubysl-date (2.0.9)
|
|
190
191
|
rubysl-delegate (2.0.1)
|
|
191
192
|
rubysl-digest (2.0.3)
|
|
192
193
|
rubysl-drb (2.0.1)
|
|
193
194
|
rubysl-e2mmap (2.0.0)
|
|
194
195
|
rubysl-english (2.0.0)
|
|
195
196
|
rubysl-enumerator (2.0.0)
|
|
196
|
-
rubysl-erb (2.0.
|
|
197
|
+
rubysl-erb (2.0.2)
|
|
197
198
|
rubysl-etc (2.0.3)
|
|
198
199
|
ffi2-generators (~> 0.1)
|
|
199
200
|
rubysl-expect (2.0.0)
|
|
@@ -211,12 +212,11 @@ GEM
|
|
|
211
212
|
rubysl-io-nonblock (2.0.0)
|
|
212
213
|
rubysl-io-wait (2.0.0)
|
|
213
214
|
rubysl-ipaddr (2.0.0)
|
|
214
|
-
rubysl-irb (2.
|
|
215
|
+
rubysl-irb (2.1.1)
|
|
215
216
|
rubysl-e2mmap (~> 2.0)
|
|
216
217
|
rubysl-mathn (~> 2.0)
|
|
217
|
-
rubysl-readline (~> 2.0)
|
|
218
218
|
rubysl-thread (~> 2.0)
|
|
219
|
-
rubysl-logger (2.
|
|
219
|
+
rubysl-logger (2.1.0)
|
|
220
220
|
rubysl-mathn (2.0.0)
|
|
221
221
|
rubysl-matrix (2.1.0)
|
|
222
222
|
rubysl-e2mmap (~> 2.0)
|
|
@@ -239,21 +239,20 @@ GEM
|
|
|
239
239
|
rubysl-observer (2.0.0)
|
|
240
240
|
rubysl-open-uri (2.0.0)
|
|
241
241
|
rubysl-open3 (2.0.0)
|
|
242
|
-
rubysl-openssl (2.1
|
|
242
|
+
rubysl-openssl (2.2.1)
|
|
243
243
|
rubysl-optparse (2.0.1)
|
|
244
244
|
rubysl-shellwords (~> 2.0)
|
|
245
245
|
rubysl-ostruct (2.0.4)
|
|
246
|
-
rubysl-pathname (2.
|
|
246
|
+
rubysl-pathname (2.1.0)
|
|
247
247
|
rubysl-prettyprint (2.0.3)
|
|
248
248
|
rubysl-prime (2.0.1)
|
|
249
249
|
rubysl-profile (2.0.0)
|
|
250
250
|
rubysl-profiler (2.0.1)
|
|
251
251
|
rubysl-pstore (2.0.0)
|
|
252
|
-
rubysl-pty (2.0.
|
|
252
|
+
rubysl-pty (2.0.3)
|
|
253
253
|
rubysl-rational (2.0.1)
|
|
254
|
-
rubysl-
|
|
255
|
-
rubysl-
|
|
256
|
-
rubysl-rexml (2.0.2)
|
|
254
|
+
rubysl-resolv (2.1.2)
|
|
255
|
+
rubysl-rexml (2.0.4)
|
|
257
256
|
rubysl-rinda (2.0.1)
|
|
258
257
|
rubysl-rss (2.0.0)
|
|
259
258
|
rubysl-scanf (2.0.0)
|
|
@@ -265,10 +264,10 @@ GEM
|
|
|
265
264
|
rubysl-stringio (2.0.0)
|
|
266
265
|
rubysl-strscan (2.0.0)
|
|
267
266
|
rubysl-sync (2.0.0)
|
|
268
|
-
rubysl-syslog (2.0
|
|
267
|
+
rubysl-syslog (2.1.0)
|
|
269
268
|
ffi2-generators (~> 0.1)
|
|
270
269
|
rubysl-tempfile (2.0.1)
|
|
271
|
-
rubysl-thread (2.0.
|
|
270
|
+
rubysl-thread (2.0.3)
|
|
272
271
|
rubysl-thwait (2.0.0)
|
|
273
272
|
rubysl-time (2.0.3)
|
|
274
273
|
rubysl-timeout (2.0.0)
|
|
@@ -281,15 +280,15 @@ GEM
|
|
|
281
280
|
rubysl-weakref (2.0.0)
|
|
282
281
|
rubysl-webrick (2.0.0)
|
|
283
282
|
rubysl-xmlrpc (2.0.0)
|
|
284
|
-
rubysl-yaml (2.0
|
|
283
|
+
rubysl-yaml (2.1.0)
|
|
285
284
|
rubysl-zlib (2.0.1)
|
|
286
|
-
safe_yaml (1.0.
|
|
287
|
-
simplecov (0.
|
|
285
|
+
safe_yaml (1.0.4)
|
|
286
|
+
simplecov (0.9.2)
|
|
288
287
|
docile (~> 1.1.0)
|
|
289
|
-
multi_json
|
|
290
|
-
simplecov-html (~> 0.
|
|
291
|
-
simplecov-html (0.
|
|
292
|
-
slop (3.
|
|
288
|
+
multi_json (~> 1.0)
|
|
289
|
+
simplecov-html (~> 0.9.0)
|
|
290
|
+
simplecov-html (0.9.0)
|
|
291
|
+
slop (3.6.0)
|
|
293
292
|
spoon (0.0.4)
|
|
294
293
|
ffi
|
|
295
294
|
sys-uname (0.9.2)
|
|
@@ -297,24 +296,24 @@ GEM
|
|
|
297
296
|
term-ansicolor (1.3.0)
|
|
298
297
|
tins (~> 1.0)
|
|
299
298
|
thor (0.19.1)
|
|
300
|
-
tins (1.3.
|
|
301
|
-
travis (1.
|
|
299
|
+
tins (1.3.4)
|
|
300
|
+
travis (1.7.5)
|
|
302
301
|
addressable (~> 2.3)
|
|
303
302
|
backports
|
|
304
303
|
faraday (~> 0.9)
|
|
305
|
-
faraday_middleware (~> 0.9)
|
|
304
|
+
faraday_middleware (~> 0.9, >= 0.9.1)
|
|
306
305
|
gh (~> 0.13)
|
|
307
306
|
highline (~> 1.6)
|
|
308
307
|
launchy (~> 2.1)
|
|
309
|
-
pry (~> 0.9)
|
|
308
|
+
pry (~> 0.9, < 0.10)
|
|
310
309
|
pusher-client (~> 0.4)
|
|
311
310
|
typhoeus (~> 0.6, >= 0.6.8)
|
|
312
|
-
typhoeus (0.
|
|
313
|
-
ethon (>= 0.7.
|
|
314
|
-
webmock (1.
|
|
311
|
+
typhoeus (0.7.1)
|
|
312
|
+
ethon (>= 0.7.1)
|
|
313
|
+
webmock (1.20.4)
|
|
315
314
|
addressable (>= 2.3.6)
|
|
316
315
|
crack (>= 0.3.2)
|
|
317
|
-
websocket (1.1
|
|
316
|
+
websocket (1.2.1)
|
|
318
317
|
|
|
319
318
|
PLATFORMS
|
|
320
319
|
java
|
|
@@ -325,14 +324,17 @@ DEPENDENCIES
|
|
|
325
324
|
autotest-fsevent
|
|
326
325
|
autotest-growl
|
|
327
326
|
coveralls
|
|
327
|
+
highline (< 1.7.0)
|
|
328
328
|
httpclient (~> 2.4)
|
|
329
329
|
json (>= 1.5.1)
|
|
330
330
|
mime-types (< 2.0)
|
|
331
331
|
rake
|
|
332
332
|
rdoc
|
|
333
333
|
redgreen
|
|
334
|
+
rest-client (= 1.6.8)
|
|
334
335
|
rspec (>= 2.5.0)
|
|
335
336
|
rubysl (~> 2.0)
|
|
337
|
+
safe_yaml (~> 1.0.4)
|
|
336
338
|
simplecov
|
|
337
339
|
travis
|
|
338
340
|
webmock
|
data/README.md
CHANGED
|
@@ -1,36 +1,40 @@
|
|
|
1
|
-
Algolia Search API Client for Ruby
|
|
2
|
-
==================
|
|
1
|
+
# Algolia Search API Client for Ruby
|
|
3
2
|
|
|
4
3
|
|
|
5
4
|
|
|
6
|
-
[Algolia Search](http://www.algolia.com) is a
|
|
7
|
-
Algolia
|
|
5
|
+
[Algolia Search](http://www.algolia.com) is a hosted full-text, numerical, and faceted search engine capable of delivering realtime results from the first keystroke.
|
|
6
|
+
Algolia's Search API makes it easy to deliver a great search experience in your websites and mobile applications by providing:
|
|
8
7
|
|
|
9
|
-
* REST and JSON
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
8
|
+
* REST and JSON based API
|
|
9
|
+
* Search against infinite attributes from a single search box
|
|
10
|
+
* Instant search as you type experience
|
|
11
|
+
* Relevance and popularity ranking
|
|
12
|
+
* Global language support
|
|
13
|
+
* Typo tolerance in any language
|
|
14
|
+
* Smart highlighting
|
|
15
|
+
* Facet as you type
|
|
16
|
+
* Geo awareness
|
|
15
17
|
* 99.99% SLA
|
|
16
|
-
*
|
|
18
|
+
* First class data security
|
|
17
19
|
|
|
18
|
-
|
|
20
|
+
Our Ruby client lets you easily use the [Algolia Search API](http://www.algolia.com) from your backend. It wraps the [Algolia Search REST API](http://www.algolia.com/doc/rest_api).
|
|
19
21
|
|
|
20
|
-
|
|
22
|
+
|
|
23
|
+
[](https://travis-ci.org/algolia/algoliasearch-client-ruby) [](http://badge.fury.io/rb/algoliasearch) [](https://codeclimate.com/github/algolia/algoliasearch-client-ruby) [](https://coveralls.io/r/algolia/algoliasearch-client-ruby)
|
|
21
24
|
|
|
22
25
|
|
|
23
26
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
+
|
|
28
|
+
Table of Contents
|
|
29
|
+
=================
|
|
30
|
+
**Getting Started**
|
|
27
31
|
|
|
28
32
|
1. [Setup](#setup)
|
|
29
33
|
1. [Quick Start](#quick-start)
|
|
30
34
|
1. [Online documentation](#documentation)
|
|
31
35
|
1. [Tutorials](#tutorials)
|
|
32
36
|
|
|
33
|
-
**Commands
|
|
37
|
+
**Commands Reference**
|
|
34
38
|
|
|
35
39
|
1. [Add a new object](#add-a-new-object-in-the-index)
|
|
36
40
|
1. [Update an object](#update-an-existing-object-in-the-index)
|
|
@@ -71,6 +75,12 @@ Algolia.init :application_id => "YourApplicationID",
|
|
|
71
75
|
:api_key => "YourAPIKey"
|
|
72
76
|
```
|
|
73
77
|
|
|
78
|
+
### Ruby on Rails
|
|
79
|
+
|
|
80
|
+
If you're a Ruby on Rails user; you're probably looking for the [algoliasearch-rails](https://github.com/algolia/algoliasearch-rails) gem.
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
|
|
74
84
|
|
|
75
85
|
|
|
76
86
|
|
|
@@ -80,16 +90,16 @@ Algolia.init :application_id => "YourApplicationID",
|
|
|
80
90
|
Quick Start
|
|
81
91
|
-------------
|
|
82
92
|
|
|
83
|
-
|
|
93
|
+
In 30 seconds, this quick start tutorial will show you how to index and search objects.
|
|
84
94
|
|
|
85
|
-
Without any prior
|
|
95
|
+
Without any prior configuration, you can start indexing [500 contacts](https://github.com/algolia/algoliasearch-client-csharp/blob/master/contacts.json) in the ```contacts``` index using the following code:
|
|
86
96
|
```ruby
|
|
87
97
|
index = Algolia::Index.new("contacts")
|
|
88
98
|
batch = JSON.parse(File.read("contacts.json"))
|
|
89
99
|
index.add_objects(batch)
|
|
90
100
|
```
|
|
91
101
|
|
|
92
|
-
You can
|
|
102
|
+
You can now search for contacts using firstname, lastname, company, etc. (even with typos):
|
|
93
103
|
```ruby
|
|
94
104
|
# search by firstname
|
|
95
105
|
puts index.search('jimmie').to_json
|
|
@@ -101,7 +111,7 @@ puts index.search('california paint').to_json
|
|
|
101
111
|
puts index.search('jimmie paint').to_json
|
|
102
112
|
```
|
|
103
113
|
|
|
104
|
-
Settings can be customized to tune the search behavior. For example you can add a custom sort by number of followers to the already
|
|
114
|
+
Settings can be customized to tune the search behavior. For example, you can add a custom sort by number of followers to the already great built-in relevance:
|
|
105
115
|
```ruby
|
|
106
116
|
index.set_settings({"customRanking" => ["desc(followers)"]})
|
|
107
117
|
```
|
|
@@ -120,8 +130,8 @@ puts index.search('jim').to_json
|
|
|
120
130
|
|
|
121
131
|
|
|
122
132
|
**Notes:** If you are building a web application, you may be more interested in using our [JavaScript client](https://github.com/algolia/algoliasearch-client-js) to perform queries. It brings two benefits:
|
|
123
|
-
*
|
|
124
|
-
*
|
|
133
|
+
* Your users get a better response time by not going through your servers
|
|
134
|
+
* It will offload unnecessary tasks from your servers.
|
|
125
135
|
|
|
126
136
|
```html
|
|
127
137
|
<script type="text/javascript" src="//path/to/algoliasearch.min.js"></script>
|
|
@@ -169,32 +179,32 @@ Check our [online documentation](http://www.algolia.com/doc/guides/ruby):
|
|
|
169
179
|
Tutorials
|
|
170
180
|
================
|
|
171
181
|
|
|
172
|
-
Check our [tutorials](http://www.algolia.com/doc/tutorials):
|
|
173
|
-
* [
|
|
174
|
-
* [
|
|
175
|
-
* [Instant
|
|
182
|
+
Check out our [tutorials](http://www.algolia.com/doc/tutorials):
|
|
183
|
+
* [Search bar with autocomplete menu](http://www.algolia.com/doc/tutorials/auto-complete)
|
|
184
|
+
* [Search bar with multi category autocomplete menu](http://www.algolia.com/doc/tutorials/multi-auto-complete)
|
|
185
|
+
* [Instant search result pages](http://www.algolia.com/doc/tutorials/instant-search)
|
|
176
186
|
|
|
177
187
|
|
|
178
188
|
|
|
179
|
-
Commands
|
|
189
|
+
Commands Reference
|
|
180
190
|
==================
|
|
181
191
|
|
|
182
192
|
|
|
183
193
|
|
|
184
194
|
|
|
185
195
|
|
|
186
|
-
Add a new object
|
|
196
|
+
Add a new object to the Index
|
|
187
197
|
-------------
|
|
188
198
|
|
|
189
|
-
Each entry in an index has a unique identifier called `objectID`.
|
|
199
|
+
Each entry in an index has a unique identifier called `objectID`. There are two ways to add en entry to the index:
|
|
190
200
|
|
|
191
|
-
1. Using automatic `objectID`
|
|
192
|
-
2.
|
|
201
|
+
1. Using automatic `objectID` assignment. You will be able to access it in the answer.
|
|
202
|
+
2. Supplying your own `objectID`.
|
|
193
203
|
|
|
194
|
-
You don't need to
|
|
195
|
-
Objects are schema less
|
|
204
|
+
You don't need to explicitly create an index, it will be automatically created the first time you add an object.
|
|
205
|
+
Objects are schema less so you don't need any configuration to start indexing. If you wish to configure things, the settings section provides details about advanced settings.
|
|
196
206
|
|
|
197
|
-
Example with automatic `objectID`
|
|
207
|
+
Example with automatic `objectID` assignment:
|
|
198
208
|
|
|
199
209
|
```ruby
|
|
200
210
|
res = index.add_object({"firstname" => "Jimmie",
|
|
@@ -202,7 +212,7 @@ res = index.add_object({"firstname" => "Jimmie",
|
|
|
202
212
|
puts "ObjectID=" + res["objectID"]
|
|
203
213
|
```
|
|
204
214
|
|
|
205
|
-
Example with manual `objectID`
|
|
215
|
+
Example with manual `objectID` assignment:
|
|
206
216
|
|
|
207
217
|
```ruby
|
|
208
218
|
res = index.add_object({"firstname" => "Jimmie",
|
|
@@ -213,12 +223,13 @@ puts "ObjectID=" + res["objectID"]
|
|
|
213
223
|
Update an existing object in the Index
|
|
214
224
|
-------------
|
|
215
225
|
|
|
216
|
-
You have
|
|
226
|
+
You have three options when updating an existing object:
|
|
217
227
|
|
|
218
228
|
1. Replace all its attributes.
|
|
219
229
|
2. Replace only some attributes.
|
|
230
|
+
3. Apply an operation to some attributes.
|
|
220
231
|
|
|
221
|
-
Example to replace all
|
|
232
|
+
Example on how to replace all attributes of an existing object:
|
|
222
233
|
|
|
223
234
|
```ruby
|
|
224
235
|
index.save_object({"firstname" => "Jimmie",
|
|
@@ -227,6 +238,15 @@ index.save_object({"firstname" => "Jimmie",
|
|
|
227
238
|
"objectID" => "myID"})
|
|
228
239
|
```
|
|
229
240
|
|
|
241
|
+
You have many ways to update an object's attributes:
|
|
242
|
+
|
|
243
|
+
1. Set the attribute value
|
|
244
|
+
2. Add an element to an array
|
|
245
|
+
3. Remove an element from an array
|
|
246
|
+
4. Add an element to an array if it doesn't exist
|
|
247
|
+
5. Increment an attribute
|
|
248
|
+
6. Decrement an attribute
|
|
249
|
+
|
|
230
250
|
Example to update only the city attribute of an existing object:
|
|
231
251
|
|
|
232
252
|
```ruby
|
|
@@ -234,92 +254,133 @@ index.partial_update_object({"city" => "San Francisco",
|
|
|
234
254
|
"objectID" => "myID"})
|
|
235
255
|
```
|
|
236
256
|
|
|
257
|
+
Example to add a tag:
|
|
258
|
+
|
|
259
|
+
```ruby
|
|
260
|
+
index.partial_update_object({"_tags" => {"value" => "MyTag", "_operation": "Add"},
|
|
261
|
+
"objectID" => "myID"})
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Example to remove a tag:
|
|
265
|
+
|
|
266
|
+
```ruby
|
|
267
|
+
index.partial_update_object({"_tags" => {"value" => "MyTag", "_operation": "Remove"},
|
|
268
|
+
"objectID" => "myID"})
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Example to add a tag if it doesn't exist:
|
|
272
|
+
|
|
273
|
+
```ruby
|
|
274
|
+
index.partial_update_object({"_tags" => {"value" => "MyTag", "_operation": "AddUnique"},
|
|
275
|
+
"objectID" => "myID"})
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
Example to increment a numeric value:
|
|
279
|
+
|
|
280
|
+
```ruby
|
|
281
|
+
index.partial_update_object({"price" => {"value" => 42, "_operation": "Increment"},
|
|
282
|
+
"objectID" => "myID"})
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Example to decrement a numeric value:
|
|
286
|
+
|
|
287
|
+
```ruby
|
|
288
|
+
index.partial_update_object({"price" => {"value" => 42, "_operation": "Decrement"},
|
|
289
|
+
"objectID" => "myID"})
|
|
290
|
+
```
|
|
291
|
+
|
|
237
292
|
|
|
238
293
|
|
|
239
294
|
Search
|
|
240
295
|
-------------
|
|
241
296
|
|
|
242
|
-
**
|
|
243
|
-
*
|
|
244
|
-
*
|
|
297
|
+
**Notes:** If you are building a web application, you may be more interested in using our [JavaScript client](https://github.com/algolia/algoliasearch-client-js) to perform queries. It brings two benefits:
|
|
298
|
+
* Your users get a better response time by not going through your servers
|
|
299
|
+
* It will offload unnecessary tasks from your servers.
|
|
245
300
|
|
|
246
301
|
|
|
247
|
-
To perform a search, you
|
|
302
|
+
To perform a search, you only need to initialize the index and perform a call to the search function.
|
|
248
303
|
|
|
249
304
|
You can use the following optional arguments:
|
|
250
305
|
|
|
251
|
-
### Query
|
|
252
|
-
|
|
253
|
-
#### Full Text Search
|
|
254
|
-
|
|
255
|
-
* **query**: (string) The instant
|
|
256
|
-
* **queryType**:
|
|
257
|
-
* **prefixAll**:
|
|
258
|
-
* **prefixLast**:
|
|
259
|
-
* **prefixNone**:
|
|
260
|
-
* **removeWordsIfNoResults**: This option to select a strategy to avoid having an empty result page. There
|
|
261
|
-
* **lastWords**:
|
|
262
|
-
* **firstWords**:
|
|
263
|
-
* **
|
|
264
|
-
|
|
265
|
-
* **minWordSizefor1Typo**:
|
|
266
|
-
* **minWordSizefor2Typos**:
|
|
267
|
-
* **allowTyposOnNumericTokens**:
|
|
268
|
-
* **
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
* **
|
|
274
|
-
* **
|
|
275
|
-
* **
|
|
276
|
-
* **
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
* **
|
|
306
|
+
### Query Parameters
|
|
307
|
+
|
|
308
|
+
#### Full Text Search Parameters
|
|
309
|
+
|
|
310
|
+
* **query**: (string) The instant search query string. All words of the query are interpreted as prefixes (for example "John Mc" will match "John Mccamey" and "Johnathan Mccamey"). If no query parameter is set all objects are retrieved.
|
|
311
|
+
* **queryType**: Selects how the query words are interpreted. It can be one of the following values:
|
|
312
|
+
* **prefixAll**: All query words are interpreted as prefixes.
|
|
313
|
+
* **prefixLast**: Only the last word is interpreted as a prefix (default behavior).
|
|
314
|
+
* **prefixNone**: No query word is interpreted as a prefix. This option is not recommended.
|
|
315
|
+
* **removeWordsIfNoResults**: This option is used to select a strategy in order to avoid having an empty result page. There are three different options:
|
|
316
|
+
* **lastWords**: When a query does not return any results, the last word will be added as optional. The process is repeated with n-1 word, n-2 word, ... until there are results.
|
|
317
|
+
* **firstWords**: When a query does not return any results, the first word will be added as optional. The process is repeated with second word, third word, ... until there are results.
|
|
318
|
+
* **allOptional**: When a query does not return any results, a second trial will be made with all words as optional. This is equivalent to transforming the AND operand between query terms to an OR operand.
|
|
319
|
+
* **none**: No specific processing is done when a query does not return any results (default behavior).
|
|
320
|
+
* **minWordSizefor1Typo**: The minimum number of characters in a query word to accept one typo in this word.<br/>Defaults to 4.
|
|
321
|
+
* **minWordSizefor2Typos**: The minimum number of characters in a query word to accept two typos in this word.<br/>Defaults to 8.
|
|
322
|
+
* **allowTyposOnNumericTokens**: If set to false, it disables typo tolerance on numeric tokens (numbers). Defaults to false.
|
|
323
|
+
* **typoTolerance**: This option allows you to control the number of typos in the result set:
|
|
324
|
+
* **true**: The typo tolerance is enabled and all matching hits are retrieved (default behavior).
|
|
325
|
+
* **false**: The typo tolerance is disabled. For example, if one result matches without typos, then all results with typos will be hidden.
|
|
326
|
+
* **min**: Only keep results with the minimum number of typos.
|
|
327
|
+
* **strict**: Hits matching with 2 typos are not retrieved if there are some matching without typos. This option is useful if you want to avoid false positives as much as possible.
|
|
328
|
+
* **allowTyposOnNumericTokens**: If set to false, disables typo tolerance on numeric tokens (numbers). Defaults to true.
|
|
329
|
+
* **ignorePlural**: If set to true, plural won't be considered as a typo. For example, car and cars will be considered as equals. Defaults to false.
|
|
330
|
+
* **restrictSearchableAttributes** List of attributes you want to use for textual search (must be a subset of the `attributesToIndex` index setting). Attributes are separated with a comma such as `"name,address"`. You can also use JSON string array encoding such as `encodeURIComponent("[\"name\",\"address\"]")`. By default, all attributes specified in `attributesToIndex` settings are used to search.
|
|
331
|
+
* **advancedSyntax**: Enables the advanced query syntax. Defaults to 0 (false).
|
|
332
|
+
* **Phrase query**: A phrase query defines a particular sequence of terms. A phrase query is built by Algolia's query parser for words surrounded by `"`. For example, `"search engine"` will retrieve records having `search` next to `engine` only. Typo tolerance is _disabled_ on phrase queries.
|
|
333
|
+
* **Prohibit operator**: The prohibit operator excludes records that contain the term after the `-` symbol. For example, `search -engine` will retrieve records containing `search` but not `engine`.
|
|
334
|
+
* **analytics**: If set to false, this query will not be taken into account in the analytics feature. Defaults to true.
|
|
335
|
+
* **synonyms**: If set to false, this query will not use synonyms defined in the configuration. Defaults to true.
|
|
336
|
+
* **replaceSynonymsInHighlight**: If set to false, words matched via synonym expansion will not be replaced by the matched synonym in the highlight results. Defaults to true.
|
|
337
|
+
* **optionalWords**: A string that contains the comma separated list of words that should be considered as optional when found in the query.
|
|
338
|
+
|
|
339
|
+
#### Pagination Parameters
|
|
340
|
+
|
|
341
|
+
* **page**: (integer) Pagination parameter used to select the page to retrieve.<br/>Page is zero based and defaults to 0. Thus, to retrieve the 10th page you need to set `page=9`.
|
|
281
342
|
* **hitsPerPage**: (integer) Pagination parameter used to select the number of hits per page. Defaults to 20.
|
|
282
343
|
|
|
283
|
-
#### Geo-search
|
|
344
|
+
#### Geo-search Parameters
|
|
284
345
|
|
|
285
|
-
* **aroundLatLng**:
|
|
346
|
+
* **aroundLatLng**: Search for entries around a given latitude/longitude (specified as two floats separated by a comma).<br/>For example, `aroundLatLng=47.316669,5.016670`.<br/>You can specify the maximum distance in meters with the **aroundRadius** parameter and the precision for ranking with **aroundPrecision**. For example, if you set aroundPrecision=100, two objects that are a distance of less than 100 meters will be considered as identical for the "geo" ranking parameter).<br/>At indexing, you should specify the geo location of an object with the `_geoloc` attribute in the form `{"_geoloc":{"lat":48.853409, "lng":2.348800}}`.
|
|
286
347
|
|
|
287
|
-
* **aroundLatLngViaIP**:
|
|
348
|
+
* **aroundLatLngViaIP**: Search for entries around a given latitude/longitude automatically computed from user IP address.<br/>For example, `aroundLatLng=47.316669,5.016670`.<br/>You can specify the maximum distance in meters with the **aroundRadius** parameter and the precision for ranking with **aroundPrecision**. For example, if you set aroundPrecision=100, two objects that are a distance of less than 100 meters will be considered as identical for the "geo" ranking parameter.<br/>At indexing, you should specify the geo location of an object with the `_geoloc` attribute in the form `{"_geoloc":{"lat":48.853409, "lng":2.348800}}`.
|
|
288
349
|
|
|
289
350
|
|
|
290
|
-
* **insideBoundingBox**:
|
|
351
|
+
* **insideBoundingBox**: Search entries inside a given area defined by the two extreme points of a rectangle (defined by 4 floats: p1Lat,p1Lng,p2Lat,p2Lng).<br/>For example, `insideBoundingBox=47.3165,4.9665,47.3424,5.0201`).<br/>At indexing, you should specify the geo location of an object with the _geoloc attribute in the form `{"_geoloc":{"lat":48.853409, "lng":2.348800}}`.
|
|
291
352
|
|
|
292
|
-
#### Parameters to
|
|
353
|
+
#### Parameters to Control Results Content
|
|
293
354
|
|
|
294
|
-
* **attributesToRetrieve**:
|
|
295
|
-
* **attributesToHighlight**:
|
|
296
|
-
* **full**:
|
|
297
|
-
* **partial**:
|
|
298
|
-
* **none**:
|
|
299
|
-
* **attributesToSnippet**:
|
|
300
|
-
* **getRankingInfo**:
|
|
355
|
+
* **attributesToRetrieve**: A string that contains the list of object attributes you want to retrieve in order to minimize the answer size.<br/> Attributes are separated with a comma (for example `"name,address"`). You can also use a string array encoding (for example `["name","address"]` ). By default, all attributes are retrieved. You can also use `*` to retrieve all values when an **attributesToRetrieve** setting is specified for your index.
|
|
356
|
+
* **attributesToHighlight**: A string that contains the list of attributes you want to highlight according to the query. Attributes are separated by commas. You can also use a string array encoding (for example `["name","address"]`). If an attribute has no match for the query, the raw value is returned. By default all indexed text attributes are highlighted. You can use `*` if you want to highlight all textual attributes. Numerical attributes are not highlighted. A matchLevel is returned for each highlighted attribute and can contain:
|
|
357
|
+
* **full**: If all the query terms were found in the attribute.
|
|
358
|
+
* **partial**: If only some of the query terms were found.
|
|
359
|
+
* **none**: If none of the query terms were found.
|
|
360
|
+
* **attributesToSnippet**: A string that contains the list of attributes to snippet alongside the number of words to return (syntax is `attributeName:nbWords`). Attributes are separated by commas (Example: `attributesToSnippet=name:10,content:10`). <br/>You can also use a string array encoding (Example: `attributesToSnippet: ["name:10","content:10"]`). By default, no snippet is computed.
|
|
361
|
+
* **getRankingInfo**: If set to 1, the result hits will contain ranking information in the **_rankingInfo** attribute.
|
|
301
362
|
|
|
302
363
|
|
|
303
|
-
#### Numeric
|
|
304
|
-
* **numericFilters**:
|
|
364
|
+
#### Numeric Search Parameters
|
|
365
|
+
* **numericFilters**: A string that contains the comma separated list of numeric filters you want to apply. The filter syntax is `attributeName` followed by `operand` followed by `value`. Supported operands are `<`, `<=`, `=`, `>` and `>=`.
|
|
305
366
|
|
|
306
|
-
You can easily perform range queries via the `:` operator
|
|
367
|
+
You can easily perform range queries via the `:` operator. This is equivalent to combining a `>=` and `<=` operand. For example, `numericFilters=price:10 to 1000`.
|
|
307
368
|
|
|
308
|
-
You can also mix OR and AND operators. The OR operator is defined with a parenthesis syntax. For example `(code=1 AND (price:[0-100] OR price:[1000-2000]))` translates
|
|
369
|
+
You can also mix OR and AND operators. The OR operator is defined with a parenthesis syntax. For example, `(code=1 AND (price:[0-100] OR price:[1000-2000]))` translates to `encodeURIComponent("code=1,(price:0 to 10,price:1000 to 2000)")`.
|
|
309
370
|
|
|
310
371
|
You can also use a string array encoding (for example `numericFilters: ["price>100","price<1000"]`).
|
|
311
372
|
|
|
312
|
-
#### Category
|
|
313
|
-
* **tagFilters**:
|
|
373
|
+
#### Category Search Parameters
|
|
374
|
+
* **tagFilters**: Filter the query by a set of tags. You can AND tags by separating them with commas. To OR tags, you must add parentheses. For example, `tags=tag1,(tag2,tag3)` means *tag1 AND (tag2 OR tag3)*. You can also use a string array encoding. For example, `tagFilters: ["tag1",["tag2","tag3"]]` means *tag1 AND (tag2 OR tag3)*.<br/>At indexing, tags should be added in the **_tags** attribute of objects. For example `{"_tags":["tag1","tag2"]}`.
|
|
314
375
|
|
|
315
|
-
#### Faceting
|
|
316
|
-
* **facetFilters**:
|
|
317
|
-
* **facets**: List of object attributes that you want to use for faceting. <br/>Attributes are separated with a comma
|
|
318
|
-
* **maxValuesPerFacet**: Limit the number of facet values returned for each facet. For example
|
|
376
|
+
#### Faceting Parameters
|
|
377
|
+
* **facetFilters**: Filter the query with a list of facets. Facets are separated by commas and is encoded as `attributeName:value`. To OR facets, you must add parentheses. For example: `facetFilters=(category:Book,category:Movie),author:John%20Doe`. You can also use a string array encoding. For example, `[["category:Book","category:Movie"],"author:John%20Doe"]`.
|
|
378
|
+
* **facets**: List of object attributes that you want to use for faceting. <br/>Attributes are separated with a comma. For example, `"category,author"`. You can also use JSON string array encoding. For example, `["category","author"]`. Only the attributes that have been added in **attributesForFaceting** index setting can be used in this parameter. You can also use `*` to perform faceting on all attributes specified in **attributesForFaceting**.
|
|
379
|
+
* **maxValuesPerFacet**: Limit the number of facet values returned for each facet. For example, `maxValuesPerFacet=10` will retrieve a maximum of 10 values per facet.
|
|
319
380
|
|
|
320
|
-
#### Distinct
|
|
321
|
-
* **distinct**: If set to 1,
|
|
322
|
-
**Note**: This feature is disabled if the query string is empty and there
|
|
381
|
+
#### Distinct Parameter
|
|
382
|
+
* **distinct**: If set to 1, enables the distinct feature, disabled by default, if the `attributeForDistinct` index setting is set. This feature is similar to the SQL "distinct" keyword. When enabled in a query with the `distinct=1` parameter, all hits containing a duplicate value for the attributeForDistinct attribute are removed from results. For example, if the chosen attribute is `show_name` and several hits have the same value for `show_name`, then only the best one is kept and the others are removed.
|
|
383
|
+
**Note**: This feature is disabled if the query string is empty and there aren't any `tagFilters`, `facetFilters`, nor `numericFilters` parameters.
|
|
323
384
|
|
|
324
385
|
```ruby
|
|
325
386
|
index = Algolia::Index.new("contacts")
|
|
@@ -363,7 +424,7 @@ The server response will look like:
|
|
|
363
424
|
```
|
|
364
425
|
|
|
365
426
|
|
|
366
|
-
|
|
427
|
+
Multiple queries
|
|
367
428
|
--------------
|
|
368
429
|
|
|
369
430
|
You can send multiple queries with a single API call using a batch of queries:
|
|
@@ -381,13 +442,10 @@ puts res["results"]
|
|
|
381
442
|
|
|
382
443
|
|
|
383
444
|
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
445
|
Get an object
|
|
388
446
|
-------------
|
|
389
447
|
|
|
390
|
-
You can easily retrieve an object using its `objectID` and
|
|
448
|
+
You can easily retrieve an object using its `objectID` and optionally specify a comma separated list of attributes you want:
|
|
391
449
|
|
|
392
450
|
```ruby
|
|
393
451
|
# Retrieves all attributes
|
|
@@ -404,6 +462,10 @@ You can also retrieve a set of objects:
|
|
|
404
462
|
res = index.get_objects(["myID", "myID2"])
|
|
405
463
|
```
|
|
406
464
|
|
|
465
|
+
|
|
466
|
+
|
|
467
|
+
|
|
468
|
+
|
|
407
469
|
Delete an object
|
|
408
470
|
-------------
|
|
409
471
|
|
|
@@ -417,7 +479,7 @@ index.delete_object("myID")
|
|
|
417
479
|
Delete by query
|
|
418
480
|
-------------
|
|
419
481
|
|
|
420
|
-
You can delete all objects matching a single query with the following code. Internally, the API client performs the query,
|
|
482
|
+
You can delete all objects matching a single query with the following code. Internally, the API client performs the query, deletes all matching hits, and waits until the deletions have been applied.
|
|
421
483
|
|
|
422
484
|
```ruby
|
|
423
485
|
params = {}
|
|
@@ -428,62 +490,62 @@ index.delete_by_query("John", params)
|
|
|
428
490
|
Index Settings
|
|
429
491
|
-------------
|
|
430
492
|
|
|
431
|
-
You can retrieve all settings using the `get_settings` function. The result will
|
|
493
|
+
You can retrieve all settings using the `get_settings` function. The result will contain the following attributes:
|
|
432
494
|
|
|
433
495
|
|
|
434
496
|
#### Indexing parameters
|
|
435
|
-
* **attributesToIndex**: (array of strings)
|
|
436
|
-
* *Limit the attributes to index*.<br/>For example if you store a binary image in base64, you want to store it and be able to retrieve it but you don't want to search in the base64 string.
|
|
437
|
-
* *Control part of the ranking*.<br/>(see the ranking parameter for full explanation) Matches in attributes at the beginning of the list will be considered more important than matches in attributes further down the list. In one attribute, matching text at the beginning of the attribute will be considered more important than text after
|
|
497
|
+
* **attributesToIndex**: (array of strings) The list of fields you want to index.<br/>If set to null, all textual and numerical attributes of your objects are indexed. Be sure to update it to get optimal results.<br/>This parameter has two important uses:
|
|
498
|
+
* *Limit the attributes to index*.<br/>For example, if you store a binary image in base64, you want to store it and be able to retrieve it, but you don't want to search in the base64 string.
|
|
499
|
+
* *Control part of the ranking*.<br/>(see the ranking parameter for full explanation) Matches in attributes at the beginning of the list will be considered more important than matches in attributes further down the list. In one attribute, matching text at the beginning of the attribute will be considered more important than text after. You can disable this behavior if you add your attribute inside `unordered(AttributeName)`. For example, `attributesToIndex: ["title", "unordered(text)"]`.
|
|
438
500
|
**Notes**: All numerical attributes are automatically indexed as numerical filters. If you don't need filtering on some of your numerical attributes, please consider sending them as strings to speed up the indexing.<br/>
|
|
439
|
-
You can decide to have the same priority for two attributes by passing them in the same string using comma as separator. For example `title` and `alternative_title` have the same priority in this example, which is different than text priority: `attributesToIndex:["title,alternative_title", "text"]
|
|
501
|
+
You can decide to have the same priority for two attributes by passing them in the same string using a comma as a separator. For example `title` and `alternative_title` have the same priority in this example, which is different than text priority: `attributesToIndex:["title,alternative_title", "text"]`.
|
|
440
502
|
* **attributesForFaceting**: (array of strings) The list of fields you want to use for faceting. All strings in the attribute selected for faceting are extracted and added as a facet. If set to null, no attribute is used for faceting.
|
|
441
|
-
* **attributeForDistinct**: The attribute name used for the `Distinct` feature. This feature is similar to the SQL "distinct" keyword
|
|
442
|
-
* **ranking**: (array of strings)
|
|
443
|
-
* **typo**:
|
|
444
|
-
* **geo**:
|
|
445
|
-
* **words**:
|
|
446
|
-
* **proximity**:
|
|
447
|
-
* **attribute**:
|
|
503
|
+
* **attributeForDistinct**: The attribute name used for the `Distinct` feature. This feature is similar to the SQL "distinct" keyword. When enabled in queries with the `distinct=1` parameter, all hits containing a duplicate value for this attribute are removed from results. For example, if the chosen attribute is `show_name` and several hits have the same value for `show_name`, then only the best one is kept and others are removed. **Note**: This feature is disabled if the query string is empty and there aren't any `tagFilters`, `facetFilters`, nor `numericFilters` parameters.
|
|
504
|
+
* **ranking**: (array of strings) Controls the way results are sorted.<br/>We have nine available criteria:
|
|
505
|
+
* **typo**: Sort according to number of typos.
|
|
506
|
+
* **geo**: Sort according to decreasing distance when performing a geo location based search.
|
|
507
|
+
* **words**: Sort according to the number of query words matched by decreasing order. This parameter is useful when you use the `optionalWords` query parameter to have results with the most matched words first.
|
|
508
|
+
* **proximity**: Sort according to the proximity of the query words in hits.
|
|
509
|
+
* **attribute**: Sort according to the order of attributes defined by attributesToIndex.
|
|
448
510
|
* **exact**:
|
|
449
|
-
*
|
|
450
|
-
*
|
|
451
|
-
* **custom**:
|
|
452
|
-
* **asc(attributeName)**:
|
|
453
|
-
* **desc(attributeName)**:
|
|
454
|
-
* **customRanking**: (array of strings)
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
* **
|
|
458
|
-
* **
|
|
459
|
-
|
|
460
|
-
* **slaves**: The list of indices on which you want to replicate all write operations. In order to get response times in milliseconds, we pre-compute part of the ranking during indexing. If you want to use different ranking configurations depending of the use
|
|
461
|
-
* **unretrievableAttributes**: The list of attributes that cannot be retrieved at query time. This feature
|
|
462
|
-
* **allowCompressionOfIntegerArray**: Allows compression of big integer arrays. We recommended
|
|
511
|
+
* If the user query contains one word: sort objects having an attribute that is exactly the query word before others. For example, if you search for the TV show "V", you want to find it with the "V" query and avoid getting all popular TV shows starting by the letter V before it.
|
|
512
|
+
* If the user query contains multiple words: sort according to the number of words that matched exactly (not as a prefix).
|
|
513
|
+
* **custom**: Sort according to a user defined formula set in the **customRanking** attribute.
|
|
514
|
+
* **asc(attributeName)**: Sort according to a numeric attribute using ascending order. **attributeName** can be the name of any numeric attribute in your records (integer, double or boolean).
|
|
515
|
+
* **desc(attributeName)**: Sort according to a numeric attribute using descending order. **attributeName** can be the name of any numeric attribute in your records (integer, double or boolean). <br/>The standard order is ["typo", "geo", "words", "proximity", "attribute", "exact", "custom"].
|
|
516
|
+
* **customRanking**: (array of strings) Lets you specify part of the ranking.<br/>The syntax of this condition is an array of strings containing attributes prefixed by the asc (ascending order) or desc (descending order) operator. For example, `"customRanking" => ["desc(population)", "asc(name)"]`.
|
|
517
|
+
* **queryType**: Select how the query words are interpreted. It can be one of the following values:
|
|
518
|
+
* **prefixAll**: All query words are interpreted as prefixes.
|
|
519
|
+
* **prefixLast**: Only the last word is interpreted as a prefix (default behavior).
|
|
520
|
+
* **prefixNone**: No query word is interpreted as a prefix. This option is not recommended.
|
|
521
|
+
* **separatorsToIndex**: Specify the separators (punctuation characters) to index. By default, separators are not indexed. Use `+#` to be able to search Google+ or C#.
|
|
522
|
+
* **slaves**: The list of indices on which you want to replicate all write operations. In order to get response times in milliseconds, we pre-compute part of the ranking during indexing. If you want to use different ranking configurations depending of the use case, you need to create one index per ranking configuration. This option enables you to perform write operations only on this index and automatically update slave indices with the same operations.
|
|
523
|
+
* **unretrievableAttributes**: The list of attributes that cannot be retrieved at query time. This feature allows you to have attributes that are used for indexing and/or ranking but cannot be retrieved. Defaults to null.
|
|
524
|
+
* **allowCompressionOfIntegerArray**: Allows compression of big integer arrays. We recommended enabling this feature and then storing the list of user IDs or rights as an integer array. When enabled, the integer array is reordered to reach a better compression ratio. Defaults to false.
|
|
463
525
|
|
|
464
526
|
#### Query expansion
|
|
465
|
-
* **synonyms**: (array of array of words considered as equals). For example, you may want to retrieve
|
|
466
|
-
* **placeholders**: (hash of array of words). This is an advanced use case to define a token substitutable by a list of words without having the original token searchable. It is defined by a hash associating placeholders to lists of substitutable words. For example `"placeholders": { "<streetnumber>": ["1", "2", "3", ..., "9999"]}`
|
|
467
|
-
* Push a record with the placeholder: `{ "name" : "Apple Store", "address" : "<streetnumber> Opera street, Paris" }
|
|
527
|
+
* **synonyms**: (array of array of words considered as equals). For example, you may want to retrieve the **black ipad** record when your users are searching for **dark ipad**, even if the word **dark** is not part of the record. To do this, you need to configure **black** as a synonym of **dark**. For example, `"synomyms": [ [ "black", "dark" ], [ "small", "little", "mini" ], ... ]`.
|
|
528
|
+
* **placeholders**: (hash of array of words). This is an advanced use case to define a token substitutable by a list of words without having the original token searchable. It is defined by a hash associating placeholders to lists of substitutable words. For example, `"placeholders": { "<streetnumber>": ["1", "2", "3", ..., "9999"]}` would allow it to be able to match all street numbers. We use the `< >` tag syntax to define placeholders in an attribute. For example:
|
|
529
|
+
* Push a record with the placeholder: `{ "name" : "Apple Store", "address" : "<streetnumber> Opera street, Paris" }`.
|
|
468
530
|
* Configure the placeholder in your index settings: `"placeholders": { "<streetnumber>" : ["1", "2", "3", "4", "5", ... ], ... }`.
|
|
469
|
-
* **disableTypoToleranceOn**: (string array)
|
|
470
|
-
* **altCorrections**: (object array)
|
|
471
|
-
* **word**:
|
|
472
|
-
* **correction**:
|
|
473
|
-
* **nbTypos**
|
|
474
|
-
|
|
475
|
-
For example `"altCorrections": [ { "word" : "foot", "correction": "feet", "nbTypos": 1}, { "word": "feet", "correction": "foot", "nbTypos": 1}]
|
|
476
|
-
|
|
477
|
-
#### Default query parameters (can be
|
|
478
|
-
* **minWordSizefor1Typo**: (integer)
|
|
479
|
-
* **minWordSizefor2Typos**: (integer)
|
|
480
|
-
* **hitsPerPage**: (integer)
|
|
481
|
-
* **attributesToRetrieve**: (array of strings)
|
|
482
|
-
* **attributesToHighlight**: (array of strings)
|
|
483
|
-
* **attributesToSnippet**: (array of strings)
|
|
484
|
-
* **highlightPreTag**: (string) Specify the string that is inserted before the highlighted parts in the query result (
|
|
485
|
-
* **highlightPostTag**: (string) Specify the string that is inserted after the highlighted parts in the query result (
|
|
486
|
-
* **optionalWords**: (array of strings) Specify a list of words that should be considered
|
|
531
|
+
* **disableTypoToleranceOn**: (string array) Specify a list of words on which automatic typo tolerance will be disabled.
|
|
532
|
+
* **altCorrections**: (object array) Specify alternative corrections that you want to consider. Each alternative correction is described by an object containing three attributes:
|
|
533
|
+
* **word**: The word to correct.
|
|
534
|
+
* **correction**: The corrected word.
|
|
535
|
+
* **nbTypos** The number of typos (1 or 2) that will be considered for the ranking algorithm (1 typo is better than 2 typos).
|
|
536
|
+
|
|
537
|
+
For example `"altCorrections": [ { "word" : "foot", "correction": "feet", "nbTypos": 1 }, { "word": "feet", "correction": "foot", "nbTypos": 1 } ]`.
|
|
538
|
+
|
|
539
|
+
#### Default query parameters (can be overwritten by queries)
|
|
540
|
+
* **minWordSizefor1Typo**: (integer) The minimum number of characters needed to accept one typo (default = 4).
|
|
541
|
+
* **minWordSizefor2Typos**: (integer) The minimum number of characters needed to accept two typos (default = 8).
|
|
542
|
+
* **hitsPerPage**: (integer) The number of hits per page (default = 10).
|
|
543
|
+
* **attributesToRetrieve**: (array of strings) Default list of attributes to retrieve in objects. If set to null, all attributes are retrieved.
|
|
544
|
+
* **attributesToHighlight**: (array of strings) Default list of attributes to highlight. If set to null, all indexed attributes are highlighted.
|
|
545
|
+
* **attributesToSnippet**: (array of strings) Default list of attributes to snippet alongside the number of words to return (syntax is 'attributeName:nbWords').<br/>By default, no snippet is computed. If set to null, no snippet is computed.
|
|
546
|
+
* **highlightPreTag**: (string) Specify the string that is inserted before the highlighted parts in the query result (defaults to "<em>").
|
|
547
|
+
* **highlightPostTag**: (string) Specify the string that is inserted after the highlighted parts in the query result (defaults to "</em>").
|
|
548
|
+
* **optionalWords**: (array of strings) Specify a list of words that should be considered optional when found in the query.
|
|
487
549
|
|
|
488
550
|
You can easily retrieve settings or update them:
|
|
489
551
|
|
|
@@ -498,7 +560,7 @@ index.set_settings({"customRanking" => ["desc(followers)"]})
|
|
|
498
560
|
|
|
499
561
|
List indices
|
|
500
562
|
-------------
|
|
501
|
-
You can list all your indices with their associated information (number of entries, disk size, etc.) with the `list_indexes` method:
|
|
563
|
+
You can list all your indices along with their associated information (number of entries, disk size, etc.) with the `list_indexes` method:
|
|
502
564
|
|
|
503
565
|
```ruby
|
|
504
566
|
Algolia.list_indexes
|
|
@@ -515,7 +577,7 @@ index.delete_index
|
|
|
515
577
|
|
|
516
578
|
Clear an index
|
|
517
579
|
-------------
|
|
518
|
-
You can delete the index
|
|
580
|
+
You can delete the index contents without removing settings and index specific API keys by using the clearIndex command:
|
|
519
581
|
|
|
520
582
|
```ruby
|
|
521
583
|
index.clear_index
|
|
@@ -533,19 +595,19 @@ res = index.add_object!({"firstname" => "Jimmie",
|
|
|
533
595
|
```
|
|
534
596
|
|
|
535
597
|
|
|
536
|
-
If you want to ensure multiple objects have been indexed, you
|
|
598
|
+
If you want to ensure multiple objects have been indexed, you only need check the biggest taskID with `wait_task`.
|
|
537
599
|
|
|
538
600
|
Batch writes
|
|
539
601
|
-------------
|
|
540
602
|
|
|
541
603
|
You may want to perform multiple operations with one API call to reduce latency.
|
|
542
|
-
We expose three methods to perform batch:
|
|
543
|
-
* `add_objects`:
|
|
544
|
-
* `save_objects`:
|
|
545
|
-
* `delete_objects`:
|
|
546
|
-
* `partial_update_objects`:
|
|
604
|
+
We expose three methods to perform batch operations:
|
|
605
|
+
* `add_objects`: Add an array of objects using automatic `objectID` assignment.
|
|
606
|
+
* `save_objects`: Add or update an array of objects that contains an `objectID` attribute.
|
|
607
|
+
* `delete_objects`: Delete an array of objectIDs.
|
|
608
|
+
* `partial_update_objects`: Partially update an array of objects that contain an `objectID` attribute (only specified attributes will be updated).
|
|
547
609
|
|
|
548
|
-
Example using automatic `objectID`
|
|
610
|
+
Example using automatic `objectID` assignment:
|
|
549
611
|
```ruby
|
|
550
612
|
res = index.add_objects([{"firstname" => "Jimmie",
|
|
551
613
|
"lastname" => "Barninger"},
|
|
@@ -563,12 +625,12 @@ res = index.save_objects([{"firstname" => "Jimmie",
|
|
|
563
625
|
"objectID" => "myID2"}])
|
|
564
626
|
```
|
|
565
627
|
|
|
566
|
-
Example that
|
|
628
|
+
Example that deletes a set of records:
|
|
567
629
|
```ruby
|
|
568
630
|
res = index.delete_objects(["myID1", "myID2"])
|
|
569
631
|
```
|
|
570
632
|
|
|
571
|
-
Example that
|
|
633
|
+
Example that updates only the `firstname` attribute:
|
|
572
634
|
```ruby
|
|
573
635
|
res = index.partial_update_objects([{"firstname" => "Jimmie",
|
|
574
636
|
"objectID" => "SFO"},
|
|
@@ -593,14 +655,16 @@ Algolia.list_user_keys
|
|
|
593
655
|
index.list_user_keys
|
|
594
656
|
```
|
|
595
657
|
|
|
596
|
-
Each key is defined by a set of
|
|
597
|
-
* **search**:
|
|
598
|
-
* **browse**:
|
|
599
|
-
* **addObject**:
|
|
600
|
-
* **deleteObject**:
|
|
601
|
-
* **deleteIndex**:
|
|
602
|
-
* **settings**: allows to get index settings
|
|
603
|
-
* **editSettings**:
|
|
658
|
+
Each key is defined by a set of permissions that specify the authorized actions. The different permissions are:
|
|
659
|
+
* **search**: Allowed to search.
|
|
660
|
+
* **browse**: Allowed to retrieve all index contents via the browse API.
|
|
661
|
+
* **addObject**: Allowed to add/update an object in the index.
|
|
662
|
+
* **deleteObject**: Allowed to delete an existing object.
|
|
663
|
+
* **deleteIndex**: Allowed to delete index content.
|
|
664
|
+
* **settings**: allows to get index settings.
|
|
665
|
+
* **editSettings**: Allowed to change index settings.
|
|
666
|
+
* **analytics**: Allowed to retrieve analytics through the analytics API.
|
|
667
|
+
* **listIndexes**: Allowed to list all accessible indexes.
|
|
604
668
|
|
|
605
669
|
Example of API Key creation:
|
|
606
670
|
```ruby
|
|
@@ -614,14 +678,14 @@ puts res['key']
|
|
|
614
678
|
|
|
615
679
|
You can also create an API Key with advanced restrictions:
|
|
616
680
|
|
|
617
|
-
* Add a validity period
|
|
618
|
-
* Specify the maximum number of API calls allowed from an IP address per hour. Each time an API call is performed with this key, a check is performed. If the IP at the
|
|
681
|
+
* Add a validity period. The key will be valid for a specific period of time (in seconds).
|
|
682
|
+
* Specify the maximum number of API calls allowed from an IP address per hour. Each time an API call is performed with this key, a check is performed. If the IP at the source of the call did more than this number of calls in the last hour, a 403 code is returned. Defaults to 0 (no rate limit). This parameter can be used to protect you from attempts at retrieving your entire index contents by massively querying the index.
|
|
619
683
|
|
|
620
684
|
|
|
621
685
|
Note: If you are sending the query through your servers, you must use the `Algolia.with_rate_limits("EndUserIP", "APIKeyWithRateLimit") do ... end` block to enable rate-limit.
|
|
622
686
|
|
|
623
|
-
* Specify the maximum number of hits this API key can retrieve in one call. Defaults to 0 (unlimited). This parameter can be used to protect you from attempts at retrieving your entire
|
|
624
|
-
* Specify the list of targeted indices
|
|
687
|
+
* Specify the maximum number of hits this API key can retrieve in one call. Defaults to 0 (unlimited). This parameter can be used to protect you from attempts at retrieving your entire index contents by massively querying the index.
|
|
688
|
+
* Specify the list of targeted indices. You can target all indices starting with a prefix or ending with a suffix using the '*' character. For example, "dev_*" matches all indices starting with "dev_" and "*_dev" matches all indices ending with "_dev". Defaults to all indices if empty or blank.
|
|
625
689
|
|
|
626
690
|
```ruby
|
|
627
691
|
# Creates a new global API key that is valid for 300 seconds
|
|
@@ -636,7 +700,7 @@ res = index.add_user_key(["search"], 300, 100, 20, ['my_index1', 'my_index2'])
|
|
|
636
700
|
puts res['key']
|
|
637
701
|
```
|
|
638
702
|
|
|
639
|
-
Update the
|
|
703
|
+
Update the permissions of an existing key:
|
|
640
704
|
```ruby
|
|
641
705
|
# Update an existing global API key that is valid for 300 seconds
|
|
642
706
|
res = Algolia.update_user_key("myAPIKey", ["search"], 300)
|
|
@@ -649,7 +713,7 @@ puts res['key']
|
|
|
649
713
|
res = index.update_user_key("myAPIKey", ["search"], 300, 100, 20, ['my_index1', 'my_index2'])
|
|
650
714
|
puts res['key']
|
|
651
715
|
```
|
|
652
|
-
Get the
|
|
716
|
+
Get the permissions of a given key:
|
|
653
717
|
```ruby
|
|
654
718
|
# Gets the rights of a global key
|
|
655
719
|
Algolia.get_user_key("f420238212c54dcfad07ea0aa6d5c45f")
|
|
@@ -667,7 +731,7 @@ index.delete_user_key("71671c38001bf3ac857bc82052485107")
|
|
|
667
731
|
|
|
668
732
|
|
|
669
733
|
|
|
670
|
-
You may have a single index containing per
|
|
734
|
+
You may have a single index containing per user data. In that case, all records should be tagged with their associated user_id in order to add a `tagFilters=(public,user_42)` filter at query time to retrieve only what a user has access to. If you're using the [JavaScript client](http://github.com/algolia/algoliasearch-client-js), it will result in a security breach since the user is able to modify the `tagFilters` you've set by modifying the code from the browser. To keep using the JavaScript client (recommended for optimal latency) and target secured records, you can generate a secured API key from your backend:
|
|
671
735
|
|
|
672
736
|
```ruby
|
|
673
737
|
# generate a public API key for user 42. Here, records are tagged with:
|
|
@@ -688,7 +752,7 @@ This public API key must then be used in your JavaScript code as follow:
|
|
|
688
752
|
</script>
|
|
689
753
|
```
|
|
690
754
|
|
|
691
|
-
You can mix rate limits and secured API keys setting an extra `user_token` attribute both at API key generation
|
|
755
|
+
You can mix rate limits and secured API keys by setting an extra `user_token` attribute both at API key generation time and query time. When set, a unique user will be identified by her `IP + user_token` instead of only by her `IP`. This allows you to restrict a single user to performing a maximum of `N` API calls per hour, even if she shares her `IP` with another user.
|
|
692
756
|
|
|
693
757
|
```ruby
|
|
694
758
|
# generate a public API key for user 42. Here, records are tagged with:
|
|
@@ -716,7 +780,7 @@ Copy or rename an index
|
|
|
716
780
|
-------------
|
|
717
781
|
|
|
718
782
|
You can easily copy or rename an existing index using the `copy` and `move` commands.
|
|
719
|
-
**Note**: Move and copy commands overwrite destination index.
|
|
783
|
+
**Note**: Move and copy commands overwrite the destination index.
|
|
720
784
|
|
|
721
785
|
```ruby
|
|
722
786
|
# Rename MyIndex in MyIndexNewName
|
|
@@ -725,20 +789,20 @@ puts Algolia.move_index("MyIndex", "MyIndexNewName")
|
|
|
725
789
|
puts Algolia.copy_index("MyIndex", "MyIndexCopy")
|
|
726
790
|
```
|
|
727
791
|
|
|
728
|
-
The move command is particularly useful
|
|
729
|
-
1. Import your database
|
|
730
|
-
1. Rename `MyNewIndex`
|
|
792
|
+
The move command is particularly useful if you want to update a big index atomically from one version to another. For example, if you recreate your index `MyIndex` each night from a database by batch, you only need to:
|
|
793
|
+
1. Import your database into a new index using [batches](#batch-writes). Let's call this new index `MyNewIndex`.
|
|
794
|
+
1. Rename `MyNewIndex` to `MyIndex` using the move command. This will automatically override the old index and new queries will be served on the new one.
|
|
731
795
|
|
|
732
796
|
```ruby
|
|
733
797
|
# Rename MyNewIndex in MyIndex (and overwrite it)
|
|
734
798
|
puts Algolia.move_index("MyNewIndex", "MyIndex")
|
|
735
799
|
```
|
|
736
800
|
|
|
737
|
-
Backup / Retrieve all index content
|
|
801
|
+
Backup / Retrieve of all index content
|
|
738
802
|
-------------
|
|
739
803
|
|
|
740
|
-
You can retrieve all index content for backup
|
|
741
|
-
This method
|
|
804
|
+
You can retrieve all index content for backup purposes or for SEO using the browse method.
|
|
805
|
+
This method retrieves 1,000 objects via an API call and supports pagination.
|
|
742
806
|
|
|
743
807
|
```ruby
|
|
744
808
|
# Get first page
|
|
@@ -750,10 +814,10 @@ puts index.browse(1)
|
|
|
750
814
|
Logs
|
|
751
815
|
-------------
|
|
752
816
|
|
|
753
|
-
You can retrieve the
|
|
817
|
+
You can retrieve the latest logs via this API. Each log entry contains:
|
|
754
818
|
* Timestamp in ISO-8601 format
|
|
755
819
|
* Client IP
|
|
756
|
-
* Request Headers (API
|
|
820
|
+
* Request Headers (API Key is obfuscated)
|
|
757
821
|
* Request URL
|
|
758
822
|
* Request method
|
|
759
823
|
* Request body
|
|
@@ -761,9 +825,14 @@ You can retrieve the last logs via this API. Each log entry contains:
|
|
|
761
825
|
* Answer body
|
|
762
826
|
* SHA1 ID of entry
|
|
763
827
|
|
|
764
|
-
You can retrieve the logs of your last
|
|
765
|
-
* ***offset***: Specify the first entry to retrieve (0-based, 0 is the most recent log entry).
|
|
766
|
-
* ***length***: Specify the maximum number of entries to retrieve starting at offset. Defaults to 10. Maximum allowed value:
|
|
828
|
+
You can retrieve the logs of your last 1,000 API calls and browse them using the offset/length parameters:
|
|
829
|
+
* ***offset***: Specify the first entry to retrieve (0-based, 0 is the most recent log entry). Defaults to 0.
|
|
830
|
+
* ***length***: Specify the maximum number of entries to retrieve starting at the offset. Defaults to 10. Maximum allowed value: 1,000.
|
|
831
|
+
* ***onlyErrors***: Retrieve only logs with an HTTP code different than 200 or 201. (deprecated)
|
|
832
|
+
* ***type***: Specify the type of logs to retrieve:
|
|
833
|
+
* ***query***: Retrieve only the queries.
|
|
834
|
+
* ***build***: Retrieve only the build operations.
|
|
835
|
+
* ***error***: Retrieve only the errors (same as ***onlyErrors*** parameters).
|
|
767
836
|
|
|
768
837
|
```ruby
|
|
769
838
|
# Get last 10 log entries
|
|
@@ -777,7 +846,7 @@ puts Algolia.get_logs(0, 100, true).to_json
|
|
|
777
846
|
Mock
|
|
778
847
|
-------------
|
|
779
848
|
|
|
780
|
-
For testing
|
|
849
|
+
For testing purposes, you may want to mock Algolia's API calls. We provide a [WebMock](https://github.com/bblimke/webmock) configuration that you can use including `algolia/webmock`:
|
|
781
850
|
|
|
782
851
|
```ruby
|
|
783
852
|
require 'algolia/webmock'
|