Retrieving facets

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.

C#

using Algolia.Search.Clients;
using Algolia.Search.Http;

var client = new SearchClient(new SearchConfig("YOUR_APP_ID", "YOUR_API_KEY"));

var response = await client.SearchAsync<Object>(
  new SearchMethodParams
  {
    Requests = new List<SearchQuery>
    {
      new SearchQuery(
        new SearchForHits
        {
          IndexName = "<YOUR_INDEX_NAME>",
          Query = "<YOUR_QUERY>",
          Facets = new List<string> { "author", "genre" },
        }
      )
    },
  }
);

Dart

import 'package:algolia_client_search/algolia_client_search.dart';

final client = SearchClient(appId: 'YOUR_APP_ID', apiKey: 'YOUR_API_KEY');

final response = await client.search(
  searchMethodParams: SearchMethodParams(
    requests: [
      SearchForHits(
        indexName: "<YOUR_INDEX_NAME>",
        query: "<YOUR_QUERY>",
        facets: [
          "author",
          "genre",
        ],
      ),
    ],
  ),
);

Go

import "github.com/algolia/algoliasearch-client-go/v4/algolia/search"

client, err := search.NewClient("YOUR_APP_ID", "YOUR_API_KEY")

response, err := client.Search(client.NewApiSearchRequest(

  search.NewEmptySearchMethodParams().SetRequests(
    []search.SearchQuery{*search.SearchForHitsAsSearchQuery(
      search.NewEmptySearchForHits().SetIndexName("<YOUR_INDEX_NAME>").SetQuery("<YOUR_QUERY>").SetFacets(
        []string{"author", "genre"}))}),
))
if err != nil {
  // handle the eventual error
  panic(err)
}

// use the model directly
print(response)

Java

import com.algolia.api.SearchClient;
import com.algolia.model.search.*;

SearchClient client = new SearchClient("YOUR_APP_ID", "YOUR_API_KEY");

client.search(
  new SearchMethodParams()
    .setRequests(
      List.of(new SearchForHits().setIndexName("<YOUR_INDEX_NAME>").setQuery("<YOUR_QUERY>").setFacets(List.of("author", "genre")))
    ),
  Hit.class
);

JavaScript

import { searchClient } from '@algolia/client-search';

const client = searchClient('YOUR_APP_ID', 'YOUR_API_KEY');

const response = await client.search({
  requests: [
    {
      indexName: '<YOUR_INDEX_NAME>',
      query: '<YOUR_QUERY>',
      facets: ['author', 'genre'],
    },
  ],
});

// use typed response
console.log(response);

Kotlin

import com.algolia.client.api.SearchClient

val client = SearchClient(appId = "YOUR_APP_ID", apiKey = "YOUR_API_KEY")

var response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = listOf(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = "<YOUR_QUERY>",
        facets = listOf("author", "genre"),
      ),
    ),
  ),
)

// Use the response
println(response)

PHP

use Algolia\AlgoliaSearch\Api\SearchClient;

$client = SearchClient::create('<YOUR_APP_ID>', '<YOUR_API_KEY>');

$response = $client->search(
    ['requests' => [
        ['indexName' => '<YOUR_INDEX_NAME>',
            'query' => '<YOUR_QUERY>',
            'facets' => [
                'author',

                'genre',
            ],
        ],
    ],
    ],
);

// play with the response
var_dump($response);

Python

from algoliasearch.search.client import SearchClient

_client = SearchClient("YOUR_APP_ID", "YOUR_API_KEY")

response = await _client.search(
    search_method_params={
        "requests": [
            {
                "indexName": "<YOUR_INDEX_NAME>",
                "query": "<YOUR_QUERY>",
                "facets": [
                    "author",
                    "genre",
                ],
            },
        ],
    },
)

# use the class directly
print(response)

# print the JSON response
print(response.to_json())

Ruby

require 'algolia'

client = Algolia::SearchClient.create('YOUR_APP_ID', 'YOUR_API_KEY')

response = client.search(
  SearchMethodParams.new(
    requests: [SearchForHits.new(
      index_name: "<YOUR_INDEX_NAME>", query: "<YOUR_QUERY>", facets: ["author", "genre"]
    )]
  )
)

# use the class directly
puts response

# print the JSON response
puts response.to_json

Scala

import algoliasearch.api.SearchClient

val client = SearchClient(appId = "YOUR_APP_ID", apiKey = "YOUR_API_KEY")

val response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = Seq(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = Some("<YOUR_QUERY>"),
        facets = Some(Seq("author", "genre"))
      )
    )
  )
)

// Use the response
val value = Await.result(response, Duration(100, "sec"))

Swift

import Search

let client = try SearchClient(appID: "YOUR_APP_ID", apiKey: "YOUR_API_KEY")

let response: SearchResponses<Hit> = try await client
    .search(searchMethodParams: SearchMethodParams(requests: [SearchQuery.searchForHits(SearchForHits(
        query: "<YOUR_QUERY>",
        facets: ["author", "genre"],
        indexName: "<YOUR_INDEX_NAME>"
    ))]))

To extract all facet information, you can use a wildcard (*).

C#

var response = await client.SearchAsync<Object>(
  new SearchMethodParams
  {
    Requests = new List<SearchQuery>
    {
      new SearchQuery(
        new SearchForHits
        {
          IndexName = "<YOUR_INDEX_NAME>",
          Query = "<YOUR_QUERY>",
          Facets = new List<string> { "*" },
        }
      )
    },
  }
);

Dart

final response = await client.search(
  searchMethodParams: SearchMethodParams(
    requests: [
      SearchForHits(
        indexName: "<YOUR_INDEX_NAME>",
        query: "<YOUR_QUERY>",
        facets: [
          "*",
        ],
      ),
    ],
  ),
);

Go

response, err := client.Search(client.NewApiSearchRequest(

  search.NewEmptySearchMethodParams().SetRequests(
    []search.SearchQuery{*search.SearchForHitsAsSearchQuery(
      search.NewEmptySearchForHits().SetIndexName("<YOUR_INDEX_NAME>").SetQuery("<YOUR_QUERY>").SetFacets(
        []string{"*"}))}),
))
if err != nil {
  // handle the eventual error
  panic(err)
}

// use the model directly
print(response)

Java

client.search(
  new SearchMethodParams()
    .setRequests(List.of(new SearchForHits().setIndexName("<YOUR_INDEX_NAME>").setQuery("<YOUR_QUERY>").setFacets(List.of("*")))),
  Hit.class
);

JavaScript

const response = await client.search({
  requests: [
    { indexName: '<YOUR_INDEX_NAME>', query: '<YOUR_QUERY>', facets: ['*'] },
  ],
});

// use typed response
console.log(response);

Kotlin

var response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = listOf(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = "<YOUR_QUERY>",
        facets = listOf("*"),
      ),
    ),
  ),
)

// Use the response
println(response)

PHP

$response = $client->search(
    ['requests' => [
        ['indexName' => '<YOUR_INDEX_NAME>',
            'query' => '<YOUR_QUERY>',
            'facets' => [
                '*',
            ],
        ],
    ],
    ],
);

// play with the response
var_dump($response);

Python

response = await _client.search(
    search_method_params={
        "requests": [
            {
                "indexName": "<YOUR_INDEX_NAME>",
                "query": "<YOUR_QUERY>",
                "facets": [
                    "*",
                ],
            },
        ],
    },
)

# use the class directly
print(response)

# print the JSON response
print(response.to_json())

Ruby

response = client.search(
  SearchMethodParams.new(
    requests: [SearchForHits.new(
      index_name: "<YOUR_INDEX_NAME>", query: "<YOUR_QUERY>", facets: ["*"]
    )]
  )
)

# use the class directly
puts response

# print the JSON response
puts response.to_json

Scala

val response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = Seq(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = Some("<YOUR_QUERY>"),
        facets = Some(Seq("*"))
      )
    )
  )
)

// Use the response
val value = Await.result(response, Duration(100, "sec"))

Swift

let response: SearchResponses<Hit> = try await client
    .search(searchMethodParams: SearchMethodParams(requests: [SearchQuery.searchForHits(SearchForHits(
        query: "<YOUR_QUERY>",
        facets: ["*"],
        indexName: "<YOUR_INDEX_NAME>"
    ))]))