algoliasearch 1.12.4 → 1.12.5
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.
- checksums.yaml +4 -4
- data/.travis.yml +4 -0
- data/ChangeLog +6 -3
- data/README.md +809 -892
- data/lib/algolia/client.rb +7 -2
- data/lib/algolia/version.rb +1 -1
- data/spec/client_spec.rb +3 -7
- metadata +3 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 58149dfb195329c0f545aa3f3f7fb7393aa2c17d
|
|
4
|
+
data.tar.gz: 72aef58e1c731284f4c4b62acca29c7eb19a2dbe
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 03b13e5680346176be1feb0908b15be7781b8b0e38348137bcf165591ae4fce66af47d402ecb789705e055c17e03f1d66dc1a7b3216acf9738e82633293735c9
|
|
7
|
+
data.tar.gz: d2ced7f61da48579ec7aff36810170b330b5bca11a7f7fdd79822e85735fa7026b49fe6feb2d7200c8e6f47de9195eee76ae7799bb68a162b75facb8ac89f50d
|
data/.travis.yml
CHANGED
|
@@ -3,17 +3,21 @@ branches:
|
|
|
3
3
|
only:
|
|
4
4
|
- master
|
|
5
5
|
rvm:
|
|
6
|
+
- 1.8.7
|
|
6
7
|
- 1.9.3
|
|
7
8
|
- 2.0.0
|
|
8
9
|
- 2.1.10
|
|
9
10
|
- 2.2.5
|
|
10
11
|
- 2.3.1
|
|
12
|
+
- 2.4.0
|
|
11
13
|
- jruby
|
|
12
14
|
- rbx-2
|
|
13
15
|
matrix:
|
|
14
16
|
allow_failures:
|
|
15
17
|
- rvm: 1.8.7
|
|
16
18
|
- rvm: rbx-2
|
|
19
|
+
- rvm: jruby
|
|
20
|
+
- rvm: 2.4.0
|
|
17
21
|
cache: bundler
|
|
18
22
|
env:
|
|
19
23
|
global:
|
data/ChangeLog
CHANGED
|
@@ -1,12 +1,15 @@
|
|
|
1
1
|
CHANGELOG
|
|
2
2
|
|
|
3
|
-
2016-12-07
|
|
3
|
+
2016-12-07 1.12.5
|
|
4
|
+
* Fixed retry strategy not keeping the `current_host` first #163
|
|
5
|
+
|
|
6
|
+
2016-12-07 1.12.4
|
|
4
7
|
* Fix DNS tests
|
|
5
8
|
|
|
6
|
-
2016-12-06
|
|
9
|
+
2016-12-06 1.12.3
|
|
7
10
|
* Allow for multiple clients on different app ids on the same thread
|
|
8
11
|
|
|
9
|
-
2016-12-05
|
|
12
|
+
2016-12-05 1.12.2
|
|
10
13
|
* Fix client scoped methods
|
|
11
14
|
|
|
12
15
|
2016-11-25 1.12.1
|
data/README.md
CHANGED
|
@@ -1,141 +1,123 @@
|
|
|
1
|
-
<!--NO_HTML-->
|
|
2
|
-
|
|
3
1
|
# Algolia Search API Client for Ruby
|
|
4
2
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
3
|
[Algolia Search](https://www.algolia.com) is a hosted full-text, numerical, and faceted search engine capable of delivering realtime results from the first keystroke.
|
|
12
4
|
|
|
13
|
-
|
|
14
5
|
Our Ruby client lets you easily use the [Algolia Search API](https://www.algolia.com/doc/rest) from your backend. It wraps the [Algolia Search REST API](https://www.algolia.com/doc/rest).
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
6
|
[](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)
|
|
19
7
|
|
|
20
8
|
|
|
9
|
+
# Table of Contents
|
|
21
10
|
|
|
22
11
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
## Table of Contents
|
|
27
|
-
|
|
28
12
|
**Getting Started**
|
|
29
13
|
|
|
30
|
-
1. [Getting started](#getting-started)
|
|
31
|
-
1. [Quick Start](#quick-start)
|
|
32
|
-
1. [Guides & Tutorials](#guides--tutorials)
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
**Commands Reference**
|
|
36
|
-
|
|
37
|
-
Getting started
|
|
38
|
-
|
|
39
14
|
1. [Install](#install)
|
|
40
|
-
1. [Init index](#init-index---
|
|
41
|
-
|
|
42
|
-
Search
|
|
43
|
-
|
|
44
|
-
1. [Search in an index](#search-in-an-index---search)
|
|
45
|
-
1. [Find by IDs](#find-by-ids---get_objects)
|
|
46
|
-
|
|
47
|
-
Indexing
|
|
48
|
-
|
|
49
|
-
1. [Add objects](#add-objects---add_objects)
|
|
50
|
-
1. [Update objects](#update-objects---save_objects)
|
|
51
|
-
1. [Partial update objects](#partial-update-objects---partial_update_objects)
|
|
52
|
-
1. [Delete objects](#delete-objects---delete_objects)
|
|
53
|
-
|
|
54
|
-
Settings
|
|
55
|
-
|
|
56
|
-
1. [Get settings](#get-settings---get_settings)
|
|
57
|
-
1. [Set settings](#set-settings---set_settings)
|
|
58
|
-
|
|
59
|
-
Manage Indices
|
|
60
|
-
|
|
61
|
-
1. [List indices](#list-indices---list_indexes)
|
|
62
|
-
1. [Delete index](#delete-index---delete_index)
|
|
63
|
-
1. [Clear index](#clear-index---clear_index)
|
|
64
|
-
1. [Copy index](#copy-index---copy_index)
|
|
65
|
-
1. [Move index](#move-index---move_index)
|
|
66
|
-
|
|
67
|
-
Api Keys
|
|
68
|
-
|
|
69
|
-
1. [Generate key](#generate-key---generate_secured_api_key)
|
|
70
|
-
|
|
15
|
+
1. [Init index - `init_index`](#init-index---initindex)
|
|
16
|
+
1. [Quick Start](#quick-start)
|
|
71
17
|
|
|
72
|
-
|
|
18
|
+
**Search**
|
|
73
19
|
|
|
74
|
-
1. [
|
|
75
|
-
1. [
|
|
20
|
+
1. [Search in an index - `search`](#search-in-an-index---search)
|
|
21
|
+
1. [Search Response Format](#search-response-format)
|
|
22
|
+
1. [Search Parameters](#search-parameters)
|
|
23
|
+
1. [Search in indices - `multiple_queries`](#search-in-indices---multiplequeries)
|
|
24
|
+
1. [Get Objects - `get_objects`](#get-objects---getobjects)
|
|
25
|
+
1. [Search for facet values - `search_for_facet_values`](#search-for-facet-values---searchforfacetvalues)
|
|
26
|
+
|
|
27
|
+
**Indexing**
|
|
28
|
+
|
|
29
|
+
1. [Add Objects - `add_objects`](#add-objects---addobjects)
|
|
30
|
+
1. [Update objects - `save_objects`](#update-objects---saveobjects)
|
|
31
|
+
1. [Partial update objects - `partial_update_objects`](#partial-update-objects---partialupdateobjects)
|
|
32
|
+
1. [Delete objects - `delete_objects`](#delete-objects---deleteobjects)
|
|
33
|
+
1. [Delete by query - `delete_by_query`](#delete-by-query---deletebyquery)
|
|
34
|
+
1. [Wait for operations - `wait_task`](#wait-for-operations---waittask)
|
|
35
|
+
|
|
36
|
+
**Settings**
|
|
37
|
+
|
|
38
|
+
1. [Get settings - `get_settings`](#get-settings---getsettings)
|
|
39
|
+
1. [Set settings - `set_settings`](#set-settings---setsettings)
|
|
40
|
+
1. [Index settings parameters](#index-settings-parameters)
|
|
41
|
+
|
|
42
|
+
**Parameters**
|
|
43
|
+
|
|
44
|
+
1. [Overview](#overview)
|
|
45
|
+
1. [Search](#search)
|
|
46
|
+
1. [Attributes](#attributes)
|
|
47
|
+
1. [Ranking](#ranking)
|
|
48
|
+
1. [Filtering / Faceting](#filtering--faceting)
|
|
49
|
+
1. [Highlighting / Snippeting](#highlighting--snippeting)
|
|
50
|
+
1. [Pagination](#pagination)
|
|
51
|
+
1. [Typos](#typos)
|
|
52
|
+
1. [Geo-Search](#geo-search)
|
|
53
|
+
1. [Query Strategy](#query-strategy)
|
|
54
|
+
1. [performance](#performance)
|
|
55
|
+
1. [Advanced](#advanced)
|
|
56
|
+
|
|
57
|
+
**Manage Indices**
|
|
58
|
+
|
|
59
|
+
1. [Create an index](#create-an-index)
|
|
60
|
+
1. [List indices - `list_indexes`](#list-indices---listindexes)
|
|
61
|
+
1. [Delete index - `delete_index`](#delete-index---deleteindex)
|
|
62
|
+
1. [Clear index - `clear_index`](#clear-index---clearindex)
|
|
63
|
+
1. [Copy index - `copy_index`](#copy-index---copyindex)
|
|
64
|
+
1. [Move index - `move_index`](#move-index---moveindex)
|
|
65
|
+
|
|
66
|
+
**Api keys**
|
|
67
|
+
|
|
68
|
+
1. [Overview](#overview)
|
|
69
|
+
1. [Generate key - `generate_secured_api_key`](#generate-key---generatesecuredapikey)
|
|
70
|
+
|
|
71
|
+
**Synonyms**
|
|
72
|
+
|
|
73
|
+
1. [Save synonym - `save_synonym`](#save-synonym---savesynonym)
|
|
74
|
+
1. [Batch synonyms - `batch_synonyms`](#batch-synonyms---batchsynonyms)
|
|
76
75
|
1. [Editing Synonyms](#editing-synonyms)
|
|
77
|
-
1. [Delete
|
|
78
|
-
1. [Clear all synonyms](#clear-all-synonyms---
|
|
79
|
-
1. [Get synonym](#get-synonym---
|
|
80
|
-
1. [Search synonyms](#search-synonyms---
|
|
81
|
-
|
|
76
|
+
1. [Delete synonym - `delete_synonym`](#delete-synonym---deletesynonym)
|
|
77
|
+
1. [Clear all synonyms - `clear_synonyms`](#clear-all-synonyms---clearsynonyms)
|
|
78
|
+
1. [Get synonym - `get_synonym`](#get-synonym---getsynonym)
|
|
79
|
+
1. [Search synonyms - `search_synonyms`](#search-synonyms---searchsynonyms)
|
|
82
80
|
|
|
83
|
-
Advanced
|
|
84
|
-
|
|
85
|
-
1. [Custom batch](#custom-batch---batch)
|
|
86
|
-
1. [Wait for operations](#wait-for-operations---wait_task)
|
|
87
|
-
1. [Multiple queries](#multiple-queries---multiple_queries)
|
|
88
|
-
1. [Delete by query](#delete-by-query---delete_by_query)
|
|
89
|
-
1. [Backup / Export an index](#backup--export-an-index---browse)
|
|
90
|
-
1. [List api keys](#list-api-keys---list_api_keys)
|
|
91
|
-
1. [Add user key](#add-user-key---add_user_key)
|
|
92
|
-
1. [Update user key](#update-user-key---update_user_key)
|
|
93
|
-
1. [Delete user key](#delete-user-key---delete_user_key)
|
|
94
|
-
1. [Get key permissions](#get-key-permissions---get_user_key_acl)
|
|
95
|
-
1. [Get Logs](#get-logs---get_logs)
|
|
81
|
+
**Advanced**
|
|
96
82
|
|
|
83
|
+
1. [Custom batch - `batch`](#custom-batch---batch)
|
|
84
|
+
1. [Backup / Export an index - `browse`](#backup--export-an-index---browse)
|
|
85
|
+
1. [List api keys - `list_api_keys`](#list-api-keys---listapikeys)
|
|
86
|
+
1. [Add user key - `add_user_key`](#add-user-key---adduserkey)
|
|
87
|
+
1. [Update user key - `update_user_key`](#update-user-key---updateuserkey)
|
|
88
|
+
1. [Delete user key - `delete_user_key`](#delete-user-key---deleteuserkey)
|
|
89
|
+
1. [Get key permissions - `get_user_key_acl`](#get-key-permissions---getuserkeyacl)
|
|
90
|
+
1. [Get last logs - `get_logs`](#get-last-logs---getlogs)
|
|
91
|
+
1. [REST API](#rest-api)
|
|
97
92
|
|
|
98
|
-
Mocking
|
|
93
|
+
**Mocking**
|
|
99
94
|
|
|
100
|
-
1. [
|
|
95
|
+
1. [Webmock](#webmock)
|
|
101
96
|
|
|
102
97
|
|
|
103
|
-
|
|
98
|
+
# Guides & Tutorials
|
|
104
99
|
|
|
105
100
|
Check our [online guides](https://www.algolia.com/doc):
|
|
106
101
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
<!--/NO_HTML-->
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
102
|
+
* [Data Formatting](https://www.algolia.com/doc/indexing/formatting-your-data)
|
|
103
|
+
* [Import and Synchronize data](https://www.algolia.com/doc/indexing/import-synchronize-data/php)
|
|
104
|
+
* [Autocomplete](https://www.algolia.com/doc/search/auto-complete)
|
|
105
|
+
* [Instant search page](https://www.algolia.com/doc/search/instant-search)
|
|
106
|
+
* [Filtering and Faceting](https://www.algolia.com/doc/search/filtering-faceting)
|
|
107
|
+
* [Sorting](https://www.algolia.com/doc/relevance/sorting)
|
|
108
|
+
* [Ranking Formula](https://www.algolia.com/doc/relevance/ranking)
|
|
109
|
+
* [Typo-Tolerance](https://www.algolia.com/doc/relevance/typo-tolerance)
|
|
110
|
+
* [Geo-Search](https://www.algolia.com/doc/geo-search/geo-search-overview)
|
|
111
|
+
* [Security](https://www.algolia.com/doc/security/best-security-practices)
|
|
112
|
+
* [API-Keys](https://www.algolia.com/doc/security/api-keys)
|
|
113
|
+
* [REST API](https://www.algolia.com/doc/rest)
|
|
132
114
|
|
|
133
|
-
## Getting Started
|
|
134
115
|
|
|
135
|
-
|
|
116
|
+
# Getting Started
|
|
136
117
|
|
|
137
118
|
|
|
138
119
|
|
|
120
|
+
## Install
|
|
139
121
|
|
|
140
122
|
Install AlgoliaSearch using:
|
|
141
123
|
|
|
@@ -143,11 +125,11 @@ Install AlgoliaSearch using:
|
|
|
143
125
|
gem install algoliasearch
|
|
144
126
|
```
|
|
145
127
|
|
|
146
|
-
|
|
128
|
+
### Ruby on Rails
|
|
147
129
|
|
|
148
130
|
If you're a Ruby on Rails user; you're probably looking for the [algoliasearch-rails](https://github.com/algolia/algoliasearch-rails) gem.
|
|
149
131
|
|
|
150
|
-
|
|
132
|
+
## Init index - `init_index`
|
|
151
133
|
|
|
152
134
|
To initialize the client, you need your **Application ID** and **API Key**. You can find both of them on [your Algolia account](https://www.algolia.com/api-keys).
|
|
153
135
|
|
|
@@ -159,11 +141,7 @@ Algolia.init :application_id => "YourApplicationID",
|
|
|
159
141
|
:api_key => "YourAPIKey"
|
|
160
142
|
```
|
|
161
143
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
### Quick Start
|
|
165
|
-
|
|
166
|
-
|
|
144
|
+
## Quick Start
|
|
167
145
|
|
|
168
146
|
In 30 seconds, this quick start tutorial will show you how to index and search objects.
|
|
169
147
|
|
|
@@ -196,7 +174,7 @@ index.set_settings({"customRanking" => ["desc(followers)"]})
|
|
|
196
174
|
You can also configure the list of attributes you want to index by order of importance (first = most important):
|
|
197
175
|
|
|
198
176
|
```ruby
|
|
199
|
-
index.set_settings({"searchableAttributes" => ["lastname", "firstname", "company",
|
|
177
|
+
index.set_settings({"searchableAttributes" => ["lastname", "firstname", "company",
|
|
200
178
|
"email", "city", "address"]})
|
|
201
179
|
```
|
|
202
180
|
|
|
@@ -207,8 +185,9 @@ puts index.search('or').to_json
|
|
|
207
185
|
puts index.search('jim').to_json
|
|
208
186
|
```
|
|
209
187
|
|
|
188
|
+
**Note:** If you are building a web application, you may be more interested in using our [JavaScript client](https://github.com/algolia/algoliasearch-client-javascript) to perform queries.
|
|
210
189
|
|
|
211
|
-
|
|
190
|
+
It brings two benefits:
|
|
212
191
|
* Your users get a better response time by not going through your servers
|
|
213
192
|
* It will offload unnecessary tasks from your servers
|
|
214
193
|
|
|
@@ -243,25 +222,19 @@ function searchCallback(err, content) {
|
|
|
243
222
|
```
|
|
244
223
|
|
|
245
224
|
|
|
225
|
+
# Search
|
|
246
226
|
|
|
247
227
|
|
|
248
228
|
|
|
229
|
+
## Search in an index - `search`
|
|
249
230
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
## Search
|
|
253
|
-
|
|
254
|
-
### Search in an index - `search`
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
**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:
|
|
231
|
+
**Notes:** If you are building a web application, you may be more interested in using our [JavaScript client](https://github.com/algolia/algoliasearch-client-javascript) to perform queries. It brings two benefits:
|
|
258
232
|
* Your users get a better response time by not going through your servers
|
|
259
233
|
* It will offload unnecessary tasks from your servers.
|
|
260
234
|
|
|
261
|
-
|
|
262
235
|
To perform a search, you only need to initialize the index and perform a call to the search function.
|
|
263
236
|
|
|
264
|
-
The search query allows only to retrieve 1000 hits. If you need to retrieve more than 1000 hits (e.g. for SEO), you can use [Backup /
|
|
237
|
+
The search query allows only to retrieve 1000 hits. If you need to retrieve more than 1000 hits (e.g. for SEO), you can use [Backup / Export an index](#backup--export-an-index).
|
|
265
238
|
|
|
266
239
|
```ruby
|
|
267
240
|
index = Algolia::Index.new("contacts")
|
|
@@ -269,9 +242,9 @@ res = index.search("query string")
|
|
|
269
242
|
res = index.search("query string", { "attributesToRetrieve" => "firstname,lastname", "hitsPerPage" => 20})
|
|
270
243
|
```
|
|
271
244
|
|
|
272
|
-
|
|
245
|
+
## Search Response Format
|
|
273
246
|
|
|
274
|
-
|
|
247
|
+
### Sample
|
|
275
248
|
|
|
276
249
|
The server response will look like:
|
|
277
250
|
|
|
@@ -308,7 +281,7 @@ The server response will look like:
|
|
|
308
281
|
}
|
|
309
282
|
```
|
|
310
283
|
|
|
311
|
-
|
|
284
|
+
### Fields
|
|
312
285
|
|
|
313
286
|
- `hits` (array): The hits returned by the search, sorted according to the ranking formula.
|
|
314
287
|
|
|
@@ -374,10 +347,8 @@ The server response will look like:
|
|
|
374
347
|
|
|
375
348
|
- `message` (string, optional): Used to return warnings about the query.
|
|
376
349
|
|
|
377
|
-
|
|
378
350
|
- `aroundLatLng` (string, optional): *Note: Only returned when [aroundLatLngViaIP](#aroundlatlngviaip) is set.* The computed geo location. **Warning: for legacy reasons, this parameter is a string and not an object.** Format: `${lat},${lng}`, where the latitude and longitude are expressed as decimal floating point numbers.
|
|
379
351
|
|
|
380
|
-
|
|
381
352
|
- `automaticRadius` (integer, optional): *Note: Only returned for geo queries without an explicitly specified radius (see `aroundRadius`).* The automatically computed radius. **Warning: for legacy reasons, this parameter is a string and not an integer.**
|
|
382
353
|
|
|
383
354
|
When [getRankingInfo](#getrankinginfo) is set to `true`, the following additional fields are returned:
|
|
@@ -414,7 +385,7 @@ When [facets](#facets) is non-empty, the following additional fields are returne
|
|
|
414
385
|
|
|
415
386
|
- `exhaustiveFacetsCount` (boolean): Whether the counts are exhaustive (`true`) or approximate (`false`). *Note: When using [distinct](#distinct), the facet counts cannot be exhaustive.*
|
|
416
387
|
|
|
417
|
-
|
|
388
|
+
## Search Parameters
|
|
418
389
|
|
|
419
390
|
Here is the list of parameters you can use with the search method (`search` [scope](#scope)):
|
|
420
391
|
Parameters that can also be used in a setSettings also have the `indexing` [scope](#scope)
|
|
@@ -433,6 +404,7 @@ Parameters that can also be used in a setSettings also have the `indexing` [scop
|
|
|
433
404
|
- [filters](#filters) `search`
|
|
434
405
|
- [facets](#facets) `search`
|
|
435
406
|
- [maxValuesPerFacet](#maxvaluesperfacet) `settings`, `search`
|
|
407
|
+
- [facetFilters](#facetfilters) `search`
|
|
436
408
|
|
|
437
409
|
**Highlighting / Snippeting**
|
|
438
410
|
|
|
@@ -471,30 +443,27 @@ Parameters that can also be used in a setSettings also have the `indexing` [scop
|
|
|
471
443
|
|
|
472
444
|
**Query Strategy**
|
|
473
445
|
|
|
474
|
-
- [queryType](#querytype) `settings`, `search`
|
|
475
446
|
- [removeWordsIfNoResults](#removewordsifnoresults) `settings`, `search`
|
|
476
447
|
- [advancedSyntax](#advancedsyntax) `settings`, `search`
|
|
477
448
|
- [optionalWords](#optionalwords) `settings`, `search`
|
|
478
449
|
- [removeStopWords](#removestopwords) `settings`, `search`
|
|
479
|
-
- [disableExactOnAttributes](#disableexactonattributes) `settings`, `search`
|
|
480
450
|
- [exactOnSingleWordQuery](#exactonsinglewordquery) `settings`, `search`
|
|
481
|
-
- [alternativesAsExact](#alternativesasexact) `
|
|
451
|
+
- [alternativesAsExact](#alternativesasexact) `setting`, `search`
|
|
482
452
|
|
|
483
453
|
**Advanced**
|
|
484
454
|
|
|
455
|
+
- [minProximity](#minproximity) `settings`, `search`
|
|
456
|
+
- [responseFields](#responsefields) `settings`, `search`
|
|
485
457
|
- [distinct](#distinct) `settings`, `search`
|
|
486
458
|
- [getRankingInfo](#getrankinginfo) `search`
|
|
487
|
-
- [numericFilters
|
|
459
|
+
- [numericFilters](#numericfilters) `search`
|
|
488
460
|
- [tagFilters (deprecated)](#tagfilters-deprecated) `search`
|
|
489
|
-
- [facetFilters (deprecated)](#facetfilters-deprecated) `search`
|
|
490
461
|
- [analytics](#analytics) `search`
|
|
491
462
|
- [analyticsTags](#analyticstags) `search`
|
|
492
463
|
- [synonyms](#synonyms) `search`
|
|
493
|
-
- [replaceSynonymsInHighlight](#replacesynonymsinhighlight) `
|
|
494
|
-
- [minProximity](#minproximity) `search`, `settings`
|
|
495
|
-
- [responseFields](#responsefields) `search`, `settings`
|
|
464
|
+
- [replaceSynonymsInHighlight](#replacesynonymsinhighlight) `settings`, `search`
|
|
496
465
|
|
|
497
|
-
|
|
466
|
+
## Search in indices - `multiple_queries`
|
|
498
467
|
|
|
499
468
|
You can send multiple queries with a single API call using a batch of queries:
|
|
500
469
|
|
|
@@ -502,9 +471,9 @@ You can send multiple queries with a single API call using a batch of queries:
|
|
|
502
471
|
# perform 3 queries in a single API call:
|
|
503
472
|
# - 1st query targets index `categories`
|
|
504
473
|
# - 2nd and 3rd queries target index `products`
|
|
505
|
-
res = Algolia.multiple_queries([
|
|
506
|
-
,
|
|
507
|
-
,
|
|
474
|
+
res = Algolia.multiple_queries([
|
|
475
|
+
,
|
|
476
|
+
, ])
|
|
508
477
|
|
|
509
478
|
puts res["results"]
|
|
510
479
|
```
|
|
@@ -514,21 +483,17 @@ You can specify a `strategy` parameter to optimize your multiple queries:
|
|
|
514
483
|
- `none`: Execute the sequence of queries until the end.
|
|
515
484
|
- `stopIfEnoughMatches`: Execute the sequence of queries until the number of hits is reached by the sum of hits.
|
|
516
485
|
|
|
517
|
-
|
|
486
|
+
### Response
|
|
518
487
|
|
|
519
488
|
The resulting JSON contains the following fields:
|
|
520
489
|
|
|
521
|
-
- `results` (array): The results for each request, in the order they were submitted. The contents are the same as in [Search in an index](#search-in-an-index
|
|
522
|
-
|
|
490
|
+
- `results` (array): The results for each request, in the order they were submitted. The contents are the same as in [Search in an index](#search-in-an-index).
|
|
523
491
|
Each result also includes the following additional fields:
|
|
524
492
|
|
|
525
493
|
- `index` (string): The name of the targeted index.
|
|
526
|
-
|
|
527
494
|
- `processed` (boolean, optional): *Note: Only returned when `strategy` is `stopIfEnoughmatches`.* Whether the query was processed.
|
|
528
495
|
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
### Find by IDs - `get_objects`
|
|
496
|
+
## Get Objects - `get_objects`
|
|
532
497
|
|
|
533
498
|
You can easily retrieve an object using its `objectID` and optionally specify a comma separated list of attributes you want:
|
|
534
499
|
|
|
@@ -547,14 +512,97 @@ You can also retrieve a set of objects:
|
|
|
547
512
|
res = index.get_objects(["myID", "myID2"])
|
|
548
513
|
```
|
|
549
514
|
|
|
515
|
+
## Search for facet values - `search_for_facet_values`
|
|
516
|
+
|
|
517
|
+
When a facet can take many different values, it can be useful to search within them. The typical use case is to build
|
|
518
|
+
an autocomplete menu for facet refinements, but of course other use cases may apply as well.
|
|
519
|
+
|
|
520
|
+
The facet search is different from a regular search in the sense that it retrieves *facet values*, not *objects*.
|
|
521
|
+
In other words, a value will only be returned once, even if it matches many different objects. How many objects it
|
|
522
|
+
matches is indicated by a count.
|
|
523
|
+
|
|
524
|
+
The results are sorted by decreasing count. Maximum 10 results are returned. No pagination is possible.
|
|
525
|
+
|
|
526
|
+
The facet search can optionally be restricted by a regular search query. In that case, it will return only facet values
|
|
527
|
+
that both:
|
|
528
|
+
|
|
529
|
+
1. match the facet query; and
|
|
530
|
+
2. are contained in objects matching the regular search query.
|
|
531
|
+
|
|
532
|
+
**Warning:** *For a facet to be searchable, it must have been declared with the `searchable()` modifier in the [attributesForFaceting](#attributesforfaceting) index setting.*
|
|
533
|
+
|
|
534
|
+
#### Example
|
|
535
|
+
|
|
536
|
+
Let's imagine we have objects similar to this one:
|
|
537
|
+
|
|
538
|
+
```json
|
|
539
|
+
{
|
|
540
|
+
"name": "iPhone 7 Plus",
|
|
541
|
+
"brand": "Apple",
|
|
542
|
+
"category": [
|
|
543
|
+
"Mobile phones",
|
|
544
|
+
"Electronics"
|
|
545
|
+
]
|
|
546
|
+
}
|
|
547
|
+
```
|
|
548
|
+
|
|
549
|
+
Then:
|
|
550
|
+
|
|
551
|
+
```ruby
|
|
552
|
+
# Search the values of the "category" facet matching "phone".
|
|
553
|
+
index.search_for_facet_values 'category', 'phone'
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
... could return:
|
|
557
|
+
|
|
558
|
+
```json
|
|
559
|
+
{
|
|
560
|
+
"facetHits": [
|
|
561
|
+
{
|
|
562
|
+
"value": "Mobile phones",
|
|
563
|
+
"highlighted": "Mobile <em>phone</em>s",
|
|
564
|
+
"count": 507
|
|
565
|
+
},
|
|
566
|
+
{
|
|
567
|
+
"value": "Phone cases",
|
|
568
|
+
"highlighted": "<em>Phone</em> cases",
|
|
569
|
+
"count": 63
|
|
570
|
+
}
|
|
571
|
+
]
|
|
572
|
+
}
|
|
573
|
+
```
|
|
574
|
+
|
|
575
|
+
Let's filter with an additional, regular search query:
|
|
576
|
+
|
|
577
|
+
```ruby
|
|
578
|
+
query = {
|
|
579
|
+
:filters => 'brand:Apple'
|
|
580
|
+
}
|
|
581
|
+
# Search the "category" facet for values matching "phone" in records
|
|
582
|
+
# having "Apple" in their "brand" facet.
|
|
583
|
+
index.search_for_facet_values 'category', 'phone', query
|
|
584
|
+
```
|
|
585
|
+
|
|
586
|
+
... could return:
|
|
550
587
|
|
|
588
|
+
```json
|
|
589
|
+
{
|
|
590
|
+
"facetHits": [
|
|
591
|
+
{
|
|
592
|
+
"value": "Mobile phones",
|
|
593
|
+
"highlighted": "Mobile <em>phone</em>s",
|
|
594
|
+
"count": 41
|
|
595
|
+
}
|
|
596
|
+
]
|
|
597
|
+
}
|
|
598
|
+
```
|
|
551
599
|
|
|
552
600
|
|
|
553
|
-
|
|
601
|
+
# Indexing
|
|
554
602
|
|
|
555
603
|
|
|
556
604
|
|
|
557
|
-
|
|
605
|
+
## Add Objects - `add_objects`
|
|
558
606
|
|
|
559
607
|
Each entry in an index has a unique identifier called `objectID`. There are two ways to add an entry to the index:
|
|
560
608
|
|
|
@@ -562,14 +610,15 @@ Each entry in an index has a unique identifier called `objectID`. There are two
|
|
|
562
610
|
2. Using automatic `objectID` assignment. You will be able to access it in the answer.
|
|
563
611
|
|
|
564
612
|
You don't need to explicitly create an index, it will be automatically created the first time you add an object.
|
|
565
|
-
Objects are schema less so you don't need any configuration to start indexing.
|
|
613
|
+
Objects are schema less so you don't need any configuration to start indexing.
|
|
614
|
+
If you wish to configure things, the settings section provides details about advanced settings.
|
|
566
615
|
|
|
567
616
|
Example with automatic `objectID` assignments:
|
|
568
617
|
|
|
569
618
|
```ruby
|
|
570
|
-
res = index.add_objects([{"firstname" => "Jimmie",
|
|
619
|
+
res = index.add_objects([{"firstname" => "Jimmie",
|
|
571
620
|
"lastname" => "Barninger"},
|
|
572
|
-
{"firstname" => "Warren",
|
|
621
|
+
{"firstname" => "Warren",
|
|
573
622
|
"lastname" => "Speach"}])
|
|
574
623
|
```
|
|
575
624
|
|
|
@@ -584,15 +633,15 @@ res = index.add_objects([{"objectID" => "1",
|
|
|
584
633
|
"lastname" => "Speach"}])
|
|
585
634
|
```
|
|
586
635
|
|
|
587
|
-
To add a single object, use the
|
|
636
|
+
To add a single object, use the [Add Objects](#add-objects) method:
|
|
588
637
|
|
|
589
638
|
```ruby
|
|
590
|
-
res = index.add_object({"firstname" => "Jimmie",
|
|
639
|
+
res = index.add_object({"firstname" => "Jimmie",
|
|
591
640
|
"lastname" => "Barninger"}, "myID")
|
|
592
641
|
puts "ObjectID=" + res["objectID"]
|
|
593
642
|
```
|
|
594
643
|
|
|
595
|
-
|
|
644
|
+
## Update objects - `save_objects`
|
|
596
645
|
|
|
597
646
|
You have three options when updating an existing object:
|
|
598
647
|
|
|
@@ -603,25 +652,24 @@ You have three options when updating an existing object:
|
|
|
603
652
|
Example on how to replace all attributes existing objects:
|
|
604
653
|
|
|
605
654
|
```ruby
|
|
606
|
-
res = index.save_objects([{"firstname" => "Jimmie",
|
|
655
|
+
res = index.save_objects([{"firstname" => "Jimmie",
|
|
607
656
|
"lastname" => "Barninger",
|
|
608
657
|
"objectID" => "myID1"},
|
|
609
|
-
{"firstname" => "Warren",
|
|
658
|
+
{"firstname" => "Warren",
|
|
610
659
|
"lastname" => "Speach",
|
|
611
660
|
"objectID" => "myID2"}])
|
|
612
661
|
```
|
|
613
662
|
|
|
614
|
-
To update a single object, you can use the
|
|
663
|
+
To update a single object, you can use the following method:
|
|
615
664
|
|
|
616
665
|
```ruby
|
|
617
|
-
index.save_object({"firstname" => "Jimmie",
|
|
666
|
+
index.save_object({"firstname" => "Jimmie",
|
|
618
667
|
"lastname" => "Barninger",
|
|
619
668
|
"city" => "New York",
|
|
620
669
|
"objectID" => "myID"})
|
|
621
670
|
```
|
|
622
671
|
|
|
623
|
-
|
|
624
|
-
### Partial update objects - `partial_update_objects`
|
|
672
|
+
## Partial update objects - `partial_update_objects`
|
|
625
673
|
|
|
626
674
|
You have many ways to update an object's attributes:
|
|
627
675
|
|
|
@@ -635,7 +683,7 @@ You have many ways to update an object's attributes:
|
|
|
635
683
|
Example to update only the city attribute of an existing object:
|
|
636
684
|
|
|
637
685
|
```ruby
|
|
638
|
-
index.partial_update_object({"city" => "San Francisco",
|
|
686
|
+
index.partial_update_object({"city" => "San Francisco",
|
|
639
687
|
"objectID" => "myID"})
|
|
640
688
|
```
|
|
641
689
|
|
|
@@ -680,17 +728,16 @@ index.partial_update_object({"price" => {"value" => 42, "_operation" => "Decreme
|
|
|
680
728
|
Note: Here we are decrementing the value by `42`. To decrement just by one, put
|
|
681
729
|
`value:1`.
|
|
682
730
|
|
|
683
|
-
To partial update multiple objects using one API call, you can use the `[Partial update objects](#partial-update-objects
|
|
731
|
+
To partial update multiple objects using one API call, you can use the `[Partial update objects](#partial-update-objects)` method:
|
|
684
732
|
|
|
685
733
|
```ruby
|
|
686
|
-
res = index.partial_update_objects([{"firstname" => "Jimmie",
|
|
734
|
+
res = index.partial_update_objects([{"firstname" => "Jimmie",
|
|
687
735
|
"objectID" => "SFO"},
|
|
688
|
-
{"firstname" => "Warren",
|
|
736
|
+
{"firstname" => "Warren",
|
|
689
737
|
"objectID" => "myID2"}])
|
|
690
738
|
```
|
|
691
739
|
|
|
692
|
-
|
|
693
|
-
### Delete objects - `delete_objects`
|
|
740
|
+
## Delete objects - `delete_objects`
|
|
694
741
|
|
|
695
742
|
You can delete objects using their `objectID`:
|
|
696
743
|
|
|
@@ -698,17 +745,16 @@ You can delete objects using their `objectID`:
|
|
|
698
745
|
res = index.delete_objects(["myID1", "myID2"])
|
|
699
746
|
```
|
|
700
747
|
|
|
701
|
-
To delete a single object, you can use the `[Delete
|
|
748
|
+
To delete a single object, you can use the `[Delete objects](#delete-objects)` method:
|
|
702
749
|
|
|
703
750
|
```ruby
|
|
704
751
|
index.delete_object("myID")
|
|
705
752
|
```
|
|
706
753
|
|
|
707
|
-
|
|
754
|
+
## Delete by query - `delete_by_query`
|
|
708
755
|
|
|
709
756
|
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.
|
|
710
757
|
|
|
711
|
-
|
|
712
758
|
Take your precautions when using this method. Calling it with an empty query will result in cleaning the index of all its records.
|
|
713
759
|
|
|
714
760
|
```ruby
|
|
@@ -716,7 +762,7 @@ params = {}
|
|
|
716
762
|
index.delete_by_query("John", params)
|
|
717
763
|
```
|
|
718
764
|
|
|
719
|
-
|
|
765
|
+
## Wait for operations - `wait_task`
|
|
720
766
|
|
|
721
767
|
All write operations in Algolia are asynchronous by design.
|
|
722
768
|
|
|
@@ -726,12 +772,12 @@ operation.
|
|
|
726
772
|
|
|
727
773
|
The actual insert and indexing will be done after replying to your code.
|
|
728
774
|
|
|
729
|
-
You can wait for a task to complete using
|
|
775
|
+
You can wait for a task to complete using the same method with a `!`.
|
|
730
776
|
|
|
731
777
|
For example, to wait for indexing of a new object:
|
|
732
778
|
|
|
733
779
|
```ruby
|
|
734
|
-
res = index.add_object!({"firstname" => "Jimmie",
|
|
780
|
+
res = index.add_object!({"firstname" => "Jimmie",
|
|
735
781
|
"lastname" => "Barninger"})
|
|
736
782
|
```
|
|
737
783
|
|
|
@@ -739,11 +785,11 @@ If you want to ensure multiple objects have been indexed, you only need to check
|
|
|
739
785
|
the biggest `taskID` with `wait_task`.
|
|
740
786
|
|
|
741
787
|
|
|
742
|
-
|
|
788
|
+
# Settings
|
|
743
789
|
|
|
744
790
|
|
|
745
791
|
|
|
746
|
-
|
|
792
|
+
## Get settings - `get_settings`
|
|
747
793
|
|
|
748
794
|
You can retrieve settings:
|
|
749
795
|
|
|
@@ -752,17 +798,19 @@ settings = index.get_settings
|
|
|
752
798
|
puts settings.to_json
|
|
753
799
|
```
|
|
754
800
|
|
|
755
|
-
|
|
801
|
+
## Set settings - `set_settings`
|
|
756
802
|
|
|
757
803
|
```ruby
|
|
758
804
|
index.set_settings({"customRanking" => ["desc(followers)"]})
|
|
759
805
|
```
|
|
760
806
|
|
|
807
|
+
You can find the list of parameters you can set in the [Settings Parameters](#index-settings-parameters) section
|
|
808
|
+
|
|
761
809
|
**Warning**
|
|
762
810
|
|
|
763
811
|
Performance wise, it's better to do a `set_settings` before pushing the data
|
|
764
812
|
|
|
765
|
-
|
|
813
|
+
### Replica settings
|
|
766
814
|
|
|
767
815
|
You can forward all settings updates to the replicas of an index by using the `forwardToReplicas` option:
|
|
768
816
|
|
|
@@ -770,21 +818,18 @@ You can forward all settings updates to the replicas of an index by using the `f
|
|
|
770
818
|
index.set_settings({"customRanking" => ["desc(followers)"]}, {"forwardToReplicas" => true})
|
|
771
819
|
```
|
|
772
820
|
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
### Index settings parameters
|
|
821
|
+
## Index settings parameters
|
|
776
822
|
|
|
777
823
|
Here is the list of parameters you can use with the set settings method (`settings` [scope](#scope)).
|
|
778
824
|
|
|
779
|
-
|
|
780
825
|
Parameters that can be overridden at search time also have the `search` [scope](#scope).
|
|
781
826
|
|
|
782
827
|
**Attributes**
|
|
783
828
|
|
|
784
829
|
- [searchableAttributes](#searchableattributes) `settings`
|
|
785
830
|
- [attributesForFaceting](#attributesforfaceting) `settings`
|
|
786
|
-
- [attributesToRetrieve](#attributestoretrieve) `settings`, `search`
|
|
787
831
|
- [unretrievableAttributes](#unretrievableattributes) `settings`
|
|
832
|
+
- [attributesToRetrieve](#attributestoretrieve) `settings`, `search`
|
|
788
833
|
|
|
789
834
|
**Ranking**
|
|
790
835
|
|
|
@@ -803,10 +848,12 @@ Parameters that can be overridden at search time also have the `search` [scope](
|
|
|
803
848
|
- [highlightPreTag](#highlightpretag) `settings`, `search`
|
|
804
849
|
- [highlightPostTag](#highlightposttag) `settings`, `search`
|
|
805
850
|
- [snippetEllipsisText](#snippetellipsistext) `settings`, `search`
|
|
851
|
+
- [restrictHighlightAndSnippetArrays](#restricthighlightandsnippetarrays) `settings`, `search`
|
|
806
852
|
|
|
807
853
|
**Pagination**
|
|
808
854
|
|
|
809
855
|
- [hitsPerPage](#hitsperpage) `settings`, `search`
|
|
856
|
+
- [paginationLimitedTo](#paginationlimitedto) `settings`
|
|
810
857
|
|
|
811
858
|
**Typos**
|
|
812
859
|
|
|
@@ -816,34 +863,42 @@ Parameters that can be overridden at search time also have the `search` [scope](
|
|
|
816
863
|
- [allowTyposOnNumericTokens](#allowtyposonnumerictokens) `settings`, `search`
|
|
817
864
|
- [ignorePlurals](#ignoreplurals) `settings`, `search`
|
|
818
865
|
- [disableTypoToleranceOnAttributes](#disabletypotoleranceonattributes) `settings`, `search`
|
|
866
|
+
- [disableTypoToleranceOnWords](#disabletypotoleranceonwords) `settings`
|
|
819
867
|
- [separatorsToIndex](#separatorstoindex) `settings`
|
|
820
868
|
|
|
821
869
|
**Query Strategy**
|
|
822
870
|
|
|
823
|
-
- [queryType](#querytype) `settings
|
|
871
|
+
- [queryType](#querytype) `settings`
|
|
824
872
|
- [removeWordsIfNoResults](#removewordsifnoresults) `settings`, `search`
|
|
825
873
|
- [advancedSyntax](#advancedsyntax) `settings`, `search`
|
|
826
874
|
- [optionalWords](#optionalwords) `settings`, `search`
|
|
827
875
|
- [removeStopWords](#removestopwords) `settings`, `search`
|
|
828
|
-
- [
|
|
829
|
-
- [disableExactOnAttributes](#disableexactonattributes) `settings`, `search`
|
|
876
|
+
- [disableExactOnAttributes](#disableexactonattributes) `settings`
|
|
830
877
|
- [exactOnSingleWordQuery](#exactonsinglewordquery) `settings`, `search`
|
|
831
|
-
- [alternativesAsExact](#alternativesasexact) `settings`, `search`
|
|
832
878
|
|
|
833
|
-
**
|
|
879
|
+
**performance**
|
|
834
880
|
|
|
835
|
-
- [attributeForDistinct](#attributefordistinct) `settings`
|
|
836
|
-
- [distinct](#distinct) `settings`, `search`
|
|
837
881
|
- [numericAttributesForFiltering](#numericattributesforfiltering) `settings`
|
|
838
882
|
- [allowCompressionOfIntegerArray](#allowcompressionofintegerarray) `settings`
|
|
839
|
-
|
|
883
|
+
|
|
884
|
+
**Advanced**
|
|
885
|
+
|
|
886
|
+
- [attributeForDistinct](#attributefordistinct) `settings`
|
|
840
887
|
- [placeholders](#placeholders) `settings`
|
|
888
|
+
- [altCorrections](#altcorrections) `settings`
|
|
889
|
+
- [minProximity](#minproximity) `settings`, `search`
|
|
890
|
+
- [responseFields](#responsefields) `settings`, `search`
|
|
891
|
+
- [distinct](#distinct) `settings`, `search`
|
|
892
|
+
- [replaceSynonymsInHighlight](#replacesynonymsinhighlight) `settings`, `search`
|
|
893
|
+
|
|
894
|
+
|
|
895
|
+
# Parameters
|
|
841
896
|
|
|
842
|
-
## Parameters
|
|
843
897
|
|
|
844
|
-
### Overview
|
|
845
898
|
|
|
846
|
-
|
|
899
|
+
## Overview
|
|
900
|
+
|
|
901
|
+
### Scope
|
|
847
902
|
|
|
848
903
|
Each parameter in this page has a scope. Depending on the scope, you can use the parameter within the `setSettings`
|
|
849
904
|
and/or the `search` method
|
|
@@ -854,8 +909,7 @@ They are three scopes:
|
|
|
854
909
|
- `search`: The setting can only be used in the `search` method
|
|
855
910
|
- `settings` `search`: The setting can be used in the `setSettings` method and be override in the`search` method
|
|
856
911
|
|
|
857
|
-
|
|
858
|
-
#### Parameters List
|
|
912
|
+
### Parameters List
|
|
859
913
|
|
|
860
914
|
**Search**
|
|
861
915
|
|
|
@@ -880,6 +934,7 @@ They are three scopes:
|
|
|
880
934
|
- [filters](#filters) `search`
|
|
881
935
|
- [facets](#facets) `search`
|
|
882
936
|
- [maxValuesPerFacet](#maxvaluesperfacet) `settings`, `search`
|
|
937
|
+
- [facetFilters](#facetfilters) `search`
|
|
883
938
|
|
|
884
939
|
**Highlighting / Snippeting**
|
|
885
940
|
|
|
@@ -896,6 +951,7 @@ They are three scopes:
|
|
|
896
951
|
- [hitsPerPage](#hitsperpage) `settings`, `search`
|
|
897
952
|
- [offset](#offset) `search`
|
|
898
953
|
- [length](#length) `search`
|
|
954
|
+
- [paginationLimitedTo](#paginationlimitedto) `settings`
|
|
899
955
|
|
|
900
956
|
**Typos**
|
|
901
957
|
|
|
@@ -905,6 +961,7 @@ They are three scopes:
|
|
|
905
961
|
- [allowTyposOnNumericTokens](#allowtyposonnumerictokens) `settings`, `search`
|
|
906
962
|
- [ignorePlurals](#ignoreplurals) `settings`, `search`
|
|
907
963
|
- [disableTypoToleranceOnAttributes](#disabletypotoleranceonattributes) `settings`, `search`
|
|
964
|
+
- [disableTypoToleranceOnWords](#disabletypotoleranceonwords) `settings`
|
|
908
965
|
- [separatorsToIndex](#separatorstoindex) `settings`
|
|
909
966
|
|
|
910
967
|
**Geo-Search**
|
|
@@ -919,56 +976,57 @@ They are three scopes:
|
|
|
919
976
|
|
|
920
977
|
**Query Strategy**
|
|
921
978
|
|
|
922
|
-
- [queryType](#querytype) `settings
|
|
979
|
+
- [queryType](#querytype) `settings`
|
|
923
980
|
- [removeWordsIfNoResults](#removewordsifnoresults) `settings`, `search`
|
|
924
981
|
- [advancedSyntax](#advancedsyntax) `settings`, `search`
|
|
925
982
|
- [optionalWords](#optionalwords) `settings`, `search`
|
|
926
983
|
- [removeStopWords](#removestopwords) `settings`, `search`
|
|
927
|
-
- [disablePrefixOnAttributes](#disableprefixonattributes) `
|
|
928
|
-
- [disableExactOnAttributes](#disableexactonattributes) `settings
|
|
984
|
+
- [disablePrefixOnAttributes](#disableprefixonattributes) `seetings`
|
|
985
|
+
- [disableExactOnAttributes](#disableexactonattributes) `settings`
|
|
929
986
|
- [exactOnSingleWordQuery](#exactonsinglewordquery) `settings`, `search`
|
|
930
|
-
- [alternativesAsExact](#alternativesasexact) `
|
|
987
|
+
- [alternativesAsExact](#alternativesasexact) `setting`, `search`
|
|
988
|
+
|
|
989
|
+
**performance**
|
|
990
|
+
|
|
991
|
+
- [numericAttributesForFiltering](#numericattributesforfiltering) `settings`
|
|
992
|
+
- [allowCompressionOfIntegerArray](#allowcompressionofintegerarray) `settings`
|
|
931
993
|
|
|
932
994
|
**Advanced**
|
|
933
995
|
|
|
934
996
|
- [attributeForDistinct](#attributefordistinct) `settings`
|
|
997
|
+
- [placeholders](#placeholders) `settings`
|
|
998
|
+
- [altCorrections](#altcorrections) `settings`
|
|
999
|
+
- [minProximity](#minproximity) `settings`, `search`
|
|
1000
|
+
- [responseFields](#responsefields) `settings`, `search`
|
|
935
1001
|
- [distinct](#distinct) `settings`, `search`
|
|
936
1002
|
- [getRankingInfo](#getrankinginfo) `search`
|
|
937
|
-
- [
|
|
938
|
-
- [allowCompressionOfIntegerArray](#allowcompressionofintegerarray) `settings`
|
|
939
|
-
- [numericFilters (deprecated)](#numericfilters-deprecated) `search`
|
|
1003
|
+
- [numericFilters](#numericfilters) `search`
|
|
940
1004
|
- [tagFilters (deprecated)](#tagfilters-deprecated) `search`
|
|
941
|
-
- [facetFilters (deprecated)](#facetfilters-deprecated) `search`
|
|
942
1005
|
- [analytics](#analytics) `search`
|
|
943
1006
|
- [analyticsTags](#analyticstags) `search`
|
|
944
1007
|
- [synonyms](#synonyms) `search`
|
|
945
|
-
- [replaceSynonymsInHighlight](#replacesynonymsinhighlight) `
|
|
946
|
-
- [placeholders](#placeholders) `settings`
|
|
947
|
-
- [altCorrections](#altcorrections) `settings`
|
|
948
|
-
- [minProximity](#minproximity) `search`, `settings`
|
|
949
|
-
- [responseFields](#responsefields) `search`, `settings`
|
|
1008
|
+
- [replaceSynonymsInHighlight](#replacesynonymsinhighlight) `settings`, `search`
|
|
950
1009
|
|
|
951
|
-
|
|
1010
|
+
## Search
|
|
952
1011
|
|
|
953
1012
|
#### query
|
|
954
1013
|
|
|
955
1014
|
- scope: `search`
|
|
956
1015
|
- type: `string`
|
|
957
|
-
- default:
|
|
958
|
-
|
|
1016
|
+
- default: ""
|
|
959
1017
|
|
|
960
|
-
The
|
|
1018
|
+
The search query string, used to set the string you want to search in your index.
|
|
1019
|
+
If no query parameter is set, the textual search will match with all the objects.
|
|
961
1020
|
|
|
962
|
-
|
|
1021
|
+
## Attributes
|
|
963
1022
|
|
|
964
1023
|
#### searchableAttributes
|
|
965
1024
|
|
|
966
1025
|
- scope: `settings`
|
|
967
1026
|
- type: `array of strings`
|
|
968
|
-
- default:
|
|
1027
|
+
- default: * (all string attributes)
|
|
969
1028
|
- formerly known as: `attributesToIndex`
|
|
970
1029
|
|
|
971
|
-
|
|
972
1030
|
The list of attributes you want index (i.e. to make searchable).
|
|
973
1031
|
|
|
974
1032
|
If set to null, all textual and numerical attributes of your objects are indexed.
|
|
@@ -976,80 +1034,81 @@ Make sure you updated this setting to get optimal results.
|
|
|
976
1034
|
|
|
977
1035
|
This parameter has two important uses:
|
|
978
1036
|
|
|
979
|
-
1. **Limit the attributes to index.** For example, if you store the URL of a picture, you want to store it and be able to retrieve it,
|
|
1037
|
+
1. **Limit the attributes to index.** For example, if you store the URL of a picture, you want to store it and be able to retrieve it,
|
|
1038
|
+
but you probably don't want to search in the URL.
|
|
980
1039
|
|
|
981
1040
|
2. **Control part of the ranking.** The contents of the `searchableAttributes` parameter impacts ranking in two complementary ways:
|
|
1041
|
+
First, the order in which attributes are listed defines their ranking priority: matches in attributes at the beginning of the
|
|
1042
|
+
list will be considered more important than matches in attributes further down the list. To assign the same priority to several attributes,
|
|
1043
|
+
pass them within the same string, separated by commas. For example, by specifying `["title,"alternative_title", "text"]`,
|
|
1044
|
+
`title` and `alternative_title` will have the same priority, but a higher priority than `text`.
|
|
982
1045
|
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
1046
|
+
Then, within the same attribute, matches near the beginning of the text will be considered more important than matches near the end.
|
|
1047
|
+
You can disable this behavior by wrapping your attribute name inside an `unordered()` modifier. For example, `["title", "unordered(text)"]`
|
|
1048
|
+
will consider all positions inside the `text` attribute as equal, but positions inside the `title` attribute will still matter.
|
|
986
1049
|
|
|
987
|
-
|
|
1050
|
+
You can decide to have the same priority for several attributes by passing them in the same string using comma as separator.
|
|
1051
|
+
For example: \n`title` and `alternative_title` have the same priority in this example: `searchableAttributes:["title,alternative_title", "text"]`
|
|
988
1052
|
|
|
1053
|
+
To get a full description of how the ranking works, you can have a look at our [Ranking guide](https://www.algolia.com/doc/guides/relevance/ranking).
|
|
989
1054
|
|
|
990
1055
|
#### attributesForFaceting
|
|
991
1056
|
|
|
992
1057
|
- scope: `settings`
|
|
993
1058
|
- type: `array of strings`
|
|
994
|
-
- default: `null`
|
|
995
|
-
|
|
996
1059
|
|
|
997
1060
|
The list of attributes you want to use for faceting.
|
|
998
1061
|
All strings within these attributes will be extracted and added as facets.
|
|
999
1062
|
If set to `null`, no attribute is used for faceting.
|
|
1000
1063
|
|
|
1064
|
+
If you only need to filter on a given facet, you can specify filterOnly(attributeName). It reduces the size of the index and the build time.
|
|
1065
|
+
|
|
1066
|
+
If you want to search inside values of a given facet (using the [Search for facet values](#search-for-facet-values) method) you need to specify searchable(attributeName).
|
|
1001
1067
|
|
|
1002
1068
|
#### unretrievableAttributes
|
|
1003
1069
|
|
|
1004
1070
|
- scope: `settings`
|
|
1005
1071
|
- type: `array of strings`
|
|
1006
|
-
- default: `null`
|
|
1007
|
-
|
|
1008
1072
|
|
|
1009
1073
|
The list of attributes that cannot be retrieved at query time.
|
|
1010
1074
|
This feature allows you to have attributes that are used for indexing
|
|
1011
1075
|
and/or ranking but cannot be retrieved.
|
|
1012
1076
|
|
|
1013
|
-
|
|
1077
|
+
This setting will be bypassed if the query is done with the ADMIN API key
|
|
1078
|
+
{.alert .alert-info}
|
|
1014
1079
|
|
|
1015
1080
|
#### attributesToRetrieve
|
|
1016
1081
|
|
|
1017
|
-
- scope: `settings
|
|
1082
|
+
- scope: `settings` `search`
|
|
1018
1083
|
- type: `array of strings`
|
|
1019
|
-
- default:
|
|
1020
|
-
|
|
1084
|
+
- default: * (all attributes)
|
|
1021
1085
|
|
|
1022
|
-
|
|
1086
|
+
List of attributes you want to retrieve in the search response.
|
|
1087
|
+
This can be use to minimize the size of the JSON answer.
|
|
1023
1088
|
|
|
1024
|
-
|
|
1025
|
-
You can also use a string array encoding (for example `["name","address"]` ).
|
|
1026
|
-
By default, all attributes are retrieved.
|
|
1027
|
-
You can also use `*` to retrieve all values when an **attributesToRetrieve** setting is specified for your index.
|
|
1089
|
+
You can use `*` to retrieve all values.
|
|
1028
1090
|
|
|
1029
1091
|
**Note:** `objectID` is always retrieved, even when not specified.
|
|
1030
1092
|
|
|
1031
|
-
|
|
1032
1093
|
#### restrictSearchableAttributes
|
|
1033
1094
|
|
|
1034
1095
|
- scope: `search`
|
|
1035
1096
|
- type: `array of strings`
|
|
1036
|
-
- default:
|
|
1097
|
+
- default: all attributes in searchableAttributes
|
|
1037
1098
|
|
|
1099
|
+
List of attributes you want to use for textual search.
|
|
1038
1100
|
|
|
1039
|
-
|
|
1040
|
-
Attributes are separated with a comma such as `"name,address"`.
|
|
1041
|
-
You can also use JSON string array encoding such as `encodeURIComponent("[\"name\",\"address\"]")`.
|
|
1042
|
-
By default, all attributes specified in the `searchableAttributes` settings are used to search.
|
|
1101
|
+
It must be a subset of the `searchableAttributes` index setting.
|
|
1043
1102
|
|
|
1103
|
+
SearchableAttributes must not be empty/null to be able to use this parameter.
|
|
1044
1104
|
|
|
1045
|
-
|
|
1105
|
+
## Ranking
|
|
1046
1106
|
|
|
1047
1107
|
#### ranking
|
|
1048
1108
|
|
|
1049
1109
|
- scope: `settings`
|
|
1050
1110
|
- type: `array of strings`
|
|
1051
|
-
- default:
|
|
1052
|
-
|
|
1111
|
+
- default: ['typo', 'geo', 'words', 'filters', 'proximity', 'attribute', 'exact', 'custom']
|
|
1053
1112
|
|
|
1054
1113
|
Controls the way results are sorted.
|
|
1055
1114
|
|
|
@@ -1067,15 +1126,13 @@ We have nine available criterion:
|
|
|
1067
1126
|
* `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).
|
|
1068
1127
|
* `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).
|
|
1069
1128
|
|
|
1070
|
-
To get a full description of how the Ranking works,
|
|
1071
|
-
you can have a look at our [Ranking guide](https://www.algolia.com/doc/guides/relevance/ranking).
|
|
1129
|
+
To get a full description of how the Ranking works, you can have a look at our [Ranking guide](https://www.algolia.com/doc/guides/relevance/ranking).
|
|
1072
1130
|
|
|
1073
1131
|
#### customRanking
|
|
1074
1132
|
|
|
1075
1133
|
- scope: `settings`
|
|
1076
1134
|
- type: `array of strings`
|
|
1077
|
-
- default:
|
|
1078
|
-
|
|
1135
|
+
- default: []
|
|
1079
1136
|
|
|
1080
1137
|
Lets you specify part of the ranking.
|
|
1081
1138
|
|
|
@@ -1091,10 +1148,9 @@ you can have a look at our [Ranking guide](https://www.algolia.com/doc/guides/re
|
|
|
1091
1148
|
|
|
1092
1149
|
- scope: `settings`
|
|
1093
1150
|
- type: `array of strings`
|
|
1094
|
-
- default:
|
|
1151
|
+
- default: []
|
|
1095
1152
|
- formerly known as: `slaves`
|
|
1096
1153
|
|
|
1097
|
-
|
|
1098
1154
|
The list of indices on which you want to replicate all write operations.
|
|
1099
1155
|
|
|
1100
1156
|
In order to get response times in milliseconds, we pre-compute part of the ranking during indexing.
|
|
@@ -1105,14 +1161,13 @@ you need to create one index per ranking configuration.
|
|
|
1105
1161
|
This option enables you to perform write operations only on this index and automatically
|
|
1106
1162
|
update replica indices with the same operations.
|
|
1107
1163
|
|
|
1108
|
-
|
|
1164
|
+
## Filtering / Faceting
|
|
1109
1165
|
|
|
1110
1166
|
#### filters
|
|
1111
1167
|
|
|
1112
1168
|
- scope: `search`
|
|
1113
1169
|
- type: `string`
|
|
1114
|
-
- default:
|
|
1115
|
-
|
|
1170
|
+
- default: ""
|
|
1116
1171
|
|
|
1117
1172
|
Filter the query with numeric, facet or/and tag filters.
|
|
1118
1173
|
|
|
@@ -1122,41 +1177,39 @@ The syntax for the underlying numeric, facet and tag filters is the same than in
|
|
|
1122
1177
|
`available=1 AND (category:Book OR NOT category:Ebook) AND _tags:public`
|
|
1123
1178
|
`date: 1441745506 TO 1441755506 AND inStock > 0 AND author:"John Doe"`
|
|
1124
1179
|
|
|
1180
|
+
The list of keywords is:
|
|
1181
|
+
|
|
1182
|
+
- **OR**: create a OR between two filters.
|
|
1183
|
+
- **AND**: create a AND between two filters.
|
|
1184
|
+
- **TO**: used to specify a range for a numeric filter.
|
|
1185
|
+
- **NOT**: used to negate a filter.
|
|
1186
|
+
|
|
1125
1187
|
If no attribute name is specified,
|
|
1126
1188
|
the filter applies to `_tags`.
|
|
1127
|
-
|
|
1128
1189
|
For example: `public OR user_42` will translate to `_tags:public OR _tags:user_42`.
|
|
1129
1190
|
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
* `OR`: create a disjunctive filter between two filters.
|
|
1133
|
-
* `AND`: create a conjunctive filter between two filters.
|
|
1134
|
-
* `TO`: used to specify a range for a numeric filter.
|
|
1135
|
-
* `NOT`: used to negate a filter. The syntax with the `-` isn’t allowed.
|
|
1191
|
+
To specify a value with spaces or with a value equal to a keyword, it's possible to add quotes.
|
|
1136
1192
|
|
|
1137
|
-
|
|
1193
|
+
Like for the other filter for performance reason, it's not possible to have FILTER1 OR (FILTER2 AND FILTER3).
|
|
1138
1194
|
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
* Like for the other filters (for performance reasons), it's not possible to have `FILTER1 OR (FILTER2 AND FILTER3)`.
|
|
1142
|
-
* It is not possible to mix different categories of filters inside an OR like: `num=3 OR tag1 OR facet:value`.
|
|
1143
|
-
* It is not possible to negate a group; only individual filters can be negated: `NOT(FILTER1 OR (FILTER2))` is not allowed.
|
|
1195
|
+
It's not possible to mix different category of filter inside a OR like num=3 OR tag1 OR facet:value
|
|
1144
1196
|
|
|
1197
|
+
It's not possible to negate an group, it's only possible to negate a filter: NOT(FILTER1 OR FILTER2) is not allowed.
|
|
1145
1198
|
|
|
1146
1199
|
#### facets
|
|
1147
1200
|
|
|
1148
1201
|
- scope: `search`
|
|
1149
|
-
- type: `string`
|
|
1150
|
-
- default:
|
|
1151
|
-
|
|
1202
|
+
- type: `array of string`
|
|
1203
|
+
- default: []
|
|
1152
1204
|
|
|
1153
1205
|
You can use [facets](#facets) to retrieve only a part of your attributes declared in
|
|
1154
1206
|
**[attributesForFaceting](#attributesforfaceting)** attributes.
|
|
1155
|
-
It will not filter your results, if you want to filter results you should use [filters](#filters).
|
|
1156
1207
|
|
|
1157
1208
|
For each of the declared attributes, you'll be able to retrieve a list of the most relevant facet values,
|
|
1158
1209
|
and their associated count for the current query.
|
|
1159
1210
|
|
|
1211
|
+
It will not filter your results, if you want to filter results you should use [filters](#filters).
|
|
1212
|
+
|
|
1160
1213
|
**Example**
|
|
1161
1214
|
|
|
1162
1215
|
If you have defined in your **[attributesForFaceting](#attributesforfaceting)**:
|
|
@@ -1171,44 +1224,53 @@ If you have defined in your **[attributesForFaceting](#attributesforfaceting)**:
|
|
|
1171
1224
|
["category", "author"]
|
|
1172
1225
|
```
|
|
1173
1226
|
|
|
1174
|
-
**
|
|
1227
|
+
When using [facets](#facets) in a search query, only attributes that have been added in **attributesForFaceting** index setting can be used in this parameter.
|
|
1175
1228
|
|
|
1176
|
-
- When using [facets](#facets) in a search query, only attributes that have been added in **attributesForFaceting** index setting can be used in this parameter.
|
|
1177
1229
|
You can also use `*` to perform faceting on all attributes specified in `attributesForFaceting`.
|
|
1178
|
-
|
|
1179
|
-
the attribute `exhaustiveFacetsCount` in the response is true when the count is exact.
|
|
1230
|
+
|
|
1231
|
+
If the number of results is important, the count can be approximate, the attribute `exhaustiveFacetsCount` in the response is true when the count is exact.
|
|
1180
1232
|
|
|
1181
1233
|
#### maxValuesPerFacet
|
|
1182
1234
|
|
|
1183
|
-
- scope: `settings
|
|
1235
|
+
- scope: `settings` `search`
|
|
1184
1236
|
- type: `integer`
|
|
1185
|
-
- default:
|
|
1186
|
-
|
|
1237
|
+
- default: 100
|
|
1187
1238
|
|
|
1188
1239
|
Limit the number of facet values returned for each facet.
|
|
1189
1240
|
|
|
1190
1241
|
For example, `maxValuesPerFacet=10` will retrieve a maximum of 10 values per facet.
|
|
1191
1242
|
|
|
1192
1243
|
**Warnings**
|
|
1193
|
-
|
|
1194
1244
|
- The engine has a hard limit on the `maxValuesPerFacet` of `1000`. Any value above that will be interpreted by the engine as being `1000`.
|
|
1195
1245
|
|
|
1196
|
-
|
|
1246
|
+
#### facetFilters
|
|
1197
1247
|
|
|
1198
|
-
|
|
1248
|
+
- scope: `search`
|
|
1249
|
+
- type: `array of string`
|
|
1250
|
+
- default: ""
|
|
1199
1251
|
|
|
1200
|
-
|
|
1201
|
-
|
|
1202
|
-
|
|
1252
|
+
**Warning**: We introduce the [filters](#filters) parameter that provide a SQL like syntax
|
|
1253
|
+
and is easier to use for most usecases
|
|
1254
|
+
|
|
1255
|
+
Filter the query with a list of facets. A Facet is encoded as key value like this: `attributeName:value`.
|
|
1256
|
+
|
|
1257
|
+
`["category:Book","author:John%20Doe"]` will translate to `category:Book` AND `author:John%20Doe`
|
|
1258
|
+
|
|
1259
|
+
You can also OR facets: `[["category:Book","category:Movie"],"author:John%20Doe"]`, will translate to
|
|
1260
|
+
`(category:Book OR category:Movie) AND author:John%20Doe`
|
|
1203
1261
|
|
|
1262
|
+
## Highlighting / Snippeting
|
|
1204
1263
|
|
|
1205
|
-
|
|
1264
|
+
#### attributesToHighlight
|
|
1265
|
+
|
|
1266
|
+
- scope: `settings` `search`
|
|
1267
|
+
- type: `array of string`
|
|
1268
|
+
|
|
1269
|
+
List of attributes to highlight.
|
|
1206
1270
|
If set to null, all indexed attributes are highlighted.
|
|
1207
1271
|
|
|
1208
|
-
|
|
1209
|
-
|
|
1210
|
-
You can also use a string array encoding (for example `["name","address"]`).
|
|
1211
|
-
If an attribute has no match for the query, the raw value is returned.
|
|
1272
|
+
An attribute has no match for the query, the raw value is returned.
|
|
1273
|
+
|
|
1212
1274
|
By default, all indexed attributes are highlighted (as long as they are strings).
|
|
1213
1275
|
You can use `*` if you want to highlight all attributes.
|
|
1214
1276
|
|
|
@@ -1220,64 +1282,53 @@ A matchLevel is returned for each highlighted attribute and can contain:
|
|
|
1220
1282
|
|
|
1221
1283
|
#### attributesToSnippet
|
|
1222
1284
|
|
|
1223
|
-
- scope: `settings
|
|
1285
|
+
- scope: `settings` `search`
|
|
1224
1286
|
- type: `array of strings`
|
|
1225
|
-
- default:
|
|
1287
|
+
- default: [] (no attribute is snippeted)
|
|
1226
1288
|
|
|
1227
|
-
|
|
1228
|
-
Default list of attributes to snippet alongside the number of words to return (syntax is `attributeName:nbWords`).
|
|
1229
|
-
If set to null, no snippet is computed.
|
|
1289
|
+
List of attributes to snippet alongside the number of words to return (syntax is `attributeName:nbWords`).
|
|
1230
1290
|
|
|
1231
1291
|
#### highlightPreTag
|
|
1232
1292
|
|
|
1233
|
-
- scope: `settings
|
|
1293
|
+
- scope: `settings` `search`
|
|
1234
1294
|
- type: `string`
|
|
1235
|
-
- default:
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
Specify the string that is inserted before the highlighted parts in the query result (defaults to `<em>`).
|
|
1239
|
-
|
|
1295
|
+
- default: <em>
|
|
1240
1296
|
|
|
1297
|
+
Specify the string that is inserted before the highlighted parts in the query result
|
|
1241
1298
|
|
|
1242
1299
|
#### highlightPostTag
|
|
1243
1300
|
|
|
1244
|
-
- scope: `settings
|
|
1301
|
+
- scope: `settings` `search`
|
|
1245
1302
|
- type: `string`
|
|
1246
|
-
- default:
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
Specify the string that is inserted after the highlighted parts in the query result (defaults to `</em>`).
|
|
1250
|
-
|
|
1303
|
+
- default: </em>
|
|
1251
1304
|
|
|
1305
|
+
Specify the string that is inserted after the highlighted parts in the query result.
|
|
1252
1306
|
|
|
1253
1307
|
#### snippetEllipsisText
|
|
1254
1308
|
|
|
1255
|
-
- scope: `settings
|
|
1309
|
+
- scope: `settings` `search`
|
|
1256
1310
|
- type: `string`
|
|
1257
|
-
- default:
|
|
1258
|
-
|
|
1311
|
+
- default: ...
|
|
1259
1312
|
|
|
1260
1313
|
String used as an ellipsis indicator when a snippet is truncated.
|
|
1261
1314
|
|
|
1262
|
-
|
|
1315
|
+
Defaults to an empty string for all accounts created before 10/2/2016, and to `…` (U+2026) for accounts created after that date.
|
|
1263
1316
|
|
|
1264
1317
|
#### restrictHighlightAndSnippetArrays
|
|
1265
1318
|
|
|
1266
|
-
- scope: `settings
|
|
1319
|
+
- scope: `settings` `search`
|
|
1267
1320
|
- type: `boolean`
|
|
1268
|
-
- default:
|
|
1269
|
-
|
|
1321
|
+
- default: false
|
|
1270
1322
|
|
|
1271
1323
|
If set to true, restrict arrays in highlights and snippets to items that matched the query at least partially else return all array items in highlights and snippets.
|
|
1272
1324
|
|
|
1273
|
-
|
|
1325
|
+
## Pagination
|
|
1274
1326
|
|
|
1275
1327
|
#### page
|
|
1276
1328
|
|
|
1277
1329
|
- scope: `search`
|
|
1278
1330
|
- type: `integer`
|
|
1279
|
-
- default:
|
|
1280
|
-
|
|
1331
|
+
- default: 0
|
|
1281
1332
|
|
|
1282
1333
|
Pagination parameter used to select the page to retrieve.
|
|
1283
1334
|
|
|
@@ -1285,10 +1336,9 @@ Pagination parameter used to select the page to retrieve.
|
|
|
1285
1336
|
|
|
1286
1337
|
#### hitsPerPage
|
|
1287
1338
|
|
|
1288
|
-
- scope: `settings
|
|
1339
|
+
- scope: `settings` `search`
|
|
1289
1340
|
- type: `integer`
|
|
1290
|
-
- default:
|
|
1291
|
-
|
|
1341
|
+
- default: 20
|
|
1292
1342
|
|
|
1293
1343
|
Pagination parameter used to select the number of hits per page.
|
|
1294
1344
|
|
|
@@ -1296,96 +1346,136 @@ Pagination parameter used to select the number of hits per page.
|
|
|
1296
1346
|
|
|
1297
1347
|
- scope: `search`
|
|
1298
1348
|
- type: `integer`
|
|
1299
|
-
- default: `null`
|
|
1300
|
-
|
|
1301
1349
|
|
|
1302
1350
|
Offset of the first hit to return (zero-based).
|
|
1303
1351
|
|
|
1304
|
-
**Warning:** In most cases, `page`/`hitsPerPage` is the recommended method for pagination
|
|
1352
|
+
**Warning:** In most cases, `page`/`hitsPerPage` is the recommended method for pagination.
|
|
1305
1353
|
|
|
1306
1354
|
#### length
|
|
1307
1355
|
|
|
1308
1356
|
- scope: `search`
|
|
1309
1357
|
- type: `integer`
|
|
1310
|
-
- default: `null`
|
|
1311
1358
|
|
|
1359
|
+
Offset of the first hit to return (zero-based).
|
|
1360
|
+
|
|
1361
|
+
**Warning:** In most cases, `page`/`hitsPerPage` is the recommended method for pagination.
|
|
1362
|
+
|
|
1363
|
+
#### paginationLimitedTo
|
|
1364
|
+
|
|
1365
|
+
- scope: `settings`
|
|
1366
|
+
- type: `integer`
|
|
1367
|
+
- default: 1000
|
|
1312
1368
|
|
|
1313
|
-
|
|
1369
|
+
Allows to control the maximum number of hits accessible via pagination.
|
|
1370
|
+
By default, this parameter is limited to 1000 to guarantee good performance.
|
|
1314
1371
|
|
|
1315
|
-
**Warning:**
|
|
1372
|
+
**Warning:** We recommend to keep the default value to guarantee excellent performance.
|
|
1373
|
+
Increasing this limit will have a direct impact on the performance of search.
|
|
1374
|
+
A big value will also make it very easy for anyone to download all your dataset.
|
|
1316
1375
|
|
|
1317
|
-
|
|
1376
|
+
## Typos
|
|
1318
1377
|
|
|
1319
1378
|
#### minWordSizefor1Typo
|
|
1320
1379
|
|
|
1321
|
-
- scope: `settings
|
|
1380
|
+
- scope: `settings` `search`
|
|
1322
1381
|
- type: `integer`
|
|
1323
|
-
- default:
|
|
1382
|
+
- default: 4
|
|
1324
1383
|
|
|
1325
|
-
|
|
1326
|
-
The minimum number of characters needed to accept one typo.
|
|
1384
|
+
The minimum number of characters in the query string needed to accept results matching with one typo.
|
|
1327
1385
|
|
|
1328
1386
|
#### minWordSizefor2Typos
|
|
1329
1387
|
|
|
1330
|
-
- scope: `settings
|
|
1388
|
+
- scope: `settings` `search`
|
|
1331
1389
|
- type: `integer`
|
|
1332
|
-
- default:
|
|
1333
|
-
|
|
1390
|
+
- default: 8
|
|
1334
1391
|
|
|
1335
|
-
The minimum number of characters needed to accept two typos.
|
|
1392
|
+
The minimum number of characters in the query string needed to accept results matching with two typos.
|
|
1336
1393
|
|
|
1337
1394
|
#### typoTolerance
|
|
1338
1395
|
|
|
1339
|
-
- scope: `settings
|
|
1340
|
-
- type: `
|
|
1341
|
-
- default:
|
|
1342
|
-
|
|
1396
|
+
- scope: `settings` `search`
|
|
1397
|
+
- type: `string`
|
|
1398
|
+
- default: true
|
|
1343
1399
|
|
|
1344
1400
|
This option allows you to control the number of typos allowed in the result set:
|
|
1345
1401
|
|
|
1346
|
-
* `true`:
|
|
1347
|
-
|
|
1348
|
-
|
|
1349
|
-
* `
|
|
1402
|
+
* `true`:
|
|
1403
|
+
The typo tolerance is enabled and all matching hits are retrieved (default behavior).
|
|
1404
|
+
|
|
1405
|
+
* `false`:
|
|
1406
|
+
The typo tolerance is disabled. All results with typos will be hidden.
|
|
1350
1407
|
|
|
1408
|
+
* `min`:
|
|
1409
|
+
Only keep results with the minimum number of typos. For example, if one result matches without typos, then all results with typos will be hidden.
|
|
1410
|
+
|
|
1411
|
+
* `strict`:
|
|
1412
|
+
Hits matching with 2 typos or more are not retrieved if there are some matching without typos.
|
|
1413
|
+
This option is useful if you want to avoid as much as possible false positive.
|
|
1351
1414
|
|
|
1352
1415
|
#### allowTyposOnNumericTokens
|
|
1353
1416
|
|
|
1354
|
-
- scope: `settings
|
|
1417
|
+
- scope: `settings` `search`
|
|
1355
1418
|
- type: `boolean`
|
|
1356
|
-
- default:
|
|
1419
|
+
- default: true
|
|
1357
1420
|
|
|
1421
|
+
If set to false, disable typo-tolerance on numeric tokens (numbers) in the query string.
|
|
1422
|
+
For example the query `\"304\"` will match with `\"30450\"`, but not with `\"40450\"`
|
|
1423
|
+
that would have been the case with typo-tolerance enabled.
|
|
1358
1424
|
|
|
1359
|
-
|
|
1425
|
+
This option can be very useful on serial numbers and zip codes searches.
|
|
1360
1426
|
|
|
1361
1427
|
#### ignorePlurals
|
|
1362
1428
|
|
|
1363
|
-
- scope: `settings
|
|
1364
|
-
- type: `boolean`
|
|
1365
|
-
- default:
|
|
1429
|
+
- scope: `settings` `search`
|
|
1430
|
+
- type: `boolean` `array of strings`
|
|
1431
|
+
- default: true
|
|
1366
1432
|
|
|
1433
|
+
Consider singular and plurals forms a match without typo.
|
|
1434
|
+
For example, car and cars, or foot and feet will be considered equivalent.
|
|
1367
1435
|
|
|
1368
|
-
|
|
1436
|
+
This parameter can be:
|
|
1369
1437
|
|
|
1370
|
-
|
|
1438
|
+
- a **boolean**: enable or disable plurals for all 59 supported languages.
|
|
1439
|
+
- a **list of language ISO codes** for which plurals should be enabled.
|
|
1371
1440
|
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1441
|
+
This option is set to `false` by default.
|
|
1442
|
+
|
|
1443
|
+
Here is the list of supported languages:
|
|
1444
|
+
|
|
1445
|
+
Afrikaans=`af`, Arabic=`ar`, Azeri=`az`, Bulgarian=`bg`, Catalan=`ca`,
|
|
1446
|
+
Czech=`cs`, Welsh=`cy`, Danis=`da`, German=`de`, English=`en`,
|
|
1447
|
+
Esperanto=`eo`, Spanish=`es`, Estonian=`et`, Basque=`eu`, Finnish=`fi`,
|
|
1448
|
+
Faroese=`fo`, French=`fr`, Galician=`gl`, Hebrew=`he`, Hindi=`hi`,
|
|
1449
|
+
Hungarian=`hu`, Armenian=`hy`, Indonesian=`id`, Icelandic=`is`, Italian=`it`,
|
|
1450
|
+
Japanese=`ja`, Georgian=`ka`, Kazakh=`kk`, Korean=`ko`, Kyrgyz=`ky`,
|
|
1451
|
+
Lithuanian=`lt`, Maori=`mi`, Mongolian=`mn`, Marathi=`mr`, Malay=`ms`,
|
|
1452
|
+
Maltese=`mt`, Norwegian=`nb`, Dutch=`nl`, Northern Sotho=`ns`, Polish=`pl`,
|
|
1453
|
+
Pashto=`ps`, Portuguese=`pt`, Quechua=`qu`, Romanian=`ro`, Russian=`ru`,
|
|
1454
|
+
Slovak=`sk`, Albanian=`sq`, Swedish=`sv`, Swahili=`sw`, Tamil=`ta`,
|
|
1455
|
+
Telugu=`te`, Tagalog=`tl`, Tswana=`tn`, Turkish=`tr`, Tatar=`tt`,
|
|
1456
|
+
|
|
1457
|
+
#### disableTypoToleranceOnAttributes
|
|
1375
1458
|
|
|
1459
|
+
- scope: `settings` `search`
|
|
1460
|
+
- type: `array of strings`
|
|
1461
|
+
- default: []
|
|
1376
1462
|
|
|
1377
1463
|
List of attributes on which you want to disable typo tolerance
|
|
1378
1464
|
(must be a subset of the `searchableAttributes` index setting).
|
|
1379
1465
|
|
|
1380
|
-
|
|
1381
|
-
|
|
1466
|
+
#### disableTypoToleranceOnWords
|
|
1467
|
+
|
|
1468
|
+
- scope: `settings`
|
|
1469
|
+
- type: `array of strings`
|
|
1470
|
+
- default: []
|
|
1471
|
+
|
|
1472
|
+
Specify a list of words on which the automatic typo tolerance will be disabled.
|
|
1382
1473
|
|
|
1383
1474
|
#### separatorsToIndex
|
|
1384
1475
|
|
|
1385
1476
|
- scope: `settings`
|
|
1386
1477
|
- type: `string`
|
|
1387
|
-
- default:
|
|
1388
|
-
|
|
1478
|
+
- default: ""
|
|
1389
1479
|
|
|
1390
1480
|
Specify the separators (punctuation characters) to index.
|
|
1391
1481
|
|
|
@@ -1393,9 +1483,7 @@ By default, separators are not indexed.
|
|
|
1393
1483
|
|
|
1394
1484
|
**Example:** Use `+#` to be able to search for "Google+" or "C#".
|
|
1395
1485
|
|
|
1396
|
-
|
|
1397
|
-
|
|
1398
|
-
### Geo-Search
|
|
1486
|
+
## Geo-Search
|
|
1399
1487
|
|
|
1400
1488
|
Geo search requires that you provide at least one geo location in each record at indexing time, under the `_geoloc` attribute. Each location must be an object with two numeric `lat` and `lng` attributes. You may specify either one location:
|
|
1401
1489
|
|
|
@@ -1425,39 +1513,27 @@ Geo search requires that you provide at least one geo location in each record at
|
|
|
1425
1513
|
}
|
|
1426
1514
|
```
|
|
1427
1515
|
|
|
1428
|
-
|
|
1429
|
-
|
|
1430
|
-
|
|
1431
1516
|
#### aroundLatLng
|
|
1432
1517
|
|
|
1433
1518
|
- scope: `search`
|
|
1434
1519
|
- type: `string`
|
|
1435
|
-
- default:
|
|
1436
|
-
|
|
1520
|
+
- default: ""
|
|
1437
1521
|
|
|
1438
1522
|
Search for entries around a given location (specified as two floats separated by a comma).
|
|
1439
1523
|
|
|
1440
1524
|
For example, `aroundLatLng=47.316669,5.016670`.
|
|
1441
1525
|
|
|
1442
1526
|
- By default the maximum distance is automatically guessed based on the density of the area
|
|
1443
|
-
but you can specify it manually in meters with the **aroundRadius** parameter.
|
|
1444
|
-
The precision for ranking can be set with **aroundPrecision** parameter.
|
|
1527
|
+
but you can specify it manually in meters with the **aroundRadius** parameter.
|
|
1528
|
+
The precision for ranking can be set with **aroundPrecision** parameter.
|
|
1445
1529
|
- If you set aroundPrecision=100, the distances will be considered by ranges of 100m.
|
|
1446
1530
|
- For example all distances 0 and 100m will be considered as identical for the "geo" ranking parameter.
|
|
1447
1531
|
|
|
1448
|
-
When `aroundRadius` is not set, the radius is computed automatically using the density of the area; you can retrieve the computed value in the `automaticRadius` attribute of the response.
|
|
1449
|
-
You can also use the `minimumAroundRadius` query parameter to specify a minimum radius in meters for the automatic computation of `aroundRadius`.
|
|
1450
|
-
|
|
1451
|
-
|
|
1452
|
-
|
|
1453
|
-
|
|
1454
|
-
|
|
1455
1532
|
#### aroundLatLngViaIP
|
|
1456
1533
|
|
|
1457
1534
|
- scope: `search`
|
|
1458
|
-
- type: `
|
|
1459
|
-
- default:
|
|
1460
|
-
|
|
1535
|
+
- type: `boolean`
|
|
1536
|
+
- default: false
|
|
1461
1537
|
|
|
1462
1538
|
Search for entries around a given latitude/longitude automatically computed from user IP address.
|
|
1463
1539
|
|
|
@@ -1471,47 +1547,50 @@ For example:
|
|
|
1471
1547
|
two objects that are in the range 0-99m
|
|
1472
1548
|
will be considered as identical in the ranking for the "geo" ranking parameter (same for 100-199, 200-299, ... ranges).
|
|
1473
1549
|
|
|
1474
|
-
|
|
1475
|
-
|
|
1476
1550
|
#### aroundRadius
|
|
1477
1551
|
|
|
1478
1552
|
- scope: `search`
|
|
1479
|
-
- type: `integer
|
|
1480
|
-
- default: `null`
|
|
1481
|
-
|
|
1553
|
+
- type: `integer` `string`
|
|
1482
1554
|
|
|
1483
1555
|
Control the radius associated with a geo search. Defined in meters.
|
|
1484
1556
|
|
|
1485
|
-
If not set, the radius is computed automatically using the density of the area.
|
|
1557
|
+
If not set, the radius is computed automatically using the density of the area.
|
|
1558
|
+
You can retrieve the computed radius in the `automaticRadius` attribute of the response.
|
|
1559
|
+
You can also specify a minimum value for the automatic radius by using the `minimumAroundRadius` query parameter.
|
|
1560
|
+
|
|
1561
|
+
You can specify `aroundRadius=all` if you want to compute the geo distance without filtering in a geo area;
|
|
1562
|
+
this option will be faster than specifying a big integer value.
|
|
1486
1563
|
|
|
1487
1564
|
#### aroundPrecision
|
|
1488
1565
|
|
|
1489
1566
|
- scope: `search`
|
|
1490
1567
|
- type: `integer`
|
|
1491
|
-
- default: `null`
|
|
1492
1568
|
|
|
1569
|
+
Control the precision of a geo search.
|
|
1570
|
+
Defined in meters.
|
|
1493
1571
|
|
|
1494
|
-
|
|
1572
|
+
For example, if you set `aroundPrecision=100`, two objects that are in the range 0-99m will be considered as
|
|
1573
|
+
identical in the ranking for the `geo` ranking parameter (same for 100-199, 200-299, … ranges).
|
|
1495
1574
|
|
|
1496
1575
|
#### minimumAroundRadius
|
|
1497
1576
|
|
|
1498
1577
|
- scope: `search`
|
|
1499
1578
|
- type: `integer`
|
|
1500
|
-
- default: `null`
|
|
1501
1579
|
|
|
1502
|
-
|
|
1503
|
-
|
|
1580
|
+
Define the minimum radius used for a geo search when `aroundRadius` is not set.
|
|
1581
|
+
The radius is computed automatically using the density of the area.
|
|
1582
|
+
You can retrieve the computed radius in the `automaticRadius` attribute of the answer.
|
|
1504
1583
|
|
|
1505
1584
|
#### insideBoundingBox
|
|
1506
1585
|
|
|
1507
1586
|
- scope: `search`
|
|
1508
1587
|
- type: `string`
|
|
1509
|
-
- default: `null`
|
|
1510
|
-
|
|
1511
1588
|
|
|
1512
1589
|
Search entries inside a given area defined by the two extreme points of a rectangle
|
|
1513
1590
|
(defined by 4 floats: p1Lat,p1Lng,p2Lat,p2Lng).
|
|
1591
|
+
|
|
1514
1592
|
For example:
|
|
1593
|
+
|
|
1515
1594
|
- `insideBoundingBox=47.3165,4.9665,47.3424,5.0201`
|
|
1516
1595
|
|
|
1517
1596
|
You can use several bounding boxes (OR) by passing more than 4 values.
|
|
@@ -1521,86 +1600,95 @@ For example: instead of having 4 values you can pass 8 to search inside the UNIO
|
|
|
1521
1600
|
|
|
1522
1601
|
- scope: `search`
|
|
1523
1602
|
- type: `string`
|
|
1524
|
-
- default:
|
|
1525
|
-
|
|
1603
|
+
- default: ""
|
|
1526
1604
|
|
|
1527
1605
|
Search entries inside a given area defined by a set of points
|
|
1528
|
-
(defined by a minimum of 6 floats: p1Lat,p1Lng,p2Lat,p2Lng,p3Lat,p3Long).
|
|
1529
|
-
|
|
1530
|
-
For example:
|
|
1531
|
-
`InsidePolygon=47.3165,4.9665,47.3424,5.0201,47.32,4.98`).
|
|
1606
|
+
(defined by a minimum of 6 floats: p1Lat,p1Lng,p2Lat,p2Lng,p3Lat,p3Long).
|
|
1532
1607
|
|
|
1608
|
+
For example:
|
|
1609
|
+
|
|
1610
|
+
- `InsidePolygon=47.3165,4.9665,47.3424,5.0201,47.32,4.98`
|
|
1611
|
+
|
|
1533
1612
|
|
|
1534
|
-
|
|
1613
|
+
## Query Strategy
|
|
1535
1614
|
|
|
1536
1615
|
#### queryType
|
|
1537
1616
|
|
|
1538
|
-
- scope: `settings
|
|
1539
|
-
- type: `
|
|
1540
|
-
- default:
|
|
1541
|
-
|
|
1617
|
+
- scope: `settings`
|
|
1618
|
+
- type: `string`
|
|
1619
|
+
- default: prefixLast
|
|
1542
1620
|
|
|
1543
1621
|
Selects how the query words are interpreted. It can be one of the following values:
|
|
1544
|
-
|
|
1545
|
-
All query words are interpreted as prefixes. This option is not recommended.
|
|
1622
|
+
|
|
1546
1623
|
* `prefixLast`:
|
|
1547
|
-
Only the last word is interpreted as a prefix (default behavior).
|
|
1624
|
+
Only the last word is interpreted as a prefix (default behavior).
|
|
1625
|
+
|
|
1626
|
+
* `prefixAll`:
|
|
1627
|
+
All query words are interpreted as prefixes. This option is not recommended.
|
|
1628
|
+
|
|
1548
1629
|
* `prefixNone`:
|
|
1549
|
-
No query word is interpreted as a prefix. This option is not recommended.
|
|
1630
|
+
No query word is interpreted as a prefix. This option is not recommended.
|
|
1550
1631
|
|
|
1551
1632
|
#### removeWordsIfNoResults
|
|
1552
1633
|
|
|
1553
|
-
- scope: `settings
|
|
1634
|
+
- scope: `settings` `search`
|
|
1554
1635
|
- type: `string`
|
|
1555
|
-
- default:
|
|
1636
|
+
- default: none
|
|
1556
1637
|
|
|
1638
|
+
This option is used to select a removing of words strategy when the query doesn't retrieve any results.
|
|
1639
|
+
It can be used to avoid having an empty result page
|
|
1557
1640
|
|
|
1558
|
-
This option is used to select a strategy in order to avoid having an empty result page.
|
|
1559
1641
|
There are four different options:
|
|
1560
1642
|
|
|
1643
|
+
- `none`:
|
|
1644
|
+
No specific processing is done when a query does not return any results (default behavior).
|
|
1645
|
+
|
|
1561
1646
|
- `lastWords`:
|
|
1562
|
-
When a query does not return any results, the last word will be added as optional.
|
|
1563
|
-
The process is repeated with n-1 word, n-2 word, ... until there are results.
|
|
1647
|
+
When a query does not return any results, the last word will be added as optional.
|
|
1648
|
+
The process is repeated with n-1 word, n-2 word, ... until there are results.
|
|
1649
|
+
|
|
1564
1650
|
- `firstWords`:
|
|
1565
|
-
When a query does not return any results, the first word will be added as optional.
|
|
1566
|
-
The process is repeated with second word, third word, ... until there are results.
|
|
1651
|
+
When a query does not return any results, the first word will be added as optional.
|
|
1652
|
+
The process is repeated with second word, third word, ... until there are results.
|
|
1567
1653
|
- `allOptional`:
|
|
1568
|
-
When a query does not return any results, a second trial will be made with all words as optional.
|
|
1569
|
-
This is equivalent to transforming the AND operand between query terms to an OR operand.
|
|
1570
|
-
- `none`:
|
|
1571
|
-
No specific processing is done when a query does not return any results (default behavior).
|
|
1572
|
-
|
|
1654
|
+
When a query does not return any results, a second trial will be made with all words as optional.
|
|
1655
|
+
This is equivalent to transforming the AND operand between query terms to an OR operand.
|
|
1573
1656
|
|
|
1574
1657
|
#### advancedSyntax
|
|
1575
1658
|
|
|
1576
|
-
- scope: `settings
|
|
1659
|
+
- scope: `settings` `search`
|
|
1577
1660
|
- type: `boolean`
|
|
1578
|
-
- default:
|
|
1579
|
-
|
|
1661
|
+
- default: false
|
|
1580
1662
|
|
|
1581
1663
|
Enables the advanced query syntax.
|
|
1582
1664
|
|
|
1583
1665
|
This syntax allow to do two things:
|
|
1584
1666
|
|
|
1585
|
-
|
|
1586
|
-
|
|
1667
|
+
- **Phrase query**: A phrase query defines a particular sequence of terms. A phrase query needs to be surrounded by `"`.
|
|
1668
|
+
For example, `"search engine"` will retrieve records having `search` next to `engine` only.
|
|
1587
1669
|
|
|
1670
|
+
Typo tolerance is disabled inside the phrase (inside the `"`).
|
|
1671
|
+
|
|
1672
|
+
|
|
1673
|
+
- **Prohibit operator**: The prohibit operator excludes records that contain the term after the `-` symbol.
|
|
1674
|
+
For example, `search -engine` will retrieve records containing `search` but not `engine`.
|
|
1588
1675
|
|
|
1589
1676
|
#### optionalWords
|
|
1590
1677
|
|
|
1591
|
-
- scope: `settings
|
|
1592
|
-
- type: `array of
|
|
1593
|
-
- default:
|
|
1678
|
+
- scope: `settings` `search`
|
|
1679
|
+
- type: `string` `array of string`
|
|
1680
|
+
- default: ""
|
|
1594
1681
|
|
|
1682
|
+
The list of words that should be considered as optional when found in the query.
|
|
1595
1683
|
|
|
1596
|
-
|
|
1684
|
+
If you use the specify the optionnal words with a string you don't need to put coma in between words.
|
|
1685
|
+
The engine will tokenize the string into words that will all be considered as optional.
|
|
1597
1686
|
|
|
1598
1687
|
#### removeStopWords
|
|
1599
1688
|
|
|
1600
|
-
- scope: `settings
|
|
1601
|
-
- type: `boolean
|
|
1602
|
-
- default:
|
|
1603
|
-
|
|
1689
|
+
- scope: `settings` `search`
|
|
1690
|
+
- type: `boolean` `array of string`
|
|
1691
|
+
- default: false
|
|
1604
1692
|
|
|
1605
1693
|
Remove stop words from the query **before** executing it. It can be:
|
|
1606
1694
|
|
|
@@ -1622,15 +1710,11 @@ In this case, before executing the query, we will remove “what”, “is” an
|
|
|
1622
1710
|
This removal will remove false positive because of stop words, especially when combined with optional words.
|
|
1623
1711
|
For most use cases, it is better to not use this feature as people search by keywords on search engines.
|
|
1624
1712
|
|
|
1625
|
-
|
|
1626
|
-
|
|
1627
|
-
|
|
1628
1713
|
#### disablePrefixOnAttributes
|
|
1629
1714
|
|
|
1630
|
-
- scope: `
|
|
1715
|
+
- scope: `seetings`
|
|
1631
1716
|
- type: `array of strings`
|
|
1632
|
-
- default:
|
|
1633
|
-
|
|
1717
|
+
- default: []
|
|
1634
1718
|
|
|
1635
1719
|
List of attributes on which you want to disable prefix matching
|
|
1636
1720
|
(must be a subset of the `searchableAttributes` index setting).
|
|
@@ -1638,23 +1722,20 @@ List of attributes on which you want to disable prefix matching
|
|
|
1638
1722
|
This setting is useful on attributes that contain string that should not be matched as a prefix
|
|
1639
1723
|
(for example a product SKU).
|
|
1640
1724
|
|
|
1641
|
-
|
|
1642
1725
|
#### disableExactOnAttributes
|
|
1643
1726
|
|
|
1644
|
-
- scope: `settings
|
|
1645
|
-
- type: `
|
|
1646
|
-
- default:
|
|
1647
|
-
|
|
1727
|
+
- scope: `settings`
|
|
1728
|
+
- type: `search`
|
|
1729
|
+
- default: []
|
|
1648
1730
|
|
|
1649
1731
|
List of attributes on which you want to disable the computation of `exact` criteria
|
|
1650
1732
|
(must be a subset of the `searchableAttributes` index setting).
|
|
1651
1733
|
|
|
1652
1734
|
#### exactOnSingleWordQuery
|
|
1653
1735
|
|
|
1654
|
-
- scope: `settings
|
|
1736
|
+
- scope: `settings` `search`
|
|
1655
1737
|
- type: `string`
|
|
1656
|
-
- default:
|
|
1657
|
-
|
|
1738
|
+
- default: attribute
|
|
1658
1739
|
|
|
1659
1740
|
This parameter control how the `exact` ranking criterion is computed when the query contains one word. There are three different values:
|
|
1660
1741
|
|
|
@@ -1664,10 +1745,9 @@ This parameter control how the `exact` ranking criterion is computed when the qu
|
|
|
1664
1745
|
|
|
1665
1746
|
#### alternativesAsExact
|
|
1666
1747
|
|
|
1667
|
-
- scope: `
|
|
1668
|
-
- type: `string`
|
|
1669
|
-
- default:
|
|
1670
|
-
|
|
1748
|
+
- scope: `setting` `search`
|
|
1749
|
+
- type: `array of string`
|
|
1750
|
+
- default: ['ignorePlurals', 'singleWordSynonym']
|
|
1671
1751
|
|
|
1672
1752
|
Specify the list of approximation that should be considered as an exact match in the ranking formula:
|
|
1673
1753
|
|
|
@@ -1675,14 +1755,42 @@ Specify the list of approximation that should be considered as an exact match in
|
|
|
1675
1755
|
* `singleWordSynonym`: single-word synonym (For example "NY" = "NYC")
|
|
1676
1756
|
* `multiWordsSynonym`: multiple-words synonym (For example "NY" = "New York")
|
|
1677
1757
|
|
|
1678
|
-
|
|
1758
|
+
## performance
|
|
1759
|
+
|
|
1760
|
+
#### numericAttributesForFiltering
|
|
1761
|
+
|
|
1762
|
+
- scope: `settings`
|
|
1763
|
+
- type: `array of strings`
|
|
1764
|
+
- default: []
|
|
1765
|
+
- formerly known as: `numericAttributesToIndex`
|
|
1766
|
+
|
|
1767
|
+
All numerical attributes are automatically indexed as numerical filters
|
|
1768
|
+
(allowing filtering operations like `<` and `<=`).
|
|
1769
|
+
If you don't need filtering on some of your numerical attributes,
|
|
1770
|
+
you can specify this list to speed up the indexing.
|
|
1771
|
+
|
|
1772
|
+
If you only need to filter on a numeric value with the operator `=` or `!=`,
|
|
1773
|
+
you can speed up the indexing by specifying the attribute with `equalOnly(AttributeName)`.
|
|
1774
|
+
The other operators will be disabled.
|
|
1775
|
+
|
|
1776
|
+
#### allowCompressionOfIntegerArray
|
|
1777
|
+
|
|
1778
|
+
- scope: `settings`
|
|
1779
|
+
- type: `boolean`
|
|
1780
|
+
- default: false
|
|
1781
|
+
|
|
1782
|
+
Allows compression of big integer arrays.
|
|
1783
|
+
|
|
1784
|
+
In data-intensive use-cases,
|
|
1785
|
+
we recommended enabling this feature and then storing the list of user IDs or rights as an integer array.
|
|
1786
|
+
When enabled, the integer array is reordered to reach a better compression ratio.
|
|
1787
|
+
|
|
1788
|
+
## Advanced
|
|
1679
1789
|
|
|
1680
1790
|
#### attributeForDistinct
|
|
1681
1791
|
|
|
1682
1792
|
- scope: `settings`
|
|
1683
1793
|
- type: `string`
|
|
1684
|
-
- default: `null`
|
|
1685
|
-
|
|
1686
1794
|
|
|
1687
1795
|
The name of the attribute used for the `Distinct` feature.
|
|
1688
1796
|
|
|
@@ -1696,14 +1804,120 @@ then only the first one is kept and the others are removed from the results.
|
|
|
1696
1804
|
To get a full understanding of how `Distinct` works,
|
|
1697
1805
|
you can have a look at our [guide on distinct](https://www.algolia.com/doc/search/distinct).
|
|
1698
1806
|
|
|
1699
|
-
####
|
|
1807
|
+
#### placeholders
|
|
1808
|
+
|
|
1809
|
+
- scope: `settings`
|
|
1810
|
+
- type: `hash of array of words`
|
|
1811
|
+
- default: ""
|
|
1812
|
+
|
|
1813
|
+
This is an advanced use-case to define a token substitutable by a list of words
|
|
1814
|
+
without having the original token searchable.
|
|
1815
|
+
|
|
1816
|
+
It is defined by a hash associating placeholders to lists of substitutable words.
|
|
1817
|
+
|
|
1818
|
+
For example, `"placeholders": { "<streetnumber>": ["1", "2", "3", ..., "9999"]}`
|
|
1819
|
+
would allow it to be able to match all street numbers. We use the `< >` tag syntax
|
|
1820
|
+
to define placeholders in an attribute.
|
|
1821
|
+
|
|
1822
|
+
For example:
|
|
1823
|
+
|
|
1824
|
+
* Push a record with the placeholder:
|
|
1825
|
+
`{ "name" : "Apple Store", "address" : "<streetnumber> Opera street, Paris" }`.
|
|
1826
|
+
* Configure the placeholder in your index settings:
|
|
1827
|
+
`"placeholders": { "<streetnumber>" : ["1", "2", "3", "4", "5", ... ], ... }`.
|
|
1828
|
+
|
|
1829
|
+
#### altCorrections
|
|
1830
|
+
|
|
1831
|
+
- scope: `settings`
|
|
1832
|
+
- type: `array of objects`
|
|
1833
|
+
- default: []
|
|
1834
|
+
|
|
1835
|
+
Specify alternative corrections that you want to consider.
|
|
1836
|
+
|
|
1837
|
+
Each alternative correction is described by an object containing three attributes:
|
|
1838
|
+
|
|
1839
|
+
* `word` (string): The word to correct.
|
|
1840
|
+
* `correction` (string): The corrected word.
|
|
1841
|
+
* `nbTypos` (integer): The number of typos (1 or 2) that will be considered for the ranking algorithm (1 typo is better than 2 typos).
|
|
1842
|
+
|
|
1843
|
+
For example:
|
|
1844
|
+
|
|
1845
|
+
```
|
|
1846
|
+
"altCorrections": [
|
|
1847
|
+
{ "word" : "foot", "correction": "feet", "nbTypos": 1 },
|
|
1848
|
+
{ "word": "feet", "correction": "foot", "nbTypos": 1 }
|
|
1849
|
+
]
|
|
1850
|
+
```
|
|
1700
1851
|
|
|
1701
|
-
|
|
1852
|
+
#### minProximity
|
|
1853
|
+
|
|
1854
|
+
- scope: `settings` `search`
|
|
1702
1855
|
- type: `integer`
|
|
1703
|
-
- default:
|
|
1856
|
+
- default: 1
|
|
1857
|
+
|
|
1858
|
+
Configure the precision of the `proximity` ranking criterion.
|
|
1859
|
+
By default, the minimum (and best) proximity value distance between 2 matching words is 1.
|
|
1860
|
+
|
|
1861
|
+
Setting it to 2 (or 3) would allow 1 (or 2) words to be found between the matching words without degrading the proximity ranking value.
|
|
1704
1862
|
|
|
1863
|
+
Considering the query *“javascript framework”*, if you set `minProximity=2`, the records *“JavaScript framework”* and *“JavaScript charting framework”*
|
|
1864
|
+
will get the same proximity score, even if the second contains a word between the two matching words.
|
|
1705
1865
|
|
|
1706
|
-
|
|
1866
|
+
**Note:** the maximum `minProximity` that can be set is 7. Any higher value will disable the `proximity` criterion from the ranking formula.
|
|
1867
|
+
|
|
1868
|
+
#### responseFields
|
|
1869
|
+
|
|
1870
|
+
- scope: `settings` `search`
|
|
1871
|
+
- type: `array of strings`
|
|
1872
|
+
- default: * (all fields)
|
|
1873
|
+
|
|
1874
|
+
Choose which fields the response will contain. Applies to search and browse queries.
|
|
1875
|
+
|
|
1876
|
+
By default, all fields are returned. If this parameter is specified, only the fields explicitly
|
|
1877
|
+
listed will be returned, unless `*` is used, in which case all fields are returned.
|
|
1878
|
+
Specifying an empty list or unknown field names is an error.
|
|
1879
|
+
|
|
1880
|
+
This parameter is mainly intended to limit the response size.
|
|
1881
|
+
For example, for complex queries, echoing of request parameters in the response's `params` field can be undesirable.
|
|
1882
|
+
|
|
1883
|
+
Here is the list of field that can be filtered:
|
|
1884
|
+
|
|
1885
|
+
- `aroundLatLng`
|
|
1886
|
+
- `automaticRadius`
|
|
1887
|
+
- `exhaustiveFacetsCount`
|
|
1888
|
+
- `facets`
|
|
1889
|
+
- `facets_stats`
|
|
1890
|
+
- `hits`
|
|
1891
|
+
- `hitsPerPage`
|
|
1892
|
+
- `index`
|
|
1893
|
+
- `length`
|
|
1894
|
+
- `nbHits`
|
|
1895
|
+
- `nbPages`
|
|
1896
|
+
- `offset`
|
|
1897
|
+
- `page`
|
|
1898
|
+
- `params`
|
|
1899
|
+
- `processingTimeMS`
|
|
1900
|
+
- `query`
|
|
1901
|
+
- `queryAfterRemoval`
|
|
1902
|
+
|
|
1903
|
+
Here is the list of fields cannot be filtered out:
|
|
1904
|
+
|
|
1905
|
+
- `message`
|
|
1906
|
+
- `warning`
|
|
1907
|
+
- `cursor`
|
|
1908
|
+
- `serverUsed`
|
|
1909
|
+
- `timeoutCounts`
|
|
1910
|
+
- `timeoutHits`
|
|
1911
|
+
- `parsedQuery`
|
|
1912
|
+
- fields triggered explicitly via [getRankingInfo](#getrankinginfo)
|
|
1913
|
+
|
|
1914
|
+
#### distinct
|
|
1915
|
+
|
|
1916
|
+
- scope: `settings` `search`
|
|
1917
|
+
- type: `boolean`
|
|
1918
|
+
- default: 0
|
|
1919
|
+
|
|
1920
|
+
If set to 1 it
|
|
1707
1921
|
enables the distinct feature, disabled by default, if the `attributeForDistinct` index setting is set.
|
|
1708
1922
|
|
|
1709
1923
|
This feature is similar to the SQL "distinct" keyword.
|
|
@@ -1716,134 +1930,71 @@ then only the best one is kept and the others are removed.
|
|
|
1716
1930
|
To get a full understanding of how `Distinct` works,
|
|
1717
1931
|
you can have a look at our [guide on distinct](https://www.algolia.com/doc/search/distinct).
|
|
1718
1932
|
|
|
1719
|
-
|
|
1720
1933
|
#### getRankingInfo
|
|
1721
1934
|
|
|
1722
1935
|
- scope: `search`
|
|
1723
1936
|
- type: `boolean`
|
|
1724
|
-
- default:
|
|
1725
|
-
|
|
1937
|
+
- default: false
|
|
1726
1938
|
|
|
1727
1939
|
If set to true,
|
|
1728
1940
|
the result hits will contain ranking information in the **_rankingInfo** attribute.
|
|
1729
1941
|
|
|
1730
|
-
####
|
|
1731
|
-
|
|
1732
|
-
- scope: `settings`
|
|
1733
|
-
- type: `array of strings`
|
|
1734
|
-
- default: ``
|
|
1735
|
-
- formerly known as: `numericAttributesToIndex`
|
|
1736
|
-
|
|
1737
|
-
|
|
1738
|
-
All numerical attributes are automatically indexed as numerical filters
|
|
1739
|
-
(allowing filtering operations like `<` and `<=`).
|
|
1740
|
-
If you don't need filtering on some of your numerical attributes,
|
|
1741
|
-
you can specify this list to speed up the indexing.
|
|
1742
|
-
|
|
1743
|
-
If you only need to filter on a numeric value with the `=` operator,
|
|
1744
|
-
you can speed up the indexing by specifying the attribute with `equalOnly(AttributeName)`.
|
|
1745
|
-
The other operators will be disabled.
|
|
1746
|
-
|
|
1747
|
-
#### allowCompressionOfIntegerArray
|
|
1748
|
-
|
|
1749
|
-
- scope: `settings`
|
|
1750
|
-
- type: `boolean`
|
|
1751
|
-
- default: `false`
|
|
1752
|
-
|
|
1753
|
-
|
|
1754
|
-
Allows compression of big integer arrays.
|
|
1755
|
-
|
|
1756
|
-
In data-intensive use-cases,
|
|
1757
|
-
we recommended enabling this feature and then storing the list of user IDs or rights as an integer array.
|
|
1758
|
-
When enabled, the integer array is reordered to reach a better compression ratio.
|
|
1759
|
-
|
|
1760
|
-
#### numericFilters (deprecated)
|
|
1942
|
+
#### numericFilters
|
|
1761
1943
|
|
|
1762
1944
|
- scope: `search`
|
|
1763
1945
|
- type: `array of strings`
|
|
1764
|
-
- default:
|
|
1946
|
+
- default: []
|
|
1765
1947
|
|
|
1948
|
+
*If you are not using this parameter to generate filters programatically you should use [filters](#filters) instead*
|
|
1766
1949
|
|
|
1767
|
-
|
|
1768
|
-
|
|
1769
|
-
A string that contains the comma separated list of numeric filters you want to apply.
|
|
1950
|
+
List of numeric filters you want to apply.
|
|
1770
1951
|
The filter syntax is `attributeName` followed by `operand` followed by `value`.
|
|
1771
1952
|
Supported operands are `<`, `<=`, `=`, `>` and `>=`.
|
|
1772
1953
|
|
|
1773
1954
|
You can easily perform range queries via the `:` operator.
|
|
1774
1955
|
This is equivalent to combining a `>=` and `<=` operand.
|
|
1775
|
-
|
|
1776
1956
|
For example, `numericFilters=price:10 to 1000`.
|
|
1777
1957
|
|
|
1778
1958
|
You can also mix OR and AND operators.
|
|
1779
1959
|
The OR operator is defined with a parenthesis syntax.
|
|
1780
|
-
|
|
1781
|
-
|
|
1782
|
-
translates to `encodeURIComponent("code=1,(price:0 to 100,price:1000 to 2000)")`.
|
|
1783
|
-
|
|
1784
|
-
You can also use a string array encoding (for example `numericFilters: ["price>100","price<1000"]`).
|
|
1960
|
+
For example, `code=1 AND (price:[0-100] OR price:[1000-2000])`
|
|
1961
|
+
translates to `code=1,(price:0 to 100,price:1000 to 2000)`.
|
|
1785
1962
|
|
|
1786
1963
|
#### tagFilters (deprecated)
|
|
1787
1964
|
|
|
1788
1965
|
- scope: `search`
|
|
1789
|
-
- type: `string`
|
|
1790
|
-
- default:
|
|
1966
|
+
- type: `array of string`
|
|
1967
|
+
- default: ""
|
|
1791
1968
|
|
|
1792
|
-
|
|
1793
|
-
*This parameter is deprecated. Please use [filters](#filters) instead.*
|
|
1969
|
+
**This parameter is deprecated. You should use [filters](#filters) instead.**
|
|
1794
1970
|
|
|
1795
1971
|
Filter the query by a set of tags.
|
|
1796
1972
|
|
|
1797
1973
|
You can AND tags by separating them with commas.
|
|
1798
1974
|
To OR tags, you must add parentheses.
|
|
1799
1975
|
|
|
1800
|
-
For example
|
|
1801
|
-
|
|
1802
|
-
You can also use a string array encoding.
|
|
1803
|
-
|
|
1804
|
-
For example, `tagFilters: ["tag1",["tag2","tag3"]]` means *tag1 AND (tag2 OR tag3)*.
|
|
1976
|
+
For example: `["tag1",["tag2","tag3"]]` means `tag1 AND (tag2 OR tag3)`.
|
|
1805
1977
|
|
|
1806
1978
|
Negations are supported via the `-` operator, prefixing the value.
|
|
1807
1979
|
|
|
1808
|
-
For example: `
|
|
1980
|
+
For example: `["tag1", "-tag2"]`.
|
|
1809
1981
|
|
|
1810
1982
|
At indexing, tags should be added in the **_tags** attribute of objects.
|
|
1811
1983
|
|
|
1812
1984
|
For example `{"_tags":["tag1","tag2"]}`.
|
|
1813
1985
|
|
|
1814
|
-
#### facetFilters (deprecated)
|
|
1815
|
-
|
|
1816
|
-
- scope: `search`
|
|
1817
|
-
- type: `string`
|
|
1818
|
-
- default: `""`
|
|
1819
|
-
|
|
1820
|
-
|
|
1821
|
-
*This parameter is deprecated. Please use [filters](#filters) instead.*
|
|
1822
|
-
|
|
1823
|
-
Filter the query with a list of facets. Facets are separated by commas and is encoded as `attributeName:value`.
|
|
1824
|
-
To OR facets, you must add parentheses.
|
|
1825
|
-
|
|
1826
|
-
For example: `facetFilters=(category:Book,category:Movie),author:John%20Doe`.
|
|
1827
|
-
|
|
1828
|
-
You can also use a string array encoding.
|
|
1829
|
-
|
|
1830
|
-
For example, `[["category:Book","category:Movie"],"author:John%20Doe"]`.
|
|
1831
|
-
|
|
1832
1986
|
#### analytics
|
|
1833
1987
|
|
|
1834
1988
|
- scope: `search`
|
|
1835
1989
|
- type: `boolean`
|
|
1836
|
-
- default:
|
|
1990
|
+
- default: true
|
|
1837
1991
|
|
|
1838
|
-
|
|
1839
|
-
If set to false, this query will not be taken into account in the analytics feature.
|
|
1992
|
+
If set to false, this query will not be taken into account in the analytics.
|
|
1840
1993
|
|
|
1841
1994
|
#### analyticsTags
|
|
1842
1995
|
|
|
1843
1996
|
- scope: `search`
|
|
1844
1997
|
- type: `array of strings`
|
|
1845
|
-
- default: `null`
|
|
1846
|
-
|
|
1847
1998
|
|
|
1848
1999
|
If set, tag your query with the specified identifiers. Tags can then be used in the Analytics to analyze a subset of searches only.
|
|
1849
2000
|
|
|
@@ -1851,111 +2002,30 @@ If set, tag your query with the specified identifiers. Tags can then be used in
|
|
|
1851
2002
|
|
|
1852
2003
|
- scope: `search`
|
|
1853
2004
|
- type: `boolean`
|
|
1854
|
-
- default:
|
|
1855
|
-
|
|
2005
|
+
- default: true
|
|
1856
2006
|
|
|
1857
2007
|
If set to `false`, the search will not use the synonyms defined for the targeted index.
|
|
1858
2008
|
|
|
1859
2009
|
#### replaceSynonymsInHighlight
|
|
1860
2010
|
|
|
1861
|
-
- scope: `
|
|
2011
|
+
- scope: `settings` `search`
|
|
1862
2012
|
- type: `boolean`
|
|
1863
|
-
- default:
|
|
1864
|
-
|
|
1865
|
-
|
|
1866
|
-
If set to `false`, words matched via synonym expansion will not be replaced by the matched synonym in the highlighted result.
|
|
1867
|
-
|
|
1868
|
-
#### placeholders
|
|
1869
|
-
|
|
1870
|
-
- scope: `settings`
|
|
1871
|
-
- type: `hash of array of words`
|
|
1872
|
-
- default: ``
|
|
1873
|
-
|
|
1874
|
-
|
|
1875
|
-
This is an advanced use-case to define a token substitutable by a list of words
|
|
1876
|
-
without having the original token searchable.
|
|
1877
|
-
|
|
1878
|
-
It is defined by a hash associating placeholders to lists of substitutable words.
|
|
1879
|
-
|
|
1880
|
-
For example, `"placeholders": { "<streetnumber>": ["1", "2", "3", ..., "9999"]}`
|
|
1881
|
-
would allow it to be able to match all street numbers. We use the `< >` tag syntax
|
|
1882
|
-
to define placeholders in an attribute.
|
|
1883
|
-
|
|
1884
|
-
For example:
|
|
1885
|
-
|
|
1886
|
-
* Push a record with the placeholder:
|
|
1887
|
-
`{ "name" : "Apple Store", "address" : "<streetnumber> Opera street, Paris" }`.
|
|
1888
|
-
* Configure the placeholder in your index settings:
|
|
1889
|
-
`"placeholders": { "<streetnumber>" : ["1", "2", "3", "4", "5", ... ], ... }`.
|
|
1890
|
-
|
|
1891
|
-
#### altCorrections
|
|
2013
|
+
- default: true
|
|
1892
2014
|
|
|
1893
|
-
|
|
1894
|
-
- type: `array of objects`
|
|
1895
|
-
- default: `[]`
|
|
1896
|
-
|
|
1897
|
-
|
|
1898
|
-
Specify alternative corrections that you want to consider.
|
|
1899
|
-
|
|
1900
|
-
Each alternative correction is described by an object containing three attributes:
|
|
1901
|
-
|
|
1902
|
-
* `word` (string): The word to correct.
|
|
1903
|
-
* `correction` (string): The corrected word.
|
|
1904
|
-
* `nbTypos` (integer): The number of typos (1 or 2) that will be considered for the ranking algorithm (1 typo is better than 2 typos).
|
|
1905
|
-
|
|
1906
|
-
For example:
|
|
1907
|
-
|
|
1908
|
-
```
|
|
1909
|
-
"altCorrections": [
|
|
1910
|
-
{ "word" : "foot", "correction": "feet", "nbTypos": 1 },
|
|
1911
|
-
{ "word": "feet", "correction": "foot", "nbTypos": 1 }
|
|
1912
|
-
]
|
|
1913
|
-
```
|
|
1914
|
-
|
|
1915
|
-
#### minProximity
|
|
1916
|
-
|
|
1917
|
-
- scope: `search`, `settings`
|
|
1918
|
-
- type: `integer`
|
|
1919
|
-
- default: `1`
|
|
1920
|
-
|
|
1921
|
-
|
|
1922
|
-
Configure the precision of the `proximity` ranking criterion. By default, the minimum (and best) proximity value distance between 2 matching words is 1. Setting it to 2 (or 3) would allow 1 (or 2) words to be found between the matching words without degrading the proximity ranking value.
|
|
1923
|
-
|
|
1924
|
-
Considering the query *“javascript framework”*, if you set `minProximity=2`, the records *“JavaScript framework”* and *“JavaScript charting framework”* will get the same proximity score, even if the second contains a word between the two matching words.
|
|
2015
|
+
If set to `false`, words matched via synonyms expansion will not be replaced by the matched synonym in the highlighted result.
|
|
1925
2016
|
|
|
1926
|
-
**Note:** the maximum `minProximity` that can be set is 7. Any higher value will disable the `proximity` criterion from the ranking formula.
|
|
1927
2017
|
|
|
1928
|
-
|
|
2018
|
+
# Manage Indices
|
|
1929
2019
|
|
|
1930
|
-
- scope: `search`, `settings`
|
|
1931
|
-
- type: `array of strings`
|
|
1932
|
-
- default: `*`
|
|
1933
2020
|
|
|
1934
2021
|
|
|
1935
|
-
|
|
1936
|
-
|
|
1937
|
-
By default, all fields are returned. If this parameter is specified, only the fields explicitly listed will be returned, unless `*` is used, in which case all fields are returned. Specifying an empty list or unknown field names is an error.
|
|
1938
|
-
|
|
1939
|
-
This parameter is mainly intended to limit the response size. For example, for complex queries, echoing of request parameters in the response's `params` field can be undesirable.
|
|
1940
|
-
|
|
1941
|
-
Some fields cannot be filtered out:
|
|
1942
|
-
|
|
1943
|
-
- warning `message`
|
|
1944
|
-
- `cursor` in browse queries
|
|
1945
|
-
- fields triggered explicitly via [getRankingInfo](#getrankinginfo)
|
|
1946
|
-
|
|
1947
|
-
|
|
1948
|
-
## Manage Indices
|
|
1949
|
-
|
|
1950
|
-
|
|
1951
|
-
|
|
1952
|
-
### Create an index
|
|
2022
|
+
## Create an index
|
|
1953
2023
|
|
|
1954
2024
|
To create an index, you need to perform any indexing operation like:
|
|
1955
2025
|
- set settings
|
|
1956
2026
|
- add object
|
|
1957
2027
|
|
|
1958
|
-
|
|
2028
|
+
## List indices - `list_indexes`
|
|
1959
2029
|
|
|
1960
2030
|
You can list all your indices along with their associated information (number of entries, disk size, etc.) with the `list_indexes` method:
|
|
1961
2031
|
|
|
@@ -1963,10 +2033,7 @@ You can list all your indices along with their associated information (number of
|
|
|
1963
2033
|
Algolia.list_indexes
|
|
1964
2034
|
```
|
|
1965
2035
|
|
|
1966
|
-
|
|
1967
|
-
|
|
1968
|
-
|
|
1969
|
-
### Delete index - `delete_index`
|
|
2036
|
+
## Delete index - `delete_index`
|
|
1970
2037
|
|
|
1971
2038
|
You can delete an index using its name:
|
|
1972
2039
|
|
|
@@ -1975,8 +2042,7 @@ index = Algolia::Index.new("contacts")
|
|
|
1975
2042
|
index.delete_index
|
|
1976
2043
|
```
|
|
1977
2044
|
|
|
1978
|
-
|
|
1979
|
-
### Clear index - `clear_index`
|
|
2045
|
+
## Clear index - `clear_index`
|
|
1980
2046
|
|
|
1981
2047
|
You can delete the index contents without removing settings and index specific API keys by using the `clearIndex` command:
|
|
1982
2048
|
|
|
@@ -1984,8 +2050,7 @@ You can delete the index contents without removing settings and index specific A
|
|
|
1984
2050
|
index.clear_index
|
|
1985
2051
|
```
|
|
1986
2052
|
|
|
1987
|
-
|
|
1988
|
-
### Copy index - `copy_index`
|
|
2053
|
+
## Copy index - `copy_index`
|
|
1989
2054
|
|
|
1990
2055
|
You can copy an existing index using the `copy` command.
|
|
1991
2056
|
|
|
@@ -1996,8 +2061,7 @@ You can copy an existing index using the `copy` command.
|
|
|
1996
2061
|
puts Algolia.copy_index("MyIndex", "MyIndexCopy")
|
|
1997
2062
|
```
|
|
1998
2063
|
|
|
1999
|
-
|
|
2000
|
-
### Move index - `move_index`
|
|
2064
|
+
## Move index - `move_index`
|
|
2001
2065
|
|
|
2002
2066
|
In some cases, you may want to totally reindex all your data. In order to keep your existing service
|
|
2003
2067
|
running while re-importing your data we recommend the usage of a temporary index plus an atomical
|
|
@@ -2019,26 +2083,24 @@ There is one exception for the [replicas](#replicas) parameter which is not impa
|
|
|
2019
2083
|
|
|
2020
2084
|
For example, if you want to fully update your index `MyIndex` every night, we recommend the following process:
|
|
2021
2085
|
|
|
2022
|
-
1. Get settings and synonyms from the old index using [Get settings](#get-settings
|
|
2023
|
-
and [Get synonym](#get-synonym
|
|
2086
|
+
1. Get settings and synonyms from the old index using [Get settings](#get-settings)
|
|
2087
|
+
and [Get synonym](#get-synonym).
|
|
2024
2088
|
1. Apply settings and synonyms to the temporary index `MyTmpIndex`, (this will create the `MyTmpIndex` index)
|
|
2025
|
-
using [Set settings](#set-settings
|
|
2089
|
+
using [Set settings](#set-settings) and [Batch synonyms](#batch-synonyms)
|
|
2026
2090
|
(make sure to remove the [replicas](#replicas) parameter from the settings if it exists).
|
|
2027
|
-
1. Import your records into a new index using [Add
|
|
2091
|
+
1. Import your records into a new index using [Add Objects](#add-objects).
|
|
2028
2092
|
1. Atomically replace the index `MyIndex` with the content and settings of the index `MyTmpIndex`
|
|
2029
|
-
using the [Move index](#move-index
|
|
2093
|
+
using the [Move index](#move-index) method.
|
|
2030
2094
|
This will automatically override the old index without any downtime on the search.
|
|
2031
2095
|
1. You'll end up with only one index called `MyIndex`, that contains the records and settings pushed to `MyTmpIndex`
|
|
2032
2096
|
and the replica-indices that were initially attached to `MyIndex` will be in sync with the new data.
|
|
2033
2097
|
|
|
2034
2098
|
|
|
2099
|
+
# Api keys
|
|
2035
2100
|
|
|
2036
2101
|
|
|
2037
2102
|
|
|
2038
|
-
|
|
2039
|
-
## Api Keys
|
|
2040
|
-
|
|
2041
|
-
### Overview
|
|
2103
|
+
## Overview
|
|
2042
2104
|
|
|
2043
2105
|
When creating your Algolia Account, you'll notice there are 3 different API Keys:
|
|
2044
2106
|
|
|
@@ -2051,18 +2113,18 @@ allow the person who has it to query/change/delete data*
|
|
|
2051
2113
|
|
|
2052
2114
|
- **Monitoring API Key** - It allows you to access the [Monitoring API](https://www.algolia.com/doc/rest-api/monitoring)
|
|
2053
2115
|
|
|
2054
|
-
|
|
2116
|
+
### Other types of API keys
|
|
2055
2117
|
|
|
2056
2118
|
The *Admin API Key* and *Search-Only API Key* both have really large scope and sometimes you want to give a key to
|
|
2057
2119
|
someone that have restricted permissions, can it be an index, a rate limit, a validity limit, ...
|
|
2058
2120
|
|
|
2059
|
-
To address those use-cases we have two
|
|
2121
|
+
To address those use-cases we have two different type of keys:
|
|
2060
2122
|
|
|
2061
2123
|
- **Secured API Keys**
|
|
2062
2124
|
|
|
2063
2125
|
When you need to restrict the scope of the *Search Key*, we recommend to use *Secured API Key*.
|
|
2064
2126
|
You can generate them on the fly (without any call to the API)
|
|
2065
|
-
from the *Search Only API Key* or any search *User Key* using the [Generate key](#generate-key
|
|
2127
|
+
from the *Search Only API Key* or any search *User Key* using the [Generate key](#generate-key) method
|
|
2066
2128
|
|
|
2067
2129
|
- **User API Keys**
|
|
2068
2130
|
|
|
@@ -2070,19 +2132,20 @@ If *Secured API Keys* does not meet your requirements, you can make use of *User
|
|
|
2070
2132
|
Managing and especially creating those keys requires a call to the API.
|
|
2071
2133
|
|
|
2072
2134
|
We have several methods to manage them:
|
|
2073
|
-
- [Add user key](#add-user-key---add_user_key)
|
|
2074
|
-
- [Update user key](#update-user-key---update_user_key)
|
|
2075
|
-
- [Delete user key](#delete-user-key---delete_user_key)
|
|
2076
|
-
- [List api keys](#list-api-keys---list_api_keys)
|
|
2077
|
-
- [Get key permissions](#get-key-permissions---get_user_key_acl)
|
|
2078
2135
|
|
|
2079
|
-
|
|
2136
|
+
- [Add user key](#add-user-key)
|
|
2137
|
+
- [Update user key](#update-user-key)
|
|
2138
|
+
- [Delete user key](#delete-user-key)
|
|
2139
|
+
- [List api keys](#list-api-keys)
|
|
2140
|
+
- [Get key permissions](#get-key-permissions)
|
|
2141
|
+
|
|
2142
|
+
## Generate key - `generate_secured_api_key`
|
|
2080
2143
|
|
|
2081
2144
|
When you need to restrict the scope of the *Search Key*, we recommend to use *Secured API Key*.
|
|
2082
2145
|
You can generate a *Secured API Key* from the *Search Only API Key* or any search *User API Key*
|
|
2083
2146
|
|
|
2084
2147
|
There is a few things to know about *Secured API Keys*
|
|
2085
|
-
- They always need to be generated **on your backend** using one of our API Client
|
|
2148
|
+
- They always need to be generated **on your backend** using one of our API Client
|
|
2086
2149
|
- You can generate them on the fly (without any call to the API)
|
|
2087
2150
|
- They will not appear on the dashboard as they are generated without any call to the API
|
|
2088
2151
|
- The key you use to generate it **needs to become private** and you should not use it in your frontend.
|
|
@@ -2091,7 +2154,7 @@ There is a few things to know about *Secured API Keys*
|
|
|
2091
2154
|
You can then use the key in your frontend code
|
|
2092
2155
|
|
|
2093
2156
|
```js
|
|
2094
|
-
var client = algoliasearch('YourApplicationID', '
|
|
2157
|
+
var client = algoliasearch('YourApplicationID', 'YourPublicAPIKey');
|
|
2095
2158
|
|
|
2096
2159
|
var index = client.initIndex('indexName')
|
|
2097
2160
|
|
|
@@ -2129,8 +2192,9 @@ In that case, you can tag all records with their associated `user_id` in order t
|
|
|
2129
2192
|
generating the *Secured API Key* to retrieve only what a user is tagged in.
|
|
2130
2193
|
|
|
2131
2194
|
**Warning**
|
|
2132
|
-
|
|
2133
|
-
|
|
2195
|
+
|
|
2196
|
+
If you're generating *Secured API Keys* using the [JavaScript client](http://github.com/algolia/algoliasearch-client-javascript) in your frontend,
|
|
2197
|
+
it will result in a security breach since the user is able to modify the filters you've set
|
|
2134
2198
|
by modifying the code from the browser.
|
|
2135
2199
|
|
|
2136
2200
|
#### Valid Until
|
|
@@ -2156,7 +2220,7 @@ public_key = Algolia.generate_secured_api_key 'YourSearchOnlyApiKey', {'restrict
|
|
|
2156
2220
|
|
|
2157
2221
|
If you want to rate limit a secured API Key, the API key you generate the secured api key from need to be rate-limited.
|
|
2158
2222
|
You can do that either via the dashboard or via the API using the
|
|
2159
|
-
[Add user key](#add-user-key
|
|
2223
|
+
[Add user key](#add-user-key) or [Update user key](#update-user-key) method
|
|
2160
2224
|
|
|
2161
2225
|
##### User Rate Limiting
|
|
2162
2226
|
|
|
@@ -2186,12 +2250,11 @@ public_key = Algolia.generate_secured_api_key 'YourSearchOnlyApiKey', {'restrict
|
|
|
2186
2250
|
```
|
|
2187
2251
|
|
|
2188
2252
|
|
|
2253
|
+
# Synonyms
|
|
2189
2254
|
|
|
2190
2255
|
|
|
2191
2256
|
|
|
2192
|
-
##
|
|
2193
|
-
|
|
2194
|
-
### Save synonym - `save_synonym`
|
|
2257
|
+
## Save synonym - `save_synonym`
|
|
2195
2258
|
|
|
2196
2259
|
This method saves a single synonym record into the index.
|
|
2197
2260
|
|
|
@@ -2206,7 +2269,7 @@ index.save_synonym('a-unique-identifier', {
|
|
|
2206
2269
|
}, true)
|
|
2207
2270
|
```
|
|
2208
2271
|
|
|
2209
|
-
|
|
2272
|
+
## Batch synonyms - `batch_synonyms`
|
|
2210
2273
|
|
|
2211
2274
|
Use the batch method to create a large number of synonyms at once,
|
|
2212
2275
|
forward them to replica indices if desired,
|
|
@@ -2230,7 +2293,7 @@ index.batch_synonyms([{
|
|
|
2230
2293
|
}], true, true)
|
|
2231
2294
|
```
|
|
2232
2295
|
|
|
2233
|
-
|
|
2296
|
+
## Editing Synonyms
|
|
2234
2297
|
|
|
2235
2298
|
Updating the value of a specific synonym record is the same as creating one.
|
|
2236
2299
|
Make sure you specify the same objectID used to create the record and the synonyms
|
|
@@ -2241,7 +2304,7 @@ false is the default value).
|
|
|
2241
2304
|
Otherwise, the entire synonym list will be replaced only partially with the records
|
|
2242
2305
|
in the batch update.
|
|
2243
2306
|
|
|
2244
|
-
|
|
2307
|
+
## Delete synonym - `delete_synonym`
|
|
2245
2308
|
|
|
2246
2309
|
Use the normal index delete method to delete synonyms,
|
|
2247
2310
|
specifying the objectID of the synonym record you want to delete.
|
|
@@ -2252,7 +2315,7 @@ Forward the deletion to replica indices by setting the forwardToReplicas paramet
|
|
|
2252
2315
|
index.delete_synonym('a-unique-identifier', true)
|
|
2253
2316
|
```
|
|
2254
2317
|
|
|
2255
|
-
|
|
2318
|
+
## Clear all synonyms - `clear_synonyms`
|
|
2256
2319
|
|
|
2257
2320
|
This is a convenience method to delete all synonyms at once.
|
|
2258
2321
|
It should not be used on a production index to then push a new list of synonyms:
|
|
@@ -2267,7 +2330,7 @@ use the batch method with the replaceExistingSynonyms parameter set to true.
|
|
|
2267
2330
|
index.clear_synonyms(true)
|
|
2268
2331
|
```
|
|
2269
2332
|
|
|
2270
|
-
|
|
2333
|
+
## Get synonym - `get_synonym`
|
|
2271
2334
|
|
|
2272
2335
|
Search for synonym records by their objectID or by the text they contain.
|
|
2273
2336
|
Both methods are covered here.
|
|
@@ -2276,7 +2339,7 @@ Both methods are covered here.
|
|
|
2276
2339
|
synonym = index.get_synonym('a-unique-identifier')
|
|
2277
2340
|
```
|
|
2278
2341
|
|
|
2279
|
-
|
|
2342
|
+
## Search synonyms - `search_synonyms`
|
|
2280
2343
|
|
|
2281
2344
|
Search for synonym records similar to how you’d search normally.
|
|
2282
2345
|
|
|
@@ -2296,23 +2359,22 @@ results = index.search_synonyms('street', {
|
|
|
2296
2359
|
```
|
|
2297
2360
|
|
|
2298
2361
|
|
|
2362
|
+
# Advanced
|
|
2299
2363
|
|
|
2300
|
-
## Advanced
|
|
2301
|
-
|
|
2302
|
-
### Custom batch - `batch`
|
|
2303
2364
|
|
|
2304
|
-
You may want to perform multiple operations with one API call to reduce latency.
|
|
2305
2365
|
|
|
2366
|
+
## Custom batch - `batch`
|
|
2306
2367
|
|
|
2368
|
+
You may want to perform multiple operations with one API call to reduce latency.
|
|
2307
2369
|
|
|
2308
|
-
If you have one index per user, you may want to perform a batch operations across
|
|
2370
|
+
If you have one index per user, you may want to perform a batch operations across several indices.
|
|
2309
2371
|
We expose a method to perform this type of batch:
|
|
2310
2372
|
|
|
2311
2373
|
```ruby
|
|
2312
|
-
res =
|
|
2313
|
-
|
|
2374
|
+
res = client.batch([
|
|
2375
|
+
{"action"=> "addObject", "indexName"=> "index1", "body": {"firstname" => "Jimmie",
|
|
2314
2376
|
"lastname" => "Barninger"}},
|
|
2315
|
-
{"action"=> "addObject", "indexName"=> "index2", "body": {"firstname" => "Warren",
|
|
2377
|
+
{"action"=> "addObject", "indexName"=> "index2", "body": {"firstname" => "Warren",
|
|
2316
2378
|
"lastname" => "Speach"}}])
|
|
2317
2379
|
```
|
|
2318
2380
|
|
|
@@ -2324,7 +2386,7 @@ The attribute **action** can have these values:
|
|
|
2324
2386
|
- partialUpdateObjectNoCreate
|
|
2325
2387
|
- deleteObject
|
|
2326
2388
|
|
|
2327
|
-
|
|
2389
|
+
## Backup / Export an index - `browse`
|
|
2328
2390
|
|
|
2329
2391
|
The `search` method cannot return more than 1,000 results. If you need to
|
|
2330
2392
|
retrieve all the content of your index (for backup, SEO purposes or for running
|
|
@@ -2335,6 +2397,13 @@ This method is optimized for speed. To make it fast, distinct, typo-tolerance,
|
|
|
2335
2397
|
word proximity, geo distance and number of matched words are disabled. Results
|
|
2336
2398
|
are still returned ranked by attributes and custom ranking.
|
|
2337
2399
|
|
|
2400
|
+
Ruby has a nice browse method that hides the cursor, so no need to talk about it
|
|
2401
|
+
It will return a `cursor` alongside your data, that you can then use to retrieve
|
|
2402
|
+
the next chunk of your records.
|
|
2403
|
+
|
|
2404
|
+
You can specify custom parameters (like `page` or `hitsPerPage`) on your first
|
|
2405
|
+
`browse` call, and these parameters will then be included in the `cursor`. Note
|
|
2406
|
+
that it is not possible to access records beyond the 1,000th on the first call.
|
|
2338
2407
|
|
|
2339
2408
|
#### Response Format
|
|
2340
2409
|
|
|
@@ -2359,37 +2428,27 @@ are still returned ranked by attributes and custom ranking.
|
|
|
2359
2428
|
##### Fields
|
|
2360
2429
|
|
|
2361
2430
|
- `cursor` (string, optional): A cursor to retrieve the next chunk of data. If absent, it means that the end of the index has been reached.
|
|
2362
|
-
|
|
2363
2431
|
- `query` (string): Query text used to filter the results.
|
|
2364
|
-
|
|
2365
2432
|
- `params` (string, URL-encoded): Search parameters used to filter the results.
|
|
2366
|
-
|
|
2367
2433
|
- `processingTimeMS` (integer): Time that the server took to process the request, in milliseconds. *Note: This does not include network time.*
|
|
2368
2434
|
|
|
2369
2435
|
The following fields are provided for convenience purposes, and **only when the browse is not filtered**:
|
|
2370
2436
|
|
|
2371
2437
|
- `nbHits` (integer): Number of objects in the index.
|
|
2372
|
-
|
|
2373
2438
|
- `page` (integer): Index of the current page (zero-based).
|
|
2374
|
-
|
|
2375
2439
|
- `hitsPerPage` (integer): Maximum number of hits returned per page.
|
|
2376
|
-
|
|
2377
2440
|
- `nbPages` (integer): Number of pages corresponding to the number of hits. Basically, `ceil(nbHits / hitsPerPage)`.
|
|
2378
2441
|
|
|
2379
|
-
|
|
2380
2442
|
#### Example
|
|
2381
2443
|
|
|
2382
2444
|
```ruby
|
|
2383
2445
|
# Iterate with a filter over the index
|
|
2384
|
-
index.browse(
|
|
2446
|
+
index.browse() do |hit|
|
|
2385
2447
|
# Do something
|
|
2386
2448
|
end
|
|
2387
2449
|
```
|
|
2388
2450
|
|
|
2389
|
-
|
|
2390
|
-
|
|
2391
|
-
|
|
2392
|
-
### List api keys - `list_api_keys`
|
|
2451
|
+
## List api keys - `list_api_keys`
|
|
2393
2452
|
|
|
2394
2453
|
To list existing keys, you can use:
|
|
2395
2454
|
|
|
@@ -2412,7 +2471,7 @@ Each key is defined by a set of permissions that specify the authorized actions.
|
|
|
2412
2471
|
* **analytics**: Allowed to retrieve analytics through the analytics API.
|
|
2413
2472
|
* **listIndexes**: Allowed to list all accessible indexes.
|
|
2414
2473
|
|
|
2415
|
-
|
|
2474
|
+
## Add user key - `add_user_key`
|
|
2416
2475
|
|
|
2417
2476
|
To create API keys:
|
|
2418
2477
|
|
|
@@ -2427,123 +2486,37 @@ puts res['key']
|
|
|
2427
2486
|
|
|
2428
2487
|
You can also create an API Key with advanced settings:
|
|
2429
2488
|
|
|
2430
|
-
|
|
2431
|
-
|
|
2432
|
-
|
|
2433
|
-
|
|
2434
|
-
|
|
2435
|
-
|
|
2436
|
-
|
|
2437
|
-
|
|
2438
|
-
</div>
|
|
2439
|
-
</div>
|
|
2440
|
-
</td>
|
|
2441
|
-
<td class='client-readme-param-content'>
|
|
2442
|
-
<p>Add a validity period. The key will be valid for a specific period of time (in seconds).</p>
|
|
2443
|
-
|
|
2444
|
-
</td>
|
|
2445
|
-
</tr>
|
|
2446
|
-
|
|
2447
|
-
|
|
2448
|
-
<tr>
|
|
2449
|
-
<td valign='top'>
|
|
2450
|
-
<div class='client-readme-param-container'>
|
|
2451
|
-
<div class='client-readme-param-container-inner'>
|
|
2452
|
-
<div class='client-readme-param-name'><code>maxQueriesPerIPPerHour</code></div>
|
|
2453
|
-
|
|
2454
|
-
</div>
|
|
2455
|
-
</div>
|
|
2456
|
-
</td>
|
|
2457
|
-
<td class='client-readme-param-content'>
|
|
2458
|
-
<p>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.</p>
|
|
2459
|
-
|
|
2460
|
-
<p>Note: If you are sending the query through your servers, you must use the <code>Algolia.with_rate_limits("EndUserIP", "APIKeyWithRateLimit") do ... end</code> block to enable rate-limit.</p>
|
|
2461
|
-
|
|
2462
|
-
</td>
|
|
2463
|
-
</tr>
|
|
2464
|
-
|
|
2465
|
-
|
|
2466
|
-
<tr>
|
|
2467
|
-
<td valign='top'>
|
|
2468
|
-
<div class='client-readme-param-container'>
|
|
2469
|
-
<div class='client-readme-param-container-inner'>
|
|
2470
|
-
<div class='client-readme-param-name'><code>maxHitsPerQuery</code></div>
|
|
2471
|
-
|
|
2472
|
-
</div>
|
|
2473
|
-
</div>
|
|
2474
|
-
</td>
|
|
2475
|
-
<td class='client-readme-param-content'>
|
|
2476
|
-
<p>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.</p>
|
|
2477
|
-
|
|
2478
|
-
</td>
|
|
2479
|
-
</tr>
|
|
2480
|
-
|
|
2481
|
-
|
|
2482
|
-
<tr>
|
|
2483
|
-
<td valign='top'>
|
|
2484
|
-
<div class='client-readme-param-container'>
|
|
2485
|
-
<div class='client-readme-param-container-inner'>
|
|
2486
|
-
<div class='client-readme-param-name'><code>indexes</code></div>
|
|
2487
|
-
|
|
2488
|
-
</div>
|
|
2489
|
-
</div>
|
|
2490
|
-
</td>
|
|
2491
|
-
<td class='client-readme-param-content'>
|
|
2492
|
-
<p>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.</p>
|
|
2493
|
-
|
|
2494
|
-
</td>
|
|
2495
|
-
</tr>
|
|
2496
|
-
|
|
2497
|
-
|
|
2498
|
-
<tr>
|
|
2499
|
-
<td valign='top'>
|
|
2500
|
-
<div class='client-readme-param-container'>
|
|
2501
|
-
<div class='client-readme-param-container-inner'>
|
|
2502
|
-
<div class='client-readme-param-name'><code>referers</code></div>
|
|
2503
|
-
|
|
2504
|
-
</div>
|
|
2505
|
-
</div>
|
|
2506
|
-
</td>
|
|
2507
|
-
<td class='client-readme-param-content'>
|
|
2508
|
-
<p>Specify the list of referers. You can target all referers starting with a prefix, ending with a suffix using the '*' character. For example, "<a href="https://algolia.com/%5C*">https://algolia.com/\*</a>" matches all referers starting with "<a href="https://algolia.com/">https://algolia.com/</a>" and "*.algolia.com" matches all referers ending with ".algolia.com". If you want to allow the domain algolia.com you can use "*algolia.com/*". Defaults to all referers if empty or blank.</p>
|
|
2509
|
-
|
|
2510
|
-
</td>
|
|
2511
|
-
</tr>
|
|
2512
|
-
|
|
2513
|
-
|
|
2514
|
-
<tr>
|
|
2515
|
-
<td valign='top'>
|
|
2516
|
-
<div class='client-readme-param-container'>
|
|
2517
|
-
<div class='client-readme-param-container-inner'>
|
|
2518
|
-
<div class='client-readme-param-name'><code>queryParameters</code></div>
|
|
2519
|
-
|
|
2520
|
-
</div>
|
|
2521
|
-
</div>
|
|
2522
|
-
</td>
|
|
2523
|
-
<td class='client-readme-param-content'>
|
|
2524
|
-
<p>Specify the list of query parameters. You can force the query parameters for a query using the url string format (param1=X&param2=Y...).</p>
|
|
2525
|
-
|
|
2526
|
-
</td>
|
|
2527
|
-
</tr>
|
|
2528
|
-
|
|
2489
|
+
##### validity
|
|
2490
|
+
|
|
2491
|
+
Add a validity period. The key will be valid for a specific period of time (in seconds).
|
|
2492
|
+
|
|
2493
|
+
##### maxQueriesPerIPPerHour
|
|
2494
|
+
|
|
2495
|
+
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.
|
|
2496
|
+
|
|
2529
2497
|
|
|
2530
|
-
|
|
2531
|
-
|
|
2532
|
-
|
|
2533
|
-
|
|
2534
|
-
|
|
2535
|
-
|
|
2536
|
-
|
|
2537
|
-
|
|
2538
|
-
|
|
2539
|
-
|
|
2540
|
-
|
|
2541
|
-
|
|
2542
|
-
|
|
2543
|
-
|
|
2544
|
-
|
|
2545
|
-
|
|
2546
|
-
|
|
2498
|
+
|
|
2499
|
+
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.
|
|
2500
|
+
|
|
2501
|
+
##### maxHitsPerQuery
|
|
2502
|
+
|
|
2503
|
+
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.
|
|
2504
|
+
|
|
2505
|
+
##### indexes
|
|
2506
|
+
|
|
2507
|
+
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.
|
|
2508
|
+
|
|
2509
|
+
##### referers
|
|
2510
|
+
|
|
2511
|
+
Specify the list of referers. You can target all referers starting with a prefix, ending with a suffix using the '\*' character. For example, "https://algolia.com/\*" matches all referers starting with "https://algolia.com/" and "\*.algolia.com" matches all referers ending with ".algolia.com". If you want to allow the domain algolia.com you can use "\*algolia.com/\*". Defaults to all referers if empty or blank.
|
|
2512
|
+
|
|
2513
|
+
##### queryParameters
|
|
2514
|
+
|
|
2515
|
+
Specify the list of query parameters. You can force the query parameters for a query using the url string format (param1=X¶m2=Y...).
|
|
2516
|
+
|
|
2517
|
+
##### description
|
|
2518
|
+
|
|
2519
|
+
Specify a description to describe where the key is used.
|
|
2547
2520
|
|
|
2548
2521
|
```ruby
|
|
2549
2522
|
# Creates a new global API key that is valid for 300 seconds
|
|
@@ -2556,20 +2529,20 @@ puts res['key']
|
|
|
2556
2529
|
# - valid on 'my_index1' and 'my_index2'
|
|
2557
2530
|
|
|
2558
2531
|
params = {
|
|
2559
|
-
|
|
2560
|
-
|
|
2561
|
-
|
|
2562
|
-
|
|
2563
|
-
|
|
2564
|
-
|
|
2565
|
-
|
|
2532
|
+
:validity => 300,
|
|
2533
|
+
:maxQueriesPerIPPerHour => 100,
|
|
2534
|
+
:maxHitsPerQuery => 20,
|
|
2535
|
+
:indexes => ['my_index1', 'my_index2'],
|
|
2536
|
+
:referers => ['algolia.com/*'],
|
|
2537
|
+
:queryParameters => 'typoTolerance=strict&ignorePlurals=false',
|
|
2538
|
+
:description => 'Limited search only API key for algolia.com'
|
|
2566
2539
|
}
|
|
2567
2540
|
|
|
2568
2541
|
res = Algolia.add_user_key(params)
|
|
2569
2542
|
puts res['key']
|
|
2570
2543
|
```
|
|
2571
2544
|
|
|
2572
|
-
|
|
2545
|
+
## Update user key - `update_user_key`
|
|
2573
2546
|
|
|
2574
2547
|
To update the permissions of an existing key:
|
|
2575
2548
|
|
|
@@ -2595,7 +2568,7 @@ Algolia.get_user_key("f420238212c54dcfad07ea0aa6d5c45f")
|
|
|
2595
2568
|
index.get_user_key("71671c38001bf3ac857bc82052485107")
|
|
2596
2569
|
```
|
|
2597
2570
|
|
|
2598
|
-
|
|
2571
|
+
## Delete user key - `delete_user_key`
|
|
2599
2572
|
|
|
2600
2573
|
To delete an existing key:
|
|
2601
2574
|
|
|
@@ -2606,9 +2579,7 @@ Algolia.delete_user_key("f420238212c54dcfad07ea0aa6d5c45f")
|
|
|
2606
2579
|
index.delete_user_key("71671c38001bf3ac857bc82052485107")
|
|
2607
2580
|
```
|
|
2608
2581
|
|
|
2609
|
-
|
|
2610
|
-
|
|
2611
|
-
|
|
2582
|
+
## Get key permissions - `get_user_key_acl`
|
|
2612
2583
|
|
|
2613
2584
|
To get the permissions of a given key:
|
|
2614
2585
|
|
|
@@ -2619,7 +2590,7 @@ Algolia.get_user_key("f420238212c54dcfad07ea0aa6d5c45f")
|
|
|
2619
2590
|
index.get_user_key("71671c38001bf3ac857bc82052485107")
|
|
2620
2591
|
```
|
|
2621
2592
|
|
|
2622
|
-
|
|
2593
|
+
## Get last logs - `get_logs`
|
|
2623
2594
|
|
|
2624
2595
|
You can retrieve the latest logs via this API. Each log entry contains:
|
|
2625
2596
|
|
|
@@ -2635,78 +2606,25 @@ You can retrieve the latest logs via this API. Each log entry contains:
|
|
|
2635
2606
|
|
|
2636
2607
|
You can retrieve the logs of your last 1,000 API calls and browse them using the offset/length parameters:
|
|
2637
2608
|
|
|
2638
|
-
|
|
2639
|
-
|
|
2640
|
-
|
|
2641
|
-
|
|
2642
|
-
|
|
2643
|
-
|
|
2644
|
-
|
|
2645
|
-
|
|
2646
|
-
|
|
2647
|
-
|
|
2648
|
-
|
|
2649
|
-
|
|
2650
|
-
|
|
2651
|
-
|
|
2652
|
-
|
|
2653
|
-
|
|
2654
|
-
|
|
2655
|
-
|
|
2656
|
-
|
|
2657
|
-
<td valign='top'>
|
|
2658
|
-
<div class='client-readme-param-container'>
|
|
2659
|
-
<div class='client-readme-param-container-inner'>
|
|
2660
|
-
<div class='client-readme-param-name'><code>length</code></div>
|
|
2661
|
-
|
|
2662
|
-
</div>
|
|
2663
|
-
</div>
|
|
2664
|
-
</td>
|
|
2665
|
-
<td class='client-readme-param-content'>
|
|
2666
|
-
<p>Specify the maximum number of entries to retrieve starting at the offset. Defaults to 10. Maximum allowed value: 1,000.</p>
|
|
2667
|
-
|
|
2668
|
-
</td>
|
|
2669
|
-
</tr>
|
|
2670
|
-
|
|
2671
|
-
|
|
2672
|
-
<tr>
|
|
2673
|
-
<td valign='top'>
|
|
2674
|
-
<div class='client-readme-param-container'>
|
|
2675
|
-
<div class='client-readme-param-container-inner'>
|
|
2676
|
-
<div class='client-readme-param-name'><code>onlyErrors</code></div>
|
|
2677
|
-
|
|
2678
|
-
</div>
|
|
2679
|
-
</div>
|
|
2680
|
-
</td>
|
|
2681
|
-
<td class='client-readme-param-content'>
|
|
2682
|
-
<p>Retrieve only logs with an HTTP code different than 200 or 201. (deprecated)</p>
|
|
2683
|
-
|
|
2684
|
-
</td>
|
|
2685
|
-
</tr>
|
|
2686
|
-
|
|
2687
|
-
|
|
2688
|
-
<tr>
|
|
2689
|
-
<td valign='top'>
|
|
2690
|
-
<div class='client-readme-param-container'>
|
|
2691
|
-
<div class='client-readme-param-container-inner'>
|
|
2692
|
-
<div class='client-readme-param-name'><code>type</code></div>
|
|
2693
|
-
|
|
2694
|
-
</div>
|
|
2695
|
-
</div>
|
|
2696
|
-
</td>
|
|
2697
|
-
<td class='client-readme-param-content'>
|
|
2698
|
-
<p>Specify the type of logs to retrieve:</p>
|
|
2699
|
-
|
|
2700
|
-
<ul>
|
|
2701
|
-
<li><code>query</code>: Retrieve only the queries.</li>
|
|
2702
|
-
<li><code>build</code>: Retrieve only the build operations.</li>
|
|
2703
|
-
<li><code>error</code>: Retrieve only the errors (same as <code>onlyErrors</code> parameters).</li>
|
|
2704
|
-
</ul>
|
|
2705
|
-
|
|
2706
|
-
</td>
|
|
2707
|
-
</tr>
|
|
2708
|
-
|
|
2709
|
-
</tbody></table>
|
|
2609
|
+
#### offset
|
|
2610
|
+
|
|
2611
|
+
Specify the first entry to retrieve (0-based, 0 is the most recent log entry). Defaults to 0.
|
|
2612
|
+
|
|
2613
|
+
#### length
|
|
2614
|
+
|
|
2615
|
+
Specify the maximum number of entries to retrieve starting at the offset. Defaults to 10. Maximum allowed value: 1,000.
|
|
2616
|
+
|
|
2617
|
+
#### onlyErrors
|
|
2618
|
+
|
|
2619
|
+
Retrieve only logs with an HTTP code different than 200 or 201. (deprecated)
|
|
2620
|
+
|
|
2621
|
+
#### type
|
|
2622
|
+
|
|
2623
|
+
Specify the type of logs to retrieve:
|
|
2624
|
+
|
|
2625
|
+
* `query`: Retrieve only the queries.
|
|
2626
|
+
* `build`: Retrieve only the build operations.
|
|
2627
|
+
* `error`: Retrieve only the errors (same as `onlyErrors` parameters).
|
|
2710
2628
|
|
|
2711
2629
|
```ruby
|
|
2712
2630
|
# Get last 10 log entries
|
|
@@ -2717,8 +2635,7 @@ puts Algolia.get_logs(0, 100).to_json
|
|
|
2717
2635
|
puts Algolia.get_logs(0, 100, true).to_json
|
|
2718
2636
|
```
|
|
2719
2637
|
|
|
2720
|
-
|
|
2721
|
-
### REST API
|
|
2638
|
+
## REST API
|
|
2722
2639
|
|
|
2723
2640
|
We've developed API clients for the most common programming languages and platforms.
|
|
2724
2641
|
These clients are advanced wrappers on top of our REST API itself and have been made
|
|
@@ -2731,10 +2648,11 @@ The REST API lets your interact directly with Algolia platforms from anything th
|
|
|
2731
2648
|
[Go to the REST API doc](https://algolia.com/doc/rest)
|
|
2732
2649
|
|
|
2733
2650
|
|
|
2651
|
+
# Mocking
|
|
2734
2652
|
|
|
2735
|
-
## Mocking
|
|
2736
2653
|
|
|
2737
|
-
|
|
2654
|
+
|
|
2655
|
+
## Webmock
|
|
2738
2656
|
|
|
2739
2657
|
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`:
|
|
2740
2658
|
|
|
@@ -2763,4 +2681,3 @@ end
|
|
|
2763
2681
|
```
|
|
2764
2682
|
|
|
2765
2683
|
|
|
2766
|
-
|