> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to declare attributes for faceting with the API

> How to declare attributes for faceting with the API.

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

export const serviceLimits = {
  application: {
    applicationSize: "100 GB (or 1 GB for the Free plan)",
    indexSize: "100 GB (or 1 GB for the Free plan)",
    indexingOperations: "Depends on your plan and usage.",
    indexingRate: "10,000 indexing operations per Unit (as applicable)",
    indexingRequestBodySize: "1 GB per batch",
    indicesPerApplication: "1,000 (Premium), 50 (Grow), or 10 (Free)",
    customNormalizations: "10",
    pendingRequests: "5,000",
    recordSize: "10 KB to 100 KB—based on your plan (10 KB maximum for the Free plan)",
    searchRequestBodySize: "50 MB per request",
    sortCriterionLength: "First 50 bytes (50 characters for ASCII text)",
    synonymsPerIndex: "10,000 (or 1,000 for the Free plan)",
    throttlingLimit: "100 pending requests",
    virtualReplicasPerIndex: "20"
  },
  filtersFacetsRules: {
    conditionsPerRule: "25",
    filterScore: "65,535",
    maxRatioFacetValuePairs: "0.1",
    numberOfFilters: "1,000",
    promotedItemsPerGroup: "100",
    promotedItemsPerRule: "300",
    ruleConsequenceSize: "100 KiB",
    queryParameterSize: "16 KiB",
    valuesPerFacetPerQuery: "1,000",
    reorderedFacetsPerQuery: "20",
    reorderedFacetValuesPerQuery: "20",
    precomputedFacetOrderingQueries: "100,000"
  },
  searchUI: {
    pagination: "20,000",
    querySuggestions: "100",
    querySize: "512 bytes"
  },
  insightsAnalytics: {
    analyticsApiCalls: "100 API calls per minute per app",
    tagSize: "100 characters",
    tagsProcessedPerIndex: "1,750 unique tag combinations every 5 minutes",
    topSearches: "1,000"
  },
  security: {
    apiKeys: "5,000"
  },
  connectors: {
    authenticationsPerApp: "200",
    sourcesPerApp: "100",
    destinationsPerApp: "500",
    tasksPerSource: "10",
    pushPayloadSize: "5 MB per API call",
    pushWatchDuration: "3 minutes",
    jsonFileSize: "1 GB",
    jsonFileRows: "1,000,000",
    csvFileSize: "1 GB",
    csvFileRows: "1,000,000",
    pushEndpointRate: "2000 calls per minute per IP",
    observabilityRate: "2000 calls per minute per IP",
    runTaskRate: "10 calls per 10 minute per taskID",
    otherEndpointsRate: "200 calls per minute per IP"
  },
  dataTransformation: {
    codeSize: "32 kB",
    runtime: "1 second per transformation",
    memory: "100 kB per request",
    transformationsPerApplication: "5 million per month",
    fetchEnrichmentRequests: "Up to 1 million Fetch requests per Application per month, as part the 5 million transformations per Application per month limit.",
    fetchTimeout: "30 seconds per Record",
    fetchResponseSize: "128 kB"
  },
  collections: {
    collectionsPerIndex: "500 (Premium plan) or 1,000 (Elevate plan)",
    conditionsPerCollection: "50",
    manuallySelectedItemsPerCollection: "10,000",
    objectIdSize: "200 characters"
  },
  smartGroups: {
    groupsPerCuratedQuery: "3",
    recordsPerGroup: "50",
    highestStartPosition: "100",
    compositionsPerApplication: "100",
    compositionRulesPerComposition: "200",
    disjunctiveFacetsPerRequest: "20",
    hitsPerPage: "1000"
  },
  docSearch: {
    applicationSize: "25 GB",
    indexSize: "25 GB",
    recordSize: "100 kB",
    indicesPerApplication: "20",
    queriesPerSecond: "3",
    teamMembers: "10"
  },
  generativeGuides: {
    guidesPerIndex: "1,000",
    sizePerGuide: "100 kB",
    inputTokensPerGeneration: "50,000",
    outputTokensPerGeneration: "2,000"
  },
  agentStudio: {
    conversationsRetained: "100,000",
    completionsPerMinute: "3,000",
    retentionPolicy: "90 days",
    agentsPerApp: "500"
  },
  aiAssist: {
    combinedTokensPerAppPerDay: "25 million"
  }
};

Algolia lets you create categories based on specific attributes so users can filter search results by those categories.
For example, if you have an <Index /> of books, you could categorize them by author and genre.
This allows users to filter search results by their favorite author or discover new genres.

To run the code examples on this page, [install the latest API client](/doc/libraries/sdk/install).

To enable this categorization,
declare the attributes `genre` and `author` as [`attributesForFaceting`](/doc/api-reference/api-parameters/attributesForFaceting):

<CodeGroup>
  ```cs C# theme={"system"}
  var response = await client.SetSettingsAsync(
    "INDEX_NAME",
    new IndexSettings
    {
      AttributesForFaceting = new List<string> { "genre", "author" },
    }
  );
  ```

  ```dart Dart theme={"system"}
  final response = await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(
      attributesForFaceting: [
        "genre",
        "author",
      ],
    ),
  );
  ```

  ```go Go theme={"system"}
  response, err := client.SetSettings(client.NewApiSetSettingsRequest(
    "INDEX_NAME",
    search.NewEmptyIndexSettings().SetAttributesForFaceting(
      []string{"genre", "author"})))
  if err != nil {
    // handle the eventual error
    panic(err)
  }
  ```

  ```java Java theme={"system"}
  UpdatedAtResponse response = client.setSettings(
    "INDEX_NAME",
    new IndexSettings().setAttributesForFaceting(Arrays.asList("genre", "author"))
  );
  ```

  ```js JavaScript theme={"system"}
  const response = await client.setSettings({
    indexName: 'INDEX_NAME',
    indexSettings: { attributesForFaceting: ['genre', 'author'] },
  });
  ```

  ```kotlin Kotlin theme={"system"}
  var response =
    client.setSettings(
      indexName = "INDEX_NAME",
      indexSettings = IndexSettings(attributesForFaceting = listOf("genre", "author")),
    )
  ```

  ```php PHP theme={"system"}
  $response = $client->setSettings(
      'INDEX_NAME',
      ['attributesForFaceting' => [
          'genre',

          'author',
      ],
      ],
  );
  ```

  ```python Python theme={"system"}
  response = client.set_settings(
      index_name="INDEX_NAME",
      index_settings={
          "attributesForFaceting": [
              "genre",
              "author",
          ],
      },
  )
  ```

  ```ruby Ruby theme={"system"}
  response = client.set_settings(
    "INDEX_NAME",
    Algolia::Search::IndexSettings.new(attributes_for_faceting: ["genre", "author"])
  )
  ```

  ```scala Scala theme={"system"}
  val response = Await.result(
    client.setSettings(
      indexName = "INDEX_NAME",
      indexSettings = IndexSettings(
        attributesForFaceting = Some(Seq("genre", "author"))
      )
    ),
    Duration(100, "sec")
  )
  ```

  ```swift Swift theme={"system"}
  let response = try await client.setSettings(
      indexName: "INDEX_NAME",
      indexSettings: IndexSettings(attributesForFaceting: ["genre", "author"])
  )
  ```
</CodeGroup>

Sometimes, you may have many facet values.
For instance, if you have a book index, you may also have a lot of different authors.
[The engine can't return more than {serviceLimits.filtersFacetsRules.valuesPerFacetPerQuery} values per facet](/doc/api-reference/api-parameters/maxValuesPerFacet),
so if you have more than that, you may want to let your users search for them.
Do this by using the `searchable` modifier.

<CodeGroup>
  ```cs C# theme={"system"}
  var response = await client.SetSettingsAsync(
    "INDEX_NAME",
    new IndexSettings
    {
      AttributesForFaceting = new List<string> { "genre", "searchable(author)" },
    }
  );
  ```

  ```dart Dart theme={"system"}
  final response = await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(
      attributesForFaceting: [
        "genre",
        "searchable(author)",
      ],
    ),
  );
  ```

  ```go Go theme={"system"}
  response, err := client.SetSettings(client.NewApiSetSettingsRequest(
    "INDEX_NAME",
    search.NewEmptyIndexSettings().SetAttributesForFaceting(
      []string{"genre", "searchable(author)"})))
  if err != nil {
    // handle the eventual error
    panic(err)
  }
  ```

  ```java Java theme={"system"}
  UpdatedAtResponse response = client.setSettings(
    "INDEX_NAME",
    new IndexSettings().setAttributesForFaceting(Arrays.asList("genre", "searchable(author)"))
  );
  ```

  ```js JavaScript theme={"system"}
  const response = await client.setSettings({
    indexName: 'INDEX_NAME',
    indexSettings: { attributesForFaceting: ['genre', 'searchable(author)'] },
  });
  ```

  ```kotlin Kotlin theme={"system"}
  var response =
    client.setSettings(
      indexName = "INDEX_NAME",
      indexSettings = IndexSettings(attributesForFaceting = listOf("genre", "searchable(author)")),
    )
  ```

  ```php PHP theme={"system"}
  $response = $client->setSettings(
      'INDEX_NAME',
      ['attributesForFaceting' => [
          'genre',

          'searchable(author)',
      ],
      ],
  );
  ```

  ```python Python theme={"system"}
  response = client.set_settings(
      index_name="INDEX_NAME",
      index_settings={
          "attributesForFaceting": [
              "genre",
              "searchable(author)",
          ],
      },
  )
  ```

  ```ruby Ruby theme={"system"}
  response = client.set_settings(
    "INDEX_NAME",
    Algolia::Search::IndexSettings.new(attributes_for_faceting: ["genre", "searchable(author)"])
  )
  ```

  ```scala Scala theme={"system"}
  val response = Await.result(
    client.setSettings(
      indexName = "INDEX_NAME",
      indexSettings = IndexSettings(
        attributesForFaceting = Some(Seq("genre", "searchable(author)"))
      )
    ),
    Duration(100, "sec")
  )
  ```

  ```swift Swift theme={"system"}
  let response = try await client.setSettings(
      indexName: "INDEX_NAME",
      indexSettings: IndexSettings(attributesForFaceting: ["genre", "searchable(author)"])
  )
  ```
</CodeGroup>

If you only need the filtering feature, use `filterOnly` to reduce the index size and improve search speed.
For example, you could automatically filter what genre the users can search based on the section of your website they're on (without displaying genre as a clickable filter).

<CodeGroup>
  ```cs C# theme={"system"}
  var response = await client.SetSettingsAsync(
    "INDEX_NAME",
    new IndexSettings
    {
      AttributesForFaceting = new List<string> { "filterOnly(genre)", "author" },
    }
  );
  ```

  ```dart Dart theme={"system"}
  final response = await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(
      attributesForFaceting: [
        "filterOnly(genre)",
        "author",
      ],
    ),
  );
  ```

  ```go Go theme={"system"}
  response, err := client.SetSettings(client.NewApiSetSettingsRequest(
    "INDEX_NAME",
    search.NewEmptyIndexSettings().SetAttributesForFaceting(
      []string{"filterOnly(genre)", "author"})))
  if err != nil {
    // handle the eventual error
    panic(err)
  }
  ```

  ```java Java theme={"system"}
  UpdatedAtResponse response = client.setSettings(
    "INDEX_NAME",
    new IndexSettings().setAttributesForFaceting(Arrays.asList("filterOnly(genre)", "author"))
  );
  ```

  ```js JavaScript theme={"system"}
  const response = await client.setSettings({
    indexName: 'INDEX_NAME',
    indexSettings: { attributesForFaceting: ['filterOnly(genre)', 'author'] },
  });
  ```

  ```kotlin Kotlin theme={"system"}
  var response =
    client.setSettings(
      indexName = "INDEX_NAME",
      indexSettings = IndexSettings(attributesForFaceting = listOf("filterOnly(genre)", "author")),
    )
  ```

  ```php PHP theme={"system"}
  $response = $client->setSettings(
      'INDEX_NAME',
      ['attributesForFaceting' => [
          'filterOnly(genre)',

          'author',
      ],
      ],
  );
  ```

  ```python Python theme={"system"}
  response = client.set_settings(
      index_name="INDEX_NAME",
      index_settings={
          "attributesForFaceting": [
              "filterOnly(genre)",
              "author",
          ],
      },
  )
  ```

  ```ruby Ruby theme={"system"}
  response = client.set_settings(
    "INDEX_NAME",
    Algolia::Search::IndexSettings.new(attributes_for_faceting: ["filterOnly(genre)", "author"])
  )
  ```

  ```scala Scala theme={"system"}
  val response = Await.result(
    client.setSettings(
      indexName = "INDEX_NAME",
      indexSettings = IndexSettings(
        attributesForFaceting = Some(Seq("filterOnly(genre)", "author"))
      )
    ),
    Duration(100, "sec")
  )
  ```

  ```swift Swift theme={"system"}
  let response = try await client.setSettings(
      indexName: "INDEX_NAME",
      indexSettings: IndexSettings(attributesForFaceting: ["filterOnly(genre)", "author"])
  )
  ```
</CodeGroup>

**Don't include colons (`:`) in attribute names that you want to use for faceting because the [`filters`](/doc/api-reference/api-parameters/filters) syntax relies on that character as a delimiter.**

## See also

* [How to declare attributes for faceting in the dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard)
* [Auto-selected facets](/doc/guides/solutions/ecommerce/filtering-and-navigation/tutorials/auto-selected-facets)
* [Guided search](/doc/guides/solutions/ecommerce/filtering-and-navigation/tutorials/guided-search)
* [Visual facets](/doc/guides/solutions/ecommerce/filtering-and-navigation/tutorials/visual-facets)