Atributos de produto no Magento 2: boas práticas para um catálogo limpo

Atributos de produto parecem campos de formulário simples, mas cada decisão sobre eles afeta indexação, busca, navegação em camadas, importações e velocidade de página. Um catálogo com trezentos atributos, metade deles pesquisáveis e um terço com scope de store view, fica mais lento e mais difícil de manter do que precisa. Estas são as regras que sigo ao projetar ou limpar atributos no Magento Open Source e no Adobe Commerce 2.4.8.

Como os atributos são armazenados

Os produtos usam o modelo EAV. As definições de atributos ficam em eav_attribute, com propriedades específicas do catálogo em catalog_eav_attribute. Os valores são guardados em uma tabela por backend type: catalog_product_entity_varchar, _int, _decimal, _text e _datetime. Cada linha de valor tem o ID do atributo, o ID da store e o entity ID do produto, ou o row ID no Adobe Commerce.

Atributos dropdown e multi select guardam IDs de opção, com os labels em eav_attribute_option_value por store. É por isso que um dropdown com opções consistentes é melhor para filtro do que texto livre: o valor é um inteiro que indexa e agrega de forma limpa.

Escolha o input type certo

Necessidade	Input type	Backend type
Lista fixa, usada para filtro	Dropdown ou swatch visual/de texto	int
Vários valores de uma lista	Multiple Select	varchar
Flag sim ou não	Yes/No	int
Texto livre curto	Text Field	varchar
Texto longo ou HTML	Text Area ou Page Builder	text
Números para comparação ou ordenação	Text Field com validação decimal, ou Price	decimal
Datas	Date	datetime

O erro mais comum é usar um campo de texto para algo que na verdade é uma lista, como material ou marca. Texto livre acaba com "Algodão", "algodão" e "100% algodão" como valores separados, e nenhum deles serve como filtro limpo. Mudar o input type depois significa migrar dados entre tabelas de valores, então escolha com cuidado no começo.

Scope: global, a menos que haja motivo

Cada atributo tem um scope Global, Website ou Store View. O scope Store View é necessário para texto que é traduzido, como nome e descrição. Para quase todo o resto, Global é a escolha certa.

• Atributos com scope de store view podem ganhar uma linha de valor por store view. Importações e edições no admin em uma store view criam linhas de override que escondem mudanças feitas depois no scope padrão.
• Atributos configuráveis precisam ser Global.
• Os labels de dropdown já são traduzíveis por store view, mesmo com o scope do atributo em Global. Você não precisa do scope Store View para traduzir labels de opções.

O scope Website é relevante principalmente para preço, quando o price scope está definido como website, e para alguns atributos como status.

Propriedades de storefront têm custo

Toda flag em Storefront Properties adiciona trabalho em algum lugar. Ligue só o que o atributo precisa.

• Use in Search. Adiciona o atributo ao documento do produto no índice de busca. Muitos atributos pesquisáveis deixam o índice maior e o reindex mais lento, e adicionam ruído aos resultados. Peso de busca e sinônimos estão em sinônimos e relevância na busca.
• Use in Layered Navigation. Adiciona uma aggregation aos requests de categoria. Só para atributos que são filtros úteis e têm um número administrável de opções.
• Used in Product Listing. Carrega o atributo com toda product collection nas páginas de categoria. Só é necessário se um template de listagem o exibe. Deixar ligado em muitos atributos deixa as listagens lentas.
• Used for Sorting in Product Listing. Adiciona uma opção de ordenação e torna o atributo ordenável no índice.
• Use for Promo Rule Conditions. Deixa o atributo disponível nas condições das regras de preço de carrinho e de catálogo.
• Visible on Catalog Pages on Storefront. Mostra o atributo na aba More Information da página de produto.
• Add to Column Options e Use in Filter Options. Deixam o atributo disponível no grid de produtos do admin. Prático, mas o grid fica mais lento com muitos atributos em join.

Attribute sets

Os attribute sets decidem quais atributos aparecem no formulário de um produto no admin. Use-os para manter os formulários curtos e relevantes: um set para roupas, um set para eletrônicos, e assim por diante. Um produto só tem valores para os atributos do seu set, e a navegação em camadas só mostra filtros que têm valores nos produtos listados.

Não crie um set por categoria. Poucos sets que correspondam a famílias reais de produtos são mais fáceis de manter. Mover um produto para outro set pode perder valores de atributos que não estão no novo set, então planeje os sets antes de o catálogo crescer.

Crie atributos em código

Atributos criados à mão no admin existem só no banco onde foram criados. Crie-os com um data patch, para todo ambiente receber a mesma definição e a mudança ser versionada junto com o código. O padrão completo, incluindo a reversão, está em criando um atributo de produto com data patch. Um exemplo compacto:

<?php
declare(strict_types=1);

namespace Vendor\Catalog\Setup\Patch\Data;

use Magento\Catalog\Model\Product;
use Magento\Eav\Model\Entity\Attribute\ScopedAttributeInterface;
use Magento\Eav\Model\Entity\Attribute\Source\Table;
use Magento\Eav\Setup\EavSetupFactory;
use Magento\Framework\Setup\ModuleDataSetupInterface;
use Magento\Framework\Setup\Patch\DataPatchInterface;

class AddMaterialAttribute implements DataPatchInterface
{
    public function __construct(
        private readonly ModuleDataSetupInterface $moduleDataSetup,
        private readonly EavSetupFactory $eavSetupFactory
    ) {
    }

    public function apply(): self
    {
        $eavSetup = $this->eavSetupFactory->create(['setup' => $this->moduleDataSetup]);

        $eavSetup->addAttribute(Product::ENTITY, 'material', [
            'type' => 'int',
            'label' => 'Material',
            'input' => 'select',
            'source' => Table::class,
            'global' => ScopedAttributeInterface::SCOPE_GLOBAL,
            'required' => false,
            'user_defined' => true,
            'searchable' => false,
            'filterable' => 1,
            'comparable' => false,
            'visible_on_front' => true,
            'used_in_product_listing' => false,
            'group' => 'General',
            'option' => ['values' => ['Cotton', 'Linen', 'Wool']],
        ]);

        return $this;
    }

    public static function getDependencies(): array
    {
        return [];
    }

    public function getAliases(): array
    {
        return [];
    }
}

Repare que toda flag de storefront é definida explicitamente. Os defaults do addAttribute() nem sempre são o que você espera, e ser explícito documenta a intenção para o próximo desenvolvedor. Defina user_defined como true para atributos que o negócio gerencia, para poderem ser editados e removidos pelo admin.

Nomes e convenções

• Códigos de atributo são permanentes na prática. Eles vão parar em importações, integrações, templates e queries GraphQL. Use minúsculas, underscores e um nome claro como material em vez de attr_23.
• Não reutilize um código com outro significado. Crie um atributo novo e migre.
• Evite códigos que colidam com campos de produto existentes ou campos GraphQL. O Magento rejeita alguns códigos reservados no admin, mas um data patch dá menos proteção.
• Mantenha unidades fora dos valores quando puder. Um decimal weight_kg é mais fácil de filtrar e ordenar que um campo de texto com "1,5 kg".

Achando atributos sem uso

Catálogos mais antigos carregam atributos de extensões removidas, de migrações e de experimentos. Esta query conta valores por atributo na tabela int. Repita para as outras tabelas de valores:

SELECT a.attribute_code, COUNT(v.value_id) AS value_rows
FROM eav_attribute a
JOIN eav_entity_type t ON t.entity_type_id = a.entity_type_id
LEFT JOIN catalog_product_entity_int v ON v.attribute_id = a.attribute_id
WHERE t.entity_type_code = 'catalog_product'
  AND a.backend_type = 'int'
  AND a.is_user_defined = 1
GROUP BY a.attribute_id, a.attribute_code
ORDER BY value_rows ASC;

Atributos sem valores e sem referências no código ou nos templates são candidatos a remoção. Procure o código no codebase e nos arquivos de importação primeiro. Remova com um data patch que chame o removeAttribute(), antes em staging, e confira depois o formulário de produto no admin e o storefront.

Olhe também o catalog_eav_attribute em busca de atributos pesquisáveis, filtráveis ou usados em listagem sem motivo. Desligar essas flags é seguro e muitas vezes o ganho mais rápido no tempo de indexação, junto com os passos de setup e ajuste do OpenSearch.

FAQ

Quantos atributos de produto são demais no Magento 2?

Não há um limite fixo. O custo vem de quantos são pesquisáveis, filtráveis, usados em listagens e com scope de store view. Centenas de atributos simples não têm problema. Centenas de pesquisáveis têm.

Devo usar dropdown ou campo de texto para a marca?

Dropdown. Dá valores consistentes, funciona como filtro da navegação em camadas e agrega com eficiência no índice de busca. Campos de texto juntam variações do mesmo valor.

Posso mudar um atributo de texto para dropdown depois?

Não pelo admin. Os valores ficam em outra tabela e precisam ser migrados para IDs de opção com um script. É possível, mas planeje como uma migração de dados, com backup.

Por que minhas alterações no admin não aparecem em uma store view?

O atributo tem scope de store view e essa store view tem um valor próprio, muitas vezes criado por uma importação. Use a caixa Use Default Value na store view ou remova as linhas de override.

Atendo como freelancer em Magento e Adobe Commerce, incluindo desenho e limpeza de catálogo. Se precisar de ajuda com isso, fale comigo.