Skip to content

Commit 9c3327e

Browse files
shortcutsshortcuts
authored
docs: add some useful guides (#450)
1 parent 3444af0 commit 9c3327e

File tree

6 files changed

+251
-17
lines changed

6 files changed

+251
-17
lines changed

‎website/docs/api-clients/guides/filtering-your-search.mdx

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: Filtering your search
3+
---
4+
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
Filtering is primarily used in the context of front-end search. We call this faceting, where filters are displayed on the search UI as clickable items, allowing users to select one or more filters. This enables a more refined, drilled-down search experience.
9+
10+
## How to Filter Your Data
11+
12+
### 1. Define attributes that need to be filterable (at indexing time)
13+
14+
Initially, filter attributes must be defined as facets, using the `attributesForFaceting` parameter. This can be done using the `setSettings` method.
15+
16+
<Tabs
17+
groupId="language"
18+
defaultValue="js"
19+
values={[
20+
{ label: 'JavaScript', value: 'js', }
21+
]
22+
}>
23+
<TabItem value="js">
24+
25+
```js
26+
await client.setSettings({
27+
indexName: '<YOUR_INDEX_NAME>',
28+
indexSettings: {
29+
attributesForFaceting: [
30+
'actor',
31+
'filterOnly(category)',
32+
'searchable(publisher)',
33+
],
34+
},
35+
});
36+
```
37+
38+
</TabItem>
39+
</Tabs>
40+
41+
### 2. Filter by Attributes (at query time)
42+
43+
The actual filtering of records is performed at query time, not at indexing time. For this, you need to use the filters parameter in your search code.
44+
45+
#### Filtering by string using the `filters` field
46+
47+
<Tabs
48+
groupId="language"
49+
defaultValue="js"
50+
values={[
51+
{ label: 'JavaScript', value: 'js', }
52+
]
53+
}>
54+
<TabItem value="js">
55+
56+
```js
57+
// Only "Scarlett Johansson" actor
58+
await client.search({
59+
indexName: '<YOUR_INDEX_NAME>',
60+
searchParams: {
61+
query: '<YOUR_QUERY>',
62+
filters: 'actor:Scarlett Johansson',
63+
},
64+
});
65+
66+
// Only "Tom Cruise" or "Scarlett Johansson" actor
67+
await client.search({
68+
indexName: '<YOUR_INDEX_NAME>',
69+
searchParams: {
70+
query: '<YOUR_QUERY>',
71+
filters: 'actor:Tom Cruise OR actor:Scarlett Johansson',
72+
},
73+
});
74+
75+
// Everything but "Nicolas Cage" actor
76+
await client.search({
77+
indexName: '<YOUR_INDEX_NAME>',
78+
searchParams: {
79+
query: '<YOUR_QUERY>',
80+
filters: 'NOT actor:Nicolas Cage',
81+
},
82+
});
83+
```
84+
85+
</TabItem>
86+
</Tabs>
87+
88+
#### Filtering by string using the `facetFilters` field
89+
90+
<Tabs
91+
groupId="language"
92+
defaultValue="js"
93+
values={[
94+
{ label: 'JavaScript', value: 'js', }
95+
]
96+
}>
97+
<TabItem value="js">
98+
99+
```js
100+
// Only "Scarlett Johansson" actor
101+
await client.search({
102+
indexName: '<YOUR_INDEX_NAME>',
103+
searchParams: {
104+
query: '<YOUR_QUERY>',
105+
facetFilters: ['actor:Scarlett Johansson'],
106+
},
107+
});
108+
109+
// Only "Tom Cruise" or "Scarlett Johansson" actor
110+
await client.search({
111+
indexName: '<YOUR_INDEX_NAME>',
112+
searchParams: {
113+
query: '<YOUR_QUERY>',
114+
facetFilters: ['actor:Tom Cruise', 'actor:Scarlett Johansson'],
115+
},
116+
});
117+
```
118+
119+
</TabItem>
120+
</Tabs>

‎website/docs/api-clients/guides/retrieving-facets.mdx

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: Retrieving facets
3+
---
4+
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
To retrieve facets and their respective counts as part of the JSON response, you must specify a list of facets in the facets parameter at query time.
9+
10+
For example, you can retrieve your books' facets with the `search` method, and the `facets` parameter.
11+
12+
> When the `facets` parameter is empty, the engine returns no facet information.
13+
14+
<Tabs
15+
groupId="language"
16+
defaultValue="js"
17+
values={[
18+
{ label: 'JavaScript', value: 'js', }
19+
]
20+
}>
21+
<TabItem value="js">
22+
23+
```js
24+
await client.search({
25+
indexName: '<YOUR_INDEX_NAME>',
26+
searchParams: {
27+
query: '<YOUR_QUERY>',
28+
facets: ['author', 'genre'],
29+
},
30+
});
31+
```
32+
33+
To extract all facet information, you can use a wildcard (`*`).
34+
35+
```js
36+
await client.search({
37+
indexName: '<YOUR_INDEX_NAME>',
38+
searchParams: {
39+
query: '<YOUR_QUERY>',
40+
facets: ['*'],
41+
},
42+
});
43+
```
44+
45+
</TabItem>
46+
</Tabs>

‎website/docs/api-clients/guides/send-data-to-algolia.mdx

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: Send data to Algolia
3+
---
4+
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
Algolia doesn’t search directly into your own data source. For data to be searchable, you need to send it to Algolia’s servers.
9+
10+
This happens right after retrieving your data from your data source and reformatting it. Once your data is ready, you can push it to Algolia using the `saveObjects` method.
11+
12+
## Required credentials
13+
14+
To push data to Algolia, you need an Application ID and a valid API key with the right access level. You can find them and create new ones [in the API keys page](https://www.algolia.com/account/api-keys/all?applicationId=QPBQ67WNIG).
15+
16+
## Setting up the API client
17+
18+
> [Make sure to also read the Installation page](/docs/api-clients/installation).
19+
20+
<Tabs
21+
groupId="language"
22+
defaultValue="js"
23+
values={[
24+
{ label: 'JavaScript', value: 'js', }
25+
]
26+
}>
27+
<TabItem value="js">
28+
29+
```js
30+
// for the default version
31+
import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch';
32+
33+
// you can also import the lite version, with search only versions
34+
// import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch-lite';
35+
36+
const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
37+
```
38+
39+
</TabItem>
40+
</Tabs>
41+
42+
## Fetching your data
43+
44+
Before sending anything to Algolia, you need to retrieve your data. You can do this in several ways, in our case we will pick it from the source code directly.
45+
46+
<Tabs
47+
groupId="language"
48+
defaultValue="js"
49+
values={[
50+
{ label: 'JavaScript', value: 'js', }
51+
]
52+
}>
53+
<TabItem value="js">
54+
55+
```js
56+
const records = [{ name: 'Tom Cruise' }, { name: 'Scarlett Johansson' }];
57+
58+
client.saveObject({
59+
indexName: '<YOUR_INDEX_NAME>',
60+
// Accepts a free form `Record<string, any>` object.
61+
body: records,
62+
});
63+
```
64+
65+
</TabItem>
66+
</Tabs>

‎website/docs/api-clients/installation.mdx

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,15 +116,16 @@ console.log('[Results]', res);
116116

117117
<TabItem value="php">
118118

119-
## Installation
120-
121119
First, install Algolia PHP API Client via the composer package manager:
120+
122121
```bash
123122
composer require algolia/algoliasearch-client-php
124123
```
124+
125125
## Using the client
126126

127127
Then, create objects on your index:
128+
128129
```php
129130
$client = Algolia\AlgoliaSearch\Api\SearchClient::create(
130131
'<YOUR_APP_ID>',
@@ -135,11 +136,13 @@ $client->saveObject('<YOUR_INDEX>', ['objectID' => 1, 'name' => 'Foo']);
135136
```
136137

137138
Finally, you may begin searching an object using the `search` method:
139+
138140
```php
139141
$objects = $client->search('<YOUR_INDEX>', ['query' => 'Foo']);
140142
```
141143

142144
Another example with the personalization client:
145+
143146
```php
144147
$client = Algolia\AlgoliaSearch\Api\PersonalizationClient::create(
145148
'<YOUR_APP_ID>',
@@ -148,5 +151,6 @@ $client = Algolia\AlgoliaSearch\Api\PersonalizationClient::create(
148151

149152
$res = $client->getUserTokenProfile('<YOUR_TOKEN>');
150153
```
154+
151155
</TabItem>
152156
</Tabs>

‎website/docs/api-clients/migration-guide.mdx

Lines changed: 3 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,9 @@ The amount of changes in this new version is significant. If you were using a ve
1919

2020
The changes below are effective on all of the API clients.
2121

22-
| Previous | Latest | Description |
23-
| ----------- | :---------- | :------------------------------------------------- |
24-
| `initIndex` | **removed** | All methods are now available at the client level. |
22+
| Previous | Latest | Description |
23+
| ----------- | :---------- | :------------------------------------------------------------------------------------------------------- |
24+
| `initIndex` | **removed** | All methods are now available at the client level. [See example below](#methods-targetting-an-indexname) |
2525

2626
## API Client specific breaking changes
2727

@@ -78,20 +78,8 @@ npm uninstall algoliasearch
7878

7979
You can continue this guide on [our installation page](/docs/api-clients/installation).
8080

81-
</TabItem>
82-
</Tabs>
83-
8481
### Importing algoliasearch using ES Modules
8582

86-
<Tabs
87-
groupId="language"
88-
defaultValue="js"
89-
values={[
90-
{ label: 'JavaScript', value: 'js', }
91-
]
92-
}>
93-
<TabItem value="js">
94-
9583
```diff
9684
- import algoliasearch from 'algoliasearch/lite';
9785
+ import { algoliasearchLiteClient } from '@experimental-api-clients-automation/algoliasearch-lite';

‎website/sidebars.js

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,16 @@ const sidebars = {
5353
collapsed: false,
5454
items: ['api-clients/installation', 'api-clients/migration-guide'],
5555
},
56+
{
57+
type: 'category',
58+
label: 'Guides',
59+
collapsed: false,
60+
items: [
61+
'api-clients/guides/send-data-to-algolia',
62+
'api-clients/guides/filtering-your-search',
63+
'api-clients/guides/retrieving-facets',
64+
],
65+
},
5666
],
5767
};
5868

0 commit comments

Comments
 (0)