diff --git a/website/docs/api-clients/guides/filtering-your-search.mdx b/website/docs/api-clients/guides/filtering-your-search.mdx new file mode 100644 index 0000000000..0d5b1a4251 --- /dev/null +++ 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. + + + + +```js +await client.setSettings({ + indexName: '', + indexSettings: { + attributesForFaceting: [ + 'actor', + 'filterOnly(category)', + 'searchable(publisher)', + ], + }, +}); +``` + + + + +### 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 + + + + +```js +// Only "Scarlett Johansson" actor +await client.search({ + indexName: '', + searchParams: { + query: '', + filters: 'actor:Scarlett Johansson', + }, +}); + +// Only "Tom Cruise" or "Scarlett Johansson" actor +await client.search({ + indexName: '', + searchParams: { + query: '', + filters: 'actor:Tom Cruise OR actor:Scarlett Johansson', + }, +}); + +// Everything but "Nicolas Cage" actor +await client.search({ + indexName: '', + searchParams: { + query: '', + filters: 'NOT actor:Nicolas Cage', + }, +}); +``` + + + + +#### Filtering by string using the `facetFilters` field + + + + +```js +// Only "Scarlett Johansson" actor +await client.search({ + indexName: '', + searchParams: { + query: '', + facetFilters: ['actor:Scarlett Johansson'], + }, +}); + +// Only "Tom Cruise" or "Scarlett Johansson" actor +await client.search({ + indexName: '', + searchParams: { + query: '', + facetFilters: ['actor:Tom Cruise', 'actor:Scarlett Johansson'], + }, +}); +``` + + + diff --git a/website/docs/api-clients/guides/retrieving-facets.mdx b/website/docs/api-clients/guides/retrieving-facets.mdx new file mode 100644 index 0000000000..4a56798f51 --- /dev/null +++ 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. + + + + +```js +await client.search({ + indexName: '', + searchParams: { + query: '', + facets: ['author', 'genre'], + }, +}); +``` + +To extract all facet information, you can use a wildcard (`*`). + +```js +await client.search({ + indexName: '', + searchParams: { + query: '', + facets: ['*'], + }, +}); +``` + + + diff --git a/website/docs/api-clients/guides/send-data-to-algolia.mdx b/website/docs/api-clients/guides/send-data-to-algolia.mdx new file mode 100644 index 0000000000..8a29fa77d8 --- /dev/null +++ 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). + + + + +```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('', ''); +``` + + + + +## 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. + + + + +```js +const records = [{ name: 'Tom Cruise' }, { name: 'Scarlett Johansson' }]; + +client.saveObject({ + indexName: '', + // Accepts a free form `Record` object. + body: records, +}); +``` + + + diff --git a/website/docs/api-clients/installation.mdx b/website/docs/api-clients/installation.mdx index 26c562fc08..2fdd20942c 100644 --- a/website/docs/api-clients/installation.mdx +++ b/website/docs/api-clients/installation.mdx @@ -116,15 +116,16 @@ console.log('[Results]', res); -## 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( '', @@ -135,11 +136,13 @@ $client->saveObject('', ['objectID' => 1, 'name' => 'Foo']); ``` Finally, you may begin searching an object using the `search` method: + ```php $objects = $client->search('', ['query' => 'Foo']); ``` Another example with the personalization client: + ```php $client = Algolia\AlgoliaSearch\Api\PersonalizationClient::create( '', @@ -148,5 +151,6 @@ $client = Algolia\AlgoliaSearch\Api\PersonalizationClient::create( $res = $client->getUserTokenProfile(''); ``` + diff --git a/website/docs/api-clients/migration-guide.mdx b/website/docs/api-clients/migration-guide.mdx index 1e00da8f74..7c0c5db474 100644 --- 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). - - - ### Importing algoliasearch using ES Modules - - - ```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 index e6113b639c..fbbaad0058 100644 --- 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', + ], + }, ], };