Skip to main content
Managing catalog attributes effectively is crucial for a robust e-commerce search and filtering experience. On the Attributes page of the dashboard, you have control over the attributes that are indexed and utilized by the search and browse engine. This guide walks you through each attribute type and how to optimize them for your product listings.
Attributes for Product Options, Shopify’s Standard Product Taxonomy Metafields, and Product Metrics are automatically created during catalog syncs. Please contact support if you need assistance managing complex attributes.

​
Finding attributes

The Attributes page displays all indexed attributes in a table with the following columns:
  • Name — the human-readable nickname for the attribute
  • Code — the underlying attribute code used by the engine
  • Type — either Catalog or Calculated
  • Used In — badges showing where the attribute is active (Filter, Sort, Search, Keyword, Grouping)
Use the search bar at the top to find attributes by name, code, or label. You can also filter the list using the Type and Used In dropdowns:
  • Type — narrow the list to Catalog attributes (sourced from your product data) or Calculated attributes (derived from formulas).
  • Used In — show only attributes that are active in a specific role: Filter, Sort, Search (semantic), Keyword, or Grouping. Select multiple values to broaden the filter (OR logic).
The Keyword option in the Used In filter shows attributes that have a keyword search weight configured. Use this to quickly review which attributes contribute to keyword-based text matching.

​
Foundational architecture

Attributes form the foundation layer of the Layers platform, enabling all higher-level functionality through their core properties. For a visual overview of how attributes connect to search, filtering, and sorting, see Attributes — Core Concepts.

​
Attribute types

​
Catalog attributes

The code corresponds to your product schema using Dot Notation, which allows for the targeting of attributes or nested attributes within your data structure. Example of Dot Notation for a product attribute: 
{
  "metafields": {
    "custom": {
      "material": "Cotton"
    }
  }
}
In this case, the attribute code would be metafields.custom.material.

​
Nested metafield object keys

When metafield values are JSON objects, you can create attribute codes that access nested object keys. The namespace and key portions must be alphanumeric with underscores, but object keys can contain spaces and special characters. Attribute code format: metafields.{namespace}.{key}.{object_key} Example: 
{
  "metafields": {
    "custom": {
      "color_family": {
        "dark orange": "orange",
        "light blue": "blue"
      }
    }
  }
}
Valid attribute codes:
  • metafields.custom.color_family.dark orange → accesses the value "orange"
  • metafields.custom.color_family.light blue → accesses the value "blue"
Use cases:
  • Create filterable attributes for nested metafield values to enable faceted navigation
  • Sort products by nested metafield object values
  • Use nested values in merchandising rules and collection filters
This syntax works for both metafields and variant_metafields. Example: variant_metafields.custom.dimensions.width cm

​
Automatic metafield attribute creation

When your catalog is synced, the system automatically creates attributes for metafields that exist on your products but don’t have formal metafield definitions in Shopify. The system creates these attributes with conservative defaults (all search/filter settings disabled) to ensure they don’t affect your search experience until you explicitly configure them. Default settings for auto-created metafield attributes:
  • Searchable: Disabled
  • Filterable: Disabled
  • Sortable: Disabled
  • Partial Matching: Disabled
You can review and configure these attributes on the Attributes page after they’re created. This ensures that all product data is available for configuration, even if metafield definitions haven’t been set up in Shopify.

​
Creating attributes from metafields

You can create catalog attributes directly from your Shopify metafield definitions on the Metafields & Metaobjects settings page. This is useful when you want to quickly make specific metafields available for search, filtering, or sorting without manually entering attribute codes. How to create a single attribute:
1

Go to the metafields page

Go to Settings → Metafields & Metaobjects in the dashboard.
2

Select the metafield tab

Choose either the Product Metafields or Variant Metafields tab depending on where the metafield is defined.
3

Find the metafield

Locate the metafield you want to create an attribute for. The Attribute column shows whether an attribute already exists for each metafield.
4

Click Create

Click the Create button next to any metafield that does not yet have an attribute. The attribute is created immediately with the correct code and a default nickname derived from the metafield name.
How to create attributes in bulk:
1

Select metafields

Use the checkboxes on the left side of the table to select multiple metafields. You can also use the header checkbox to select all visible metafields at once.
2

Click Create Attributes

Click the Create Attributes button that appears in the top-right corner. The count shown on the button reflects only the selected metafields that do not already have attributes.
Newly created attributes use conservative defaults — searchable, filterable, and sortable are all disabled. After creation, navigate to the Attributes page to configure each attribute’s settings for your use case.
You can create up to 100 attributes at a time using bulk creation. Metafields that already have a matching attribute are automatically skipped.

​
Calculated attributes

Calculated Attributes allow you to write formulas using JSONLogic for creating attributes with dynamic values calculated on the fly. See the dedicated Calculated Attributes page for full details on the Derive builder, AI-powered generation, platform defaults, and recipes.

​
Customer-facing label

Each attribute has an optional Label field that represents the customer-facing name displayed on your storefront. While the attribute code (e.g., metafields.custom.material) is used internally by the engine, the label provides a human-readable name (e.g., “Material”) for use in storefront UI elements like filter menus and facet headings. You can set or update the label when creating or editing an attribute on the Attributes page of the dashboard.
The attribute search bar on the Attributes page matches against the attribute code, nickname, and label. If you assign meaningful labels to your attributes, you can quickly locate them by searching for the customer-facing name instead of remembering the underlying code.

​
Attribute options

​
Searchable attributes

By marking an attribute as Searchable, your products can be found in search results if the search query matches the attribute’s value. This is ideal for text-based attributes such as product names, descriptions, or categories. Attributes that are marked as Searchable and contain an Image URL will automatically be used for Image Search.

​
Partial matching

The “Allow Partial Matching” option determines whether a product can match search queries that only partially match the attribute’s value. For instance, if you want customers to find a product by typing just a part of the SKU or Style Code, enable this option. If exact matches are preferred, such as for specific codes, you can disable this option.

​
Keyword search weight

The Keyword Search Weight option allows you to control how much influence a searchable attribute has on keyword-based search ranking. When set, the attribute is included as a keyword field in the search ranking model, and its weight determines how much it contributes relative to other keyword fields.
  • What it does: Assigns a weight to the attribute for keyword matching techniques (full-text search, word similarity, and trigram matching). The weight is proportionally distributed across all keyword-enabled attributes.
  • When to use: When you want to prioritize certain attributes over others in keyword search. For example, giving title a higher weight than body_html ensures that title matches rank higher.
  • How it works: The total keyword weight budget from the ranking model is distributed proportionally across all attributes with a keyword search weight. Each field’s share is further split across three matching techniques (full-text ranking, word similarity, and trigram matching) using a fixed profile ratio.
Keyword Search Weight is only available for attributes that are marked as Searchable. The weight value is a relative number — what matters is the ratio between keyword-enabled attributes, not the absolute value. For example, giving title a weight of 2.0 and vendor a weight of 1.0 means title matches count twice as much as vendor matches.

​
Filterable attributes

Setting an attribute as Filterable enables it to be used as a facet on category or search result pages. This allows customers to refine their searches based on specific product characteristics like size, color, or brand. Learn more in Filters / Facets.

​
Sortable attributes

Sortable attributes can be used to create custom Sort Orders for your product catalog. This is useful for allowing customers to sort products according to different criteria, such as price, popularity, or relevance.
You cannot disable sorting on an attribute that is currently used in a sort order. To disable sorting, first remove the attribute from all sort orders that reference it.

​
Groupable attributes

Use a groupable attribute to group results and/or metrics by a shared value instead of by individual product IDs—for example, by a style code across variants or related products.
  • What it does: Treat all products with the same group value as one group (e.g., group by style_code) for ranking and reporting.
  • When to use: When you want to rank or measure product families together (styles, sets, or kits).
  • Where to enable: Edit an attribute and toggle “Groupable.”
  • Works with: Metrics and Sort Orders.
Example: If multiple products share the same style_code, enabling Groupable on style_code lets you view metrics and apply sorting at the style level.

​
Visible in API responses

The Visible in API Responses option controls whether an attribute can be used in storefront API requests. When set to false, the attribute becomes internal-only and is excluded from customer-facing operations. What it does:
  • Prevents the attribute from being used in request-level filters
  • Blocks the attribute from being requested in the attributes parameter
  • Excludes the attribute from API responses
  • Filters nested properties from JSON response data (e.g., if a nested property is marked as non-visible, it will be stripped from the parent object in responses)
When to use it:
  • For internal-only attributes like calculated fields used for merchandising rules
  • For sensitive data that should not be exposed to the storefront
Default behavior:
  • All attributes default to visible in API responses
  • Calculated attributes automatically default to not visible in API responses
Nested property filtering: When an attribute with nested properties (like calculated.revenue.total) is marked as non-visible, the system recursively filters those properties from JSON objects in API responses. For example, if you have calculated.a (visible) and calculated.b (non-visible), requesting the calculated attribute will return only the a property in the response object.
Attributes marked as non-visible in API responses can still be used internally for merchandising rules, sort orders, and dashboard analytics. They are only hidden from customer-facing API requests.

​
Enable as storefront facet

The Enable as Storefront Facet option controls whether a filterable attribute is synced to Shopify as a metaobject for use in storefront filtering. This setting is independent of the Visible in API Responses option and only applies to attributes marked as Filterable. What it does:
  • When enabled, creates and syncs a metaobject in Shopify for the filterable attribute
  • When disabled, deletes the metaobject from Shopify (if it exists)
  • Controls whether the attribute can be used for native Shopify storefront filtering
When to use it:
  • Enable for filterable attributes that should be available for Shopify storefront filtering
  • Disable for filterable attributes that are only used internally or through the Layers API
Default behavior:
  • All filterable attributes default to enabled as storefront facets
  • Non-filterable attributes cannot be enabled as storefront facets
How it works with other settings: The two visibility options work independently:
  • Visible in API Responses: Controls whether the attribute appears in Layers API responses
  • Enable as Storefront Facet: Controls whether the attribute is synced to Shopify metaobjects
For example, you might have an attribute that is:
  • Visible in API responses but not enabled as a storefront facet (available through Layers API only)
  • Enabled as a storefront facet but not visible in API responses (available for Shopify filtering only)
  • Both enabled (available through both Layers API and Shopify filtering)
Metaobject sync only occurs for attributes marked as Filterable. The Enable as Storefront Facet toggle only appears for filterable attributes. Learn more about metaobject syncing in Metaobjects & Metafields.

​
Attribute classes

Attribute classes provide additional metadata that helps the search engine understand how to process and optimize searches involving specific attributes. When you assign a class to an attribute, the engine can apply specialized handling that improves relevance and performance.

​
Categorical attributes

Categorical attributes represent discrete values that products can be grouped by, such as brand, color, material, or product type. The engine uses this classification to optimize faceted navigation and to understand when customers are filtering by category versus searching for specific terms.

​
Feature attributes

Feature attributes describe product characteristics that customers might search for or filter by, such as size, weight, or technical specifications. The engine treats these differently from categorical attributes, applying appropriate matching logic for feature-based queries.

​
Price attributes

Price attributes are specifically designated for monetary values. This classification enables the engine to apply price-specific optimizations, including range-based filtering, price sensitivity detection in user intent processing, and appropriate sorting behaviors for price-related queries.
Assigning the correct class to your attributes helps the search engine deliver more relevant results by understanding the semantic meaning of each attribute in your catalog.

​
Best practices

  • Use clear, descriptive nicknames for attributes to easily manage and identify them on the dashboard.
  • When setting up searchable attributes, consider the search behavior of your customers and which attributes are most relevant to their queries.
  • For filterable attributes, think about the facets that are most useful for customers when browsing your product range.
  • Regularly review and update your attributes to keep up with changes in your product catalog and customer search behavior.
By following these guidelines, you can ensure that your product attributes are optimized for search and filtering, creating a better shopping experience for your customers.

​
See also