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 our search and browse engine. Here we’ll guide 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.

​
Foundational Architecture

Attributes form the foundation layer of the Layers platform, enabling all higher-level functionality through their core properties:

​
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. These attributes are created 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.

​
Calculated Attributes

/images/attributes-dashboard-calculated.png Calculated Attributes allow you to write formulas using JSONLogic for creating attributes with dynamic values calculated on the fly. A calculated attribute has access to all Catalog Attributes and the raw underlying data from Shopify prior to transformation and indexing.

​
Automatic Product Recalculation

When you create a new calculated attribute or update an existing calculated attribute’s logic, the system automatically recalculates all products in your catalog in the background. This ensures that your calculated attribute values are immediately applied across your entire product catalog without requiring manual intervention.
Recalculation is triggered only when you create a calculated attribute or modify its logic field. Updates to other fields (like nickname or filterable settings) do not trigger recalculation.

​
Data Access in Calculated Attributes

Calculated attributes can access two types of data:
  • Catalog Attributes: Use _attribute:{attribute_code} to reference existing catalog attributes. For example, _attribute:price_range.from or _attribute:published_at.
  • Raw Data: Use _raw:raw.{path} to access raw underlying Shopify data before transformation. Use dot notation for nested properties. For example, _raw:raw.variants or _raw:raw.featured_media.

​
AI-Powered Calculated Attributes

You can use AI to generate and understand calculated attributes without writing JSONLogic manually:
Generate with AI
The “Generate with AI” feature allows you to describe what you want to calculate in natural language, and the system will automatically generate the JSONLogic expression for you. How to use:
  1. Navigate to Attributes → Create new calculated attribute
  2. Click the Generate with AI button next to “Value Formula”
  3. Enter a natural language description of what you want to calculate (minimum 10 characters)
    • Example: “Calculate the discount percentage from compare_at_price to current price”
    • Example: “Count the total number of variants”
    • Example: “Calculate days since published”
  4. Click Generate to start the AI generation process
  5. Monitor real-time progress updates as the AI generates and validates the expression
  6. Review the generated JSONLogic in the preview
  7. Click Apply to Form to use the generated expression
Generation Process: The AI generation uses a 3-attempt retry mechanism with validation:
  • Attempt 1: Initial generation based on your description
  • Attempts 2-3: If validation fails, the AI receives error feedback and attempts to correct the expression
  • Real-time updates: WebSocket events broadcast progress (generating → retrying → completed/failed)
  • Validation: Each generated expression is validated for correct JSONLogic syntax and proper dependency prefixes
The AI has access to your store’s specific attributes (metafields, named tags, options, variants) and will generate expressions that reference the actual data available in your catalog.
Explain with AI
The “Explain with AI” feature provides human-readable explanations of existing JSONLogic expressions, making it easier to understand what a calculated attribute does. How to use:
  1. Create or edit a calculated attribute with JSONLogic
  2. Scroll to the “What does this formula do?” section below the formula builder
  3. Click Explain with AI
  4. Review the plain-language explanation of your formula
Example explanations:
  • JSONLogic: {"/": [{"-": [{"var": "_attribute:compare_at_price"}, {"var": "_attribute:price"}]}, {"var": "_attribute:compare_at_price"}]}
  • Explanation: “Calculates the discount percentage by comparing the original price to the current selling price. For example, if a product was 100andisnow100 and is now 75, this would return 0.25 (25% off).”
Use “Explain with AI” to document complex formulas or understand calculated attributes created by other team members.

​
Platform Default Calculated Attributes

The following calculated attributes are available by default in the Layers platform:
Description: Ratio between total number of variants and their availability status.
{
  "/": [
    {
      "reduce": [
        {
          "map": [
            { "var": "_raw:raw.variants" },
            { "if": [ { "var": "available" }, 1, 0 ] }
          ]
        },
        { "+": [ { "var": "accumulator" }, { "var": "current" } ] },
        0
      ]
    },
    { "count": { "var": "_raw:raw.variants" } }
  ]
}
Description: The number of days since the product became available, based on the imported Published At for the product. If no available date has been imported, the system uses the date the product was created.
{
  "daysSince": {
    "parseDate": {
      "or": [
        { "var": ["_attribute:published_at", null] },
        { "var": ["_attribute:created_at", null] }
      ]
    }
  }
}
Description: If the product has a featured image.
{
  "!!": {
    "var": "_raw:raw.featured_media"
  }
}
Description: The age of the most recently created variant.
{
  "daysSince": {
    "reduce": [
      {
        "map": [
          {
            "var": "_raw:raw.variants"
          },
          {
            "parseDate": {
              "var": "created_at"
            }
          }
        ]
      },
      {
        "if": [
          {
            "or": [
              {
                "==": [
                  {
                    "var": "accumulator"
                  },
                  null
                ]
              },
              {
                ">": [
                  {
                    "var": "current"
                  },
                  {
                    "var": "accumulator"
                  }
                ]
              }
            ]
          },
          {
            "var": "current"
          },
          {
            "var": "accumulator"
          }
        ]
      },
      null
    ]
  }
}
Description: If price_range.from != price_range.to.
{
  "!==": [
    {
      "var": "_attribute:price_range.from"
    },
    {
      "var": "_attribute:price_range.to"
    }
  ]
}
For a comprehensive guide to JSONLogic operators and how to write calculated attribute formulas, see JSONLogic Operators.

​
Additional Calculated Attribute Recipes

Beyond the platform defaults, you can create custom calculated attributes for specific business needs:
Description: The percentage discount calculated from compare_at_price to current price. Returns 0 if no discount is available.Use Case: Sort products by discount amount or filter for products on sale. Create “Biggest Discounts” collections or exclude heavily discounted items from premium merchandising.
{
  "if": [
    {
      "and": [
        { "var": "_attribute:price_range.to" },
        {
          ">": [
            { "var": "_attribute:price_range.to" },
            { "var": "_attribute:price_range.from" }
          ]
        }
      ]
    },
    {
      "*": [
        {
          "/": [
            {
              "-": [
                { "var": "_attribute:price_range.to" },
                { "var": "_attribute:price_range.from" }
              ]
            },
            { "var": "_attribute:price_range.to" }
          ]
        },
        100
      ]
    },
    0
  ]
}
Attributes: Filterable, Sortable | Value Type: Number (percentage)Example: A product with compare_at_price of 100andcurrentpriceof100 and current price of 75 has a discount percentage of 25.
Description: The total number of variants for this product. Useful for filtering or sorting by product complexity.Use Case: Identify products with many options (high variant count) or single-variant products. Filter out products with too many variants from certain collections.
{
  "count": [{ "var": "_raw:raw.variants" }]
}
Attributes: Filterable, Sortable | Value Type: Number (count)Example: A t-shirt available in 5 colors and 4 sizes (20 combinations) has a variant count of 20.
Description: Average profit margin across variants, calculated as (price - cost) / price for each variant with cost data. Returns null if no variants have cost information.Use Case: Sort products by profitability or filter for high-margin items. Create “Best Margin” collections for merchandising or exclude low-margin products from promotional campaigns.
{
  "if": [
    [
      {
        ">": [
          {
            "reduce": [
              {
                "map": [
                  { "var": "_raw:raw.variants" },
                  {
                    "if": [
                      {
                        "and": [
                          { "!=": [{ "var": "cost" }, null] },
                          { ">": [{ "var": "price" }, 0] }
                        ]
                      },
                      1,
                      0
                    ]
                  }
                ]
              },
              {
                "+": [
                  { "var": "accumulator" },
                  { "var": "current" }
                ]
              },
              0
            ]
          },
          0
        ]
      }
    ],
    {
      "/": [
        {
          "reduce": [
            {
              "map": [
                { "var": "_raw:raw.variants" },
                {
                  "if": [
                    {
                      "and": [
                        { "!=": [{ "var": "cost" }, null] },
                        { ">": [{ "var": "price" }, 0] }
                      ]
                    },
                    {
                      "/": [
                        {
                          "-": [
                            { "var": "price" },
                            { "var": "cost" }
                          ]
                        },
                        { "var": "price" }
                      ]
                    },
                    0
                  ]
                }
              ]
            },
            {
              "+": [
                { "var": "accumulator" },
                { "var": "current" }
              ]
            },
            0
          ]
        },
        {
          "reduce": [
            {
              "map": [
                { "var": "_raw:raw.variants" },
                {
                  "if": [
                    {
                      "and": [
                        { "!=": [{ "var": "cost" }, null] },
                        { ">": [{ "var": "price" }, 0] }
                      ]
                    },
                    1,
                    0
                  ]
                }
              ]
            },
            {
              "+": [
                { "var": "accumulator" },
                { "var": "current" }
              ]
            },
            0
          ]
        }
      ]
    },
    null
  ]
}
Attributes: Filterable, Sortable | Value Type: Number (decimal)Example: A product with two variants (price=10,cost=10, cost=5 and price=20,cost=20, cost=10) has an average margin of 0.5 (50%).

​
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 users 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