Why searchable attributes matter
searchableAttributes determines which indexed product fields Algolia examines when a shopper enters a query. In a WooCommerce store, this setting has a direct effect on whether customers find the right product quickly—or receive results dominated by irrelevant descriptions, internal data, or low-value matches.
This is not a list of fields that should merely exist in your product records. It is a deliberate ranking strategy. The order of the attributes determines which matches are considered more important when Algolia ranks results.
For example, a search for blue running shoes should normally prioritize:
- A product title containing the phrase
- A brand or product type match
- A category match
- Relevant descriptive copy
- Supporting fields such as SKU or model number
A practical WooCommerce configuration
Assume each indexed product contains fields such as:
{
"name": "Blue Trail Running Shoes",
"sku": "TRAIL-BLU-42",
"brand": "Example Athletics",
"categories": ["Running Shoes", "Footwear"],
"short_description": "Lightweight shoes for trail running.",
"description": "Technical details, materials, care instructions, and sizing information.",
"search_keywords": ["outdoor running", "grip", "hiking"]
}A sensible starting configuration might be:
[
"name",
"brand",
"categories",
"sku",
"search_keywords",
"unordered(short_description)",
"unordered(description)"
]This configuration gives the product name the highest priority, followed by structured commercial data. Longer text remains searchable without allowing word position in a large description to overpower a strong title match.
The exact field names must match the attributes in your Algolia records. If your index uses post_title instead of name, configure post_title. Algolia does not infer that a WooCommerce field should be searchable based on its WordPress or WooCommerce meaning.
Ordered and unordered searchable attributes
By default, attributes in searchableAttributes are ordered. Algolia considers an earlier attribute more important than a later one. Within an attribute, word position can also influence ranking.
You can use the unordered() modifier when the order of matching words inside a field should not matter as much:
[
"name",
"brand",
"unordered(categories)",
"unordered(description)"
]Use ordered attributes for fields where placement is meaningful, such as product names. Use unordered attributes for descriptions, keyword collections, and other content where a match anywhere in the field is acceptable.
Do not mark every attribute as unordered automatically. Removing useful positional relevance from product names can make titles such as Men's Waterproof Jacket compete poorly against less precise text matches.
Choosing fields for WooCommerce search
Product title
The product title should almost always be the first searchable attribute. It contains the clearest signal of what the product is and usually matches the language shoppers use.
Keep titles customer-facing. Avoid adding long lists of synonyms, internal codes, or promotional text solely to influence search. If additional terms are genuinely useful, store them in a dedicated field such as search_keywords.
SKU and model number
SKU and model fields are important for repeat customers, trade buyers, and support teams. They are especially useful when a shopper searches for an exact identifier.
Place them after the title and other primary descriptive fields so an incidental match in an SKU does not outrank a product whose name matches the query. If exact SKU lookup is a major use case, test searches for complete and partial codes separately.
Brand, categories, and product attributes
Brand and category values are usually strong searchable fields because they are structured and consistent. Depending on the catalogue, you may also index values such as:
- Product type
- Material
- Compatibility
- Collection
- Gender
- Size or model family
Searchability does not make a field filterable. If shoppers must refine results by brand, size, colour, or another facet, configure the field separately in attributesForFaceting.
For example:
{
"searchableAttributes": [
"name",
"brand",
"categories",
"sku",
"unordered(description)"
],
"attributesForFaceting": [
"brand",
"categories",
"color",
"size"
]
}A field can be both searchable and facetable, but the two settings serve different purposes.
Descriptions and custom keywords
Descriptions can help with broad or technical searches, but they often contain boilerplate, delivery information, care instructions, and marketing language. Put them lower in the searchable attribute order and consider using unordered().
A dedicated search_keywords field is often more maintainable than duplicating synonyms throughout product descriptions. For example, a merchant selling trainers might add terms such as sneakers, gym shoes, or road running when those terms accurately describe the product and reflect real customer searches.
Avoid indexing the wrong content
Do not add every field from a WordPress product record to searchableAttributes. Commonly excluded fields include:
- Internal notes
- Supplier names that customers do not use
- Administrative status values
- Warehouse locations
- Raw HTML
- Duplicate concatenations of the same content
- Hidden metadata used only by plugins
Indexing these values can produce confusing matches and make relevance difficult to explain to merchants. It can also increase index size and make future catalogue changes harder to manage.
If a value is needed for filtering, sorting, display, or analytics but should not match free-text queries, keep it out of searchableAttributes and configure it for its specific purpose instead.
Configure the setting in the correct index
Algolia settings belong to an index. In a WooCommerce implementation, you may have separate indices for products, suggestions, staging data, or different regions and languages. Apply the searchable attribute configuration to the index used by the live frontend search experience.
A common deployment pattern is:
- Update the settings in a staging index.
- Reindex representative products.
- Test high-value queries and edge cases.
- Promote or replicate the validated configuration to production.
When using the Algolia API, the setting can be applied with an index client. The exact client syntax depends on the Algolia SDK version, but the setting itself follows this structure:
{
"searchableAttributes": [
"name",
"brand",
"categories",
"sku",
"search_keywords",
"unordered(description)"
]
}Changing searchable attributes affects how existing records are searched; it does not add missing fields to records. If the required attribute is not present in the indexed WooCommerce object, update the indexing process and reindex the catalogue.
Test with real WooCommerce queries
Use real search logs, customer-service tickets, and merchant feedback when evaluating the configuration. A useful test set should include:
- Exact product names
- Partial product names
- SKUs and model numbers
- Brand plus product type
- Category terms
- Common synonyms and spelling mistakes
- Queries containing colour, size, or compatibility terms
- Searches with no exact product match
For every query, inspect whether the top results are commercially appropriate, not merely whether the query returns hits. For example, a search for oak dining table should not place a product with the words oak care instructions in its description above actual oak tables.
Use the Algolia dashboard or API response data to compare ranking changes after each adjustment. Change one part of the configuration at a time so the effect of attribute order is measurable.
Common configuration mistakes
Putting descriptions first
This causes generic marketing copy to compete with product names and structured catalogue data. Keep descriptions later unless the business genuinely relies on content-led discovery.
Treating searchable attributes as facets
Adding brand to searchableAttributes allows text matches; it does not create a brand filter. Configure faceting separately.
Adding duplicate fields
Indexing the same title in several attributes can artificially increase its influence and make ranking unpredictable. Keep one authoritative field for each concept.
Forgetting to reindex
If the indexing pipeline does not send brand, categories, or search_keywords, adding those names to the settings will not make them searchable. Verify the actual Algolia record before diagnosing the settings.
Using internal field names inconsistently
A WordPress meta key, a WooCommerce REST field, and an Algolia record attribute may have different names. Document the mapping and use the Algolia record name in the setting.
Expecting searchable attributes to solve every relevance issue
Searchable attributes establish the fields Algolia searches and their relative priority. Other controls—including custom ranking, business rules, synonyms, filters, and query strategy—may still be required. Change those only after confirming that the correct product data is present and the searchable attribute order is sound.