Skip to content

Commit adb5819

Browse files
PensuPensu
committed
Adding feature descriptions
1 parent d2cb2a4 commit adb5819

File tree

8 files changed

+589
-0
lines changed

8 files changed

+589
-0
lines changed

‎docs-site/content/.vuepress/config.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,10 @@ let config = {
149149
['/0.19.0/guide/features/typo-tolerance', 'Typo Tolerance'],
150150
['/0.19.0/guide/features/faceting', 'Faceting'],
151151
['/0.19.0/guide/features/filtering', 'Filtering'],
152+
['/0.19.0/guide/features/federated-search', 'Federated Search'],
153+
['/0.19.0/guide/features/multi-tenant-indices', 'Multi-tenant Indices'],
154+
['/0.19.0/guide/features/synonyms', 'Synonyms'],
155+
['/0.19.0/guide/features/clustering', 'Raft Based Clustering'],
152156
],
153157
},
154158
],

‎docs-site/content/.vuepress/public/images/bhp-federated.png‎

1.19 MB
Loading

‎docs-site/content/.vuepress/public/images/typesense-filter.png‎

262 KB
Loading

‎docs-site/content/0.19.0/guide/features/federated.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Federated Search
2+
3+
Federated or multi search is a way to search for documents in multiple collections as part of a single search query. You can also use multi-search to send multiple search queries to the same collections, essentially giving you a way to batch search queries in a single HTTP request. Federated search can help reduce network latencies. It can also be used to present similar content from other collections, that might encourage users to browse more content across your application. For example, your application might have different collections for `Nike` and `Adidas`. Now, if a user is looking for a shoe from a specific branch and they might not know what other brands are available, the search query can perform a search on both the collections and return relevant results from both the collections.
4+
5+
For example, if you search for `Canon` on https://www.bhphotovideo.com/, you would see that there are multiple results shown including products, suggestions and help resources:
6+
7+
![bhp federated example](~@images/bhp-federated.png)
8+
9+
Typesense supports searching across multiple collections in a single HTTP request. Let's create a search query for shoes:
10+
11+
<Tabs :tabs="['JavaScript','PHP','Python','Ruby']">
12+
<template v-slot:JavaScript>
13+
14+
```javascript
15+
let searchRequests = {
16+
'searches': [
17+
{
18+
'collection': 'products',
19+
'q': 'shoe',
20+
'filter_by': 'price:=[50..120]'
21+
},
22+
{
23+
'collection': 'brands',
24+
'q': 'Nike'
25+
}
26+
]
27+
}
28+
29+
// Search parameters that are common to all searches go here
30+
let commonSearchParams = {
31+
'query_by': 'name',
32+
}
33+
34+
client.multiSearch.perform(searchRequests, commonSearchParams)
35+
```
36+
</template>
37+
38+
<template v-slot:PHP>
39+
40+
```php
41+
$searchRequests = [
42+
'searches' => [
43+
[
44+
'collection' => 'products',
45+
'q' => 'shoe',
46+
'filter_by' => 'price:=[50..120]'
47+
],
48+
[
49+
'collection' => 'brands',
50+
'q' => 'Nike'
51+
]
52+
]
53+
];
54+
55+
// Search parameters that are common to all searches go here
56+
$commonSearchParams = [
57+
'query_by' => 'name',
58+
];
59+
60+
$client->multiSearch->perform($searchRequests, $commonSearchParams);
61+
```
62+
</template>
63+
<template v-slot:Python>
64+
65+
```python
66+
search_requests = {
67+
'searches': [
68+
{
69+
'collection': 'products',
70+
'q': 'shoe',
71+
'filter_by': 'price:=[50..120]'
72+
},
73+
{
74+
'collection': 'brands',
75+
'q': 'Nike'
76+
}
77+
]
78+
}
79+
80+
# Search parameters that are common to all searches go here
81+
common_search_params = {
82+
'query_by': 'name',
83+
}
84+
85+
client.multi_search.perform(search_requests, common_search_params)
86+
```
87+
</template>
88+
<template v-slot:Ruby>
89+
90+
```ruby
91+
search_requests = {
92+
'searches': [
93+
{
94+
'collection': 'products',
95+
'q': 'shoe',
96+
'filter_by': 'price:=[50..120]'
97+
},
98+
{
99+
'collection': 'brands',
100+
'q': 'Nike'
101+
}
102+
]
103+
}
104+
105+
# Search parameters that are common to all searches go here
106+
common_search_params = {
107+
'query_by': 'name',
108+
}
109+
110+
client.multi_search.perform(search_requests, common_search_params)
111+
```
112+
</template>
113+
</Tabs>
114+
115+
Sample response:
116+
117+
```json
118+
{
119+
"results": [
120+
{
121+
"facet_counts": [],
122+
"found": 1,
123+
"hits": [
124+
{
125+
"document": {
126+
"name": "Blue shoe",
127+
"brand": "Adidas",
128+
"id": "126",
129+
"price": 50
130+
},
131+
"highlights": [
132+
{
133+
"field": "name",
134+
"matched_tokens": [
135+
"shoe"
136+
],
137+
"snippet": "Blue <mark>shoe</mark>"
138+
}
139+
],
140+
"text_match": 130816
141+
}
142+
],
143+
"out_of": 10,
144+
"page": 1,
145+
"request_params": {
146+
"per_page": 10,
147+
"q": "shoe"
148+
},
149+
"search_time_ms": 1
150+
},
151+
{
152+
"facet_counts": [],
153+
"found": 1,
154+
"hits": [
155+
{
156+
"document": {
157+
"name": "Nike shoes",
158+
"brand": "Nike",
159+
"id": "391",
160+
"price": 60
161+
},
162+
"highlights": [
163+
{
164+
"field": "name",
165+
"matched_tokens": [
166+
"Nike"
167+
],
168+
"snippet": "<mark>Nike</mark>shoes"
169+
}
170+
],
171+
"text_match": 144112
172+
}
173+
],
174+
"out_of": 5,
175+
"page": 1,
176+
"request_params": {
177+
"per_page": 10,
178+
"q": "Nike"
179+
},
180+
"search_time_ms": 1
181+
},
182+
]
183+
}
184+
```
185+
186+
In the above example, the user is searching for a `Nike` shoe, but the `multiSerch` query returns results from the `Adidas` collection as well. You can control the number of maximum search requests using the `limit_multi_searches` parameter. By default, there is no limit. You can find more details on the argument [here](../../0.19.0/api/documents.html#federated-multi-search).

‎docs-site/content/0.19.0/guide/features/multi-tenant-indices.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Scoped API Keys
2+
3+
Typesense is designed with security and fine-grained access control in mind. To perform any action with Typesense, you need API keys. Typesense also allows access control on API keys. You can define capabilities as to what a user can or cannot do. You can also restrict access to a specific document or collection. In the case of a multi-tenant environment, you can scope API keys to a particular subset. This is helpful when you have indexed data from multiple tenants in your Typesense server and want to restrict users to only access their subset of data.
4+
5+
Typesense allows you to create API keys that have pre-defined filters embedded in them. So, whenever you run a search query with these API keys, those filters are automatically applied and cannot be overridden. You can then provide those search API keys to users and they would only be able to access the data that is allowed by the set filter. To create scoped API keys, you just need a parent key.
6+
7+
Let's take example of a [company collection](../../api/collections.html#create-a-collection), that has the following documents:
8+
9+
```shell
10+
{"company_id":124,"company_name":"Stark Industries","country":"USA","id":"0","num_employees":3355}
11+
{"company_id":125,"company_name":"Wayne Enterprises","country":"USA","id":"1","num_employees":4538}
12+
{"company_id":126,"company_name":"Daily Planet","country":"USA","id":"2","num_employees":2232}
13+
{"company_id":127,"company_name":"New Stark Industries","country":"USA","id":"3","num_employees":7945}
14+
```
15+
16+
Now, let's create a scoped API key that will restrict access to documents that have the `company_id` value as 124.
17+
18+
<Tabs :tabs="['JavaScript','PHP','Python','Ruby', 'Shell']">
19+
<template v-slot:JavaScript>
20+
21+
```javascript
22+
keyWithSearchPermissions = 'RN23GFr1s6jQ9kgSNg2O7fYcAUXU7127'
23+
client.keys().generateScopedSearchKey(keyWithSearchPermissions, {'filter_by': 'company_id:124', 'expires_at': 1611590465})
24+
```
25+
</template>
26+
27+
<template v-slot:PHP>
28+
29+
```php
30+
$keyWithSearchPermissions = 'RN23GFr1s6jQ9kgSNg2O7fYcAUXU7127';
31+
$client->keys()->generateScopedSearchKey($keyWithSearchPermissions, ['filter_by' => 'company_id:124', 'expires_at' => 1611590465]);
32+
```
33+
</template>
34+
<template v-slot:Python>
35+
36+
```python
37+
key_with_search_permissions = 'RN23GFr1s6jQ9kgSNg2O7fYcAUXU7127'
38+
client.keys().generate_scoped_search_key(key_with_search_permissions, {"filter_by": "company_id:124", "expires_at": 1611590465})
39+
```
40+
</template>
41+
<template v-slot:Ruby>
42+
43+
```ruby
44+
key_with_search_permissions = 'RN23GFr1s6jQ9kgSNg2O7fYcAUXU7127'
45+
client.keys().generate_scoped_search_key(key_with_search_permissions, {'filter_by': 'company_id:124', 'expires_at': 1611590465})
46+
```
47+
</template>
48+
<template v-slot:Shell>
49+
50+
```bash
51+
KEY_WITH_SEARCH_PERMISSIONS="RN23GFr1s6jQ9kgSNg2O7fYcAUXU7127"
52+
EMBEDDED_SEARCH_PARAMETERS_JSON='{"filter_by":"company_id:124","expires_at":1611590465}'
53+
54+
digest=$(echo -n $EMBEDDED_SEARCH_PARAMETERS_JSON | openssl dgst -sha256 -hmac $KEY_WITH_SEARCH_PERMISSIONS -binary | base64)
55+
56+
scoped_api_key=$(echo -n "${digest}${KEY_WITH_SEARCH_PERMISSIONS:0:4}${EMBEDDED_SEARCH_PARAMETERS_JSON}" | base64)
57+
58+
echo $scoped_api_key
59+
```
60+
61+
</template>
62+
</Tabs>
63+
64+
Sample response:
65+
66+
```json
67+
"RDhxa2VKTnBQVkxaVlFIOS9JWDZ2bDdtMU5HL3laa0pab2pTeEUzbFBhZz1STjIzeyJmaWx0ZXJfYnkiOiJjb21wYW55X2lkOjEyNCIsImV4cGlyZXNfYXQiOjE2MTE1OTA0NjV9"
68+
```
69+
70+
The `expires_at` parameter sets the expiration date for the API key and must be less that the expiration of parent API key. Let's perform a search using the scoped API key:
71+
72+
<Tabs :tabs="['JavaScript','PHP','Python','Ruby']">
73+
<template v-slot:JavaScript>
74+
75+
```javascript
76+
let searchParameters = {
77+
'q' : 'Stark',
78+
'query_by' : 'company_name',
79+
'sort_by' : 'num_employees:desc'
80+
}
81+
82+
client.collections('companies')
83+
.documents()
84+
.search(searchParameters)
85+
.then(function (searchResults) {
86+
console.log(searchResults)
87+
})
88+
```
89+
</template>
90+
91+
<template v-slot:PHP>
92+
93+
```php
94+
$$searchParameters = [
95+
'q' => 'Stark',
96+
'query_by' => 'company_name',
97+
'sort_by' => 'num_employees:desc'
98+
]
99+
100+
$client->collections['companies']->documents->search($searchParameters)
101+
```
102+
</template>
103+
<template v-slot:Python>
104+
105+
```python
106+
search_parameters = {
107+
'q' : 'Stark',
108+
'query_by' : 'company_name',
109+
'sort_by' : 'num_employees:desc'
110+
}
111+
112+
client.collections['companies'].documents.search(search_parameters)
113+
```
114+
</template>
115+
<template v-slot:Ruby>
116+
117+
```ruby
118+
search_parameters = {
119+
'q' => 'Stark',
120+
'query_by' => 'company_name',
121+
'sort_by' => 'num_employees:desc'
122+
}
123+
124+
client.collections['companies'].documents.search(search_parameters)
125+
```
126+
</template>
127+
</Tabs>
128+
129+
130+
Response:
131+
132+
```json
133+
{
134+
"facet_counts": [],
135+
"found": 1,
136+
"hits": [
137+
{
138+
"document": {
139+
"company_id": 124,
140+
"company_name": "Stark Industries",
141+
"country": "USA",
142+
"id": "0",
143+
"num_employees": 3355
144+
},
145+
"highlights": [
146+
{
147+
"field": "company_name",
148+
"matched_tokens": [
149+
"Stark"
150+
],
151+
"snippet": "<mark>Stark</mark> Industries"
152+
}
153+
],
154+
"text_match": 130816
155+
}
156+
],
157+
"out_of": 4,
158+
"page": 1,
159+
"request_params": {
160+
"collection_name": "companies",
161+
"per_page": 10,
162+
"q": "stark"
163+
},
164+
"search_time_ms": 0
165+
}
166+
```
167+
168+
As you see in the response, the document with `company_id` set to 124 is shown in the output. There is another document that has the `company_name` as "New Stark Industries", but it won't be shown in the result.
169+
170+
You can find more details about scoped API keys [here](../../api/api-keys.html#generate-scoped-search-key).

‎docs-site/content/0.19.0/guide/features/raft.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Raft Based Clustering
2+
3+
High availability is essential for production environments. Typesense uses the [Raft Consensus Algorithm](https://raft.github.io/) to create a highly available cluster with more than one Typesense servers. With Raft, you need to create a cluster of 3 nodes to tolerate single node failures. If you wish to handle 2-node failures, then you need a minimum of 5 nodes in the cluster. Note that adding more nodes will also increase write latencies.
4+
5+
More details on cluster operations can be found [here](../../api/cluster-operations.html).

0 commit comments

Comments
 (0)