docs: add some useful guides (#450)

algolia · May 2, 2022 · 9c3327e · 9c3327e
1 parent 3444af0
commit 9c3327e
Show file tree

Hide file tree

Showing 6 changed files with 251 additions and 17 deletions.
diff --git a/website/docs/api-clients/guides/filtering-your-search.mdx b/website/docs/api-clients/guides/filtering-your-search.mdx
@@ -0,0 +1,120 @@
+---
+title: Filtering your search
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+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.
+
+## How to Filter Your Data
+
+### 1. Define attributes that need to be filterable (at indexing time)
+
+Initially, filter attributes must be defined as facets, using the `attributesForFaceting` parameter. This can be done using the `setSettings` method.
+
+<Tabs
+  groupId="language"
+  defaultValue="js"
+  values={[
+    { label: 'JavaScript', value: 'js', }
+  ]
+}>
+<TabItem value="js">
+
+```js
+await client.setSettings({
+  indexName: '<YOUR_INDEX_NAME>',
+  indexSettings: {
+    attributesForFaceting: [
+      'actor',
+      'filterOnly(category)',
+      'searchable(publisher)',
+    ],
+  },
+});
+```
+
+</TabItem>
+</Tabs>
+
+### 2. Filter by Attributes (at query time)
+
+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.
+
+#### Filtering by string using the `filters` field
+
+<Tabs
+  groupId="language"
+  defaultValue="js"
+  values={[
+    { label: 'JavaScript', value: 'js', }
+  ]
+}>
+<TabItem value="js">
+
+```js
+// Only "Scarlett Johansson" actor
+await client.search({
+  indexName: '<YOUR_INDEX_NAME>',
+  searchParams: {
+    query: '<YOUR_QUERY>',
+    filters: 'actor:Scarlett Johansson',
+  },
+});
+
+// Only "Tom Cruise" or "Scarlett Johansson" actor
+await client.search({
+  indexName: '<YOUR_INDEX_NAME>',
+  searchParams: {
+    query: '<YOUR_QUERY>',
+    filters: 'actor:Tom Cruise OR actor:Scarlett Johansson',
+  },
+});
+
+// Everything but "Nicolas Cage" actor
+await client.search({
+  indexName: '<YOUR_INDEX_NAME>',
+  searchParams: {
+    query: '<YOUR_QUERY>',
+    filters: 'NOT actor:Nicolas Cage',
+  },
+});
+```
+
+</TabItem>
+</Tabs>
+
+#### Filtering by string using the `facetFilters` field
+
+<Tabs
+  groupId="language"
+  defaultValue="js"
+  values={[
+    { label: 'JavaScript', value: 'js', }
+  ]
+}>
+<TabItem value="js">
+
+```js
+// Only "Scarlett Johansson" actor
+await client.search({
+  indexName: '<YOUR_INDEX_NAME>',
+  searchParams: {
+    query: '<YOUR_QUERY>',
+    facetFilters: ['actor:Scarlett Johansson'],
+  },
+});
+
+// Only "Tom Cruise" or "Scarlett Johansson" actor
+await client.search({
+  indexName: '<YOUR_INDEX_NAME>',
+  searchParams: {
+    query: '<YOUR_QUERY>',
+    facetFilters: ['actor:Tom Cruise', 'actor:Scarlett Johansson'],
+  },
+});
+```
+
+</TabItem>
+</Tabs>
diff --git a/website/docs/api-clients/guides/retrieving-facets.mdx b/website/docs/api-clients/guides/retrieving-facets.mdx
@@ -0,0 +1,46 @@
+---
+title: Retrieving facets
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+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.
+
+For example, you can retrieve your books' facets with the `search` method, and the `facets` parameter.
+
+> When the `facets` parameter is empty, the engine returns no facet information.
+
+<Tabs
+  groupId="language"
+  defaultValue="js"
+  values={[
+    { label: 'JavaScript', value: 'js', }
+  ]
+}>
+<TabItem value="js">
+
+```js
+await client.search({
+  indexName: '<YOUR_INDEX_NAME>',
+  searchParams: {
+    query: '<YOUR_QUERY>',
+    facets: ['author', 'genre'],
+  },
+});
+```
+
+To extract all facet information, you can use a wildcard (`*`).
+
+```js
+await client.search({
+  indexName: '<YOUR_INDEX_NAME>',
+  searchParams: {
+    query: '<YOUR_QUERY>',
+    facets: ['*'],
+  },
+});
+```
+
+</TabItem>
+</Tabs>
diff --git a/website/docs/api-clients/guides/send-data-to-algolia.mdx b/website/docs/api-clients/guides/send-data-to-algolia.mdx
@@ -0,0 +1,66 @@
+---
+title: Send data to Algolia
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Algolia doesn’t search directly into your own data source. For data to be searchable, you need to send it to Algolia’s servers.
+
+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.
+
+## Required credentials
+
+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).
+
+## Setting up the API client
+
+> [Make sure to also read the Installation page](/docs/api-clients/installation).
+
+<Tabs
+  groupId="language"
+  defaultValue="js"
+  values={[
+    { label: 'JavaScript', value: 'js', }
+  ]
+}>
+<TabItem value="js">
+
+```js
+// for the default version
+import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch';
+
+// you can also import the lite version, with search only versions
+// import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch-lite';
+
+const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
+```
+
+</TabItem>
+</Tabs>
+
+## Fetching your data
+
+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.
+
+<Tabs
+  groupId="language"
+  defaultValue="js"
+  values={[
+    { label: 'JavaScript', value: 'js', }
+  ]
+}>
+<TabItem value="js">
+
+```js
+const records = [{ name: 'Tom Cruise' }, { name: 'Scarlett Johansson' }];
+
+client.saveObject({
+  indexName: '<YOUR_INDEX_NAME>',
+  // Accepts a free form `Record<string, any>` object.
+  body: records,
+});
+```
+
+</TabItem>
+</Tabs>
diff --git a/website/docs/api-clients/installation.mdx b/website/docs/api-clients/installation.mdx
@@ -116,15 +116,16 @@ console.log('[Results]', res);
 
 <TabItem value="php">
 
-## Installation
-
 First, install Algolia PHP API Client via the composer package manager:
+
 ```bash
 composer require algolia/algoliasearch-client-php
 ```
+
 ## Using the client
 
 Then, create objects on your index:
+
 ```php
 $client = Algolia\AlgoliaSearch\Api\SearchClient::create(
     '<YOUR_APP_ID>',
@@ -135,11 +136,13 @@ $client->saveObject('<YOUR_INDEX>', ['objectID' => 1, 'name' => 'Foo']);
 ```
 
 Finally, you may begin searching an object using the `search` method:
+
 ```php
 $objects = $client->search('<YOUR_INDEX>', ['query' => 'Foo']);
 ```
 
 Another example with the personalization client:
+
 ```php
 $client = Algolia\AlgoliaSearch\Api\PersonalizationClient::create(
     '<YOUR_APP_ID>',
@@ -148,5 +151,6 @@ $client = Algolia\AlgoliaSearch\Api\PersonalizationClient::create(
 
 $res = $client->getUserTokenProfile('<YOUR_TOKEN>');
 ```
+
 </TabItem>
 </Tabs>
diff --git a/website/docs/api-clients/migration-guide.mdx b/website/docs/api-clients/migration-guide.mdx
@@ -19,9 +19,9 @@ The amount of changes in this new version is significant. If you were using a ve
 
 The changes below are effective on all of the API clients.
 
-| Previous    | Latest      | Description                                        |
-| ----------- | :---------- | :------------------------------------------------- |
-| `initIndex` | **removed** | All methods are now available at the client level. |
+| Previous    | Latest      | Description                                                                                              |
+| ----------- | :---------- | :------------------------------------------------------------------------------------------------------- |
+| `initIndex` | **removed** | All methods are now available at the client level. [See example below](#methods-targetting-an-indexname) |
 
 ## API Client specific breaking changes
 
@@ -78,20 +78,8 @@ npm uninstall algoliasearch
 
 You can continue this guide on [our installation page](/docs/api-clients/installation).
 
-</TabItem>
-</Tabs>
-
 ### Importing algoliasearch using ES Modules
 
-<Tabs
-  groupId="language"
-  defaultValue="js"
-  values={[
-    { label: 'JavaScript', value: 'js', }
-  ]
-}>
-<TabItem value="js">
-
 ```diff
 - import algoliasearch from 'algoliasearch/lite';
 + import { algoliasearchLiteClient } from '@experimental-api-clients-automation/algoliasearch-lite';

diff --git a/website/sidebars.js b/website/sidebars.js
@@ -53,6 +53,16 @@ const sidebars = {
       collapsed: false,
       items: ['api-clients/installation', 'api-clients/migration-guide'],
     },
+    {
+      type: 'category',
+      label: 'Guides',
+      collapsed: false,
+      items: [
+        'api-clients/guides/send-data-to-algolia',
+        'api-clients/guides/filtering-your-search',
+        'api-clients/guides/retrieving-facets',
+      ],
+    },
   ],
 };