Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Makes metafields searchable and sortable

Fizza Iqbal04a15cf957d2
diff --git a/docs/developer/core-concepts/metafields.mdx b/docs/developer/core-concepts/metafields.mdx
index 273c5592a2..0f667c2563 100644
--- a/docs/developer/core-concepts/metafields.mdx
+++ b/docs/developer/core-concepts/metafields.mdx
@@ -34,6 +34,8 @@ erDiagram
string metafield_type
string resource_type
string display_on
+ boolean searchable
+ boolean sortable
}
Metafield {
@@ -84,6 +86,17 @@ Metafields support two visibility levels via the `display_on` attribute:
| `both` | Yes | Yes | Public product specifications |
| `back_end` | No | Yes | Internal notes, integration IDs |
+## Storefront search & sort
+
+Product metafield definitions can opt into storefront SearchProvider participation:
+
+| Flag | Effect | Allowed field types |
+|------|--------|---------------------|
+| `searchable` | Values are included in product text search | `short_text`, `long_text`, `number` |
+| `sortable` | Listings can sort with `sort=mf_{namespace.length}_{namespace}_{key}` (prefix `-` for descending), e.g. `mf_6_custom_label` | `short_text`, `number` |
+
+Both default to `false`. Set them on the definition (Admin UI, Admin API, or seeds). For an existing catalog with Meilisearch, run `rake spree:search:reindex` after toggling flags so index settings and product documents pick up new `mf_*` fields.
+
## Supported Resources
Metafields can be attached to most Spree resources including Products, Variants, Orders, Line Items, Taxons, Payments, Shipments, Gift Cards, Store Credits, and more.
diff --git a/docs/developer/core-concepts/search-filtering.mdx b/docs/developer/core-concepts/search-filtering.mdx
index 3202289df7..3ed2499726 100644
--- a/docs/developer/core-concepts/search-filtering.mdx
+++ b/docs/developer/core-concepts/search-filtering.mdx
@@ -9,11 +9,11 @@ import { Since } from '/snippets/since.mdx';
Spree provides powerful search, filtering, and sorting capabilities for products and other resources. The Store API supports:
-- Full-text search across product names and SKUs
+- Full-text search across product names, SKUs, and searchable product metafields
- Attribute-based filtering (price range, availability, stock status)
- Category and taxon filtering
- Faceted search with filter counts
-- Flexible sorting options
+- Flexible sorting options (including sortable product metafields via `sort=mf_{namespace.length}_{namespace}_{key}`)
## Product Search
@@ -167,6 +167,7 @@ const sorted = await client.products.list({
// Available sort options (prefix '-' for descending; use '-available_on' for newest):
// price, -price, name, -name, available_on, -available_on, best_selling
+// Plus any product metafield marked sortable, e.g. mf_6_custom_label / -mf_6_custom_label
```
```typescript Admin SDK
diff --git a/docs/developer/how-to/custom-search-provider.mdx b/docs/developer/how-to/custom-search-provider.mdx
index 6d01f1e354..92740abe3a 100644
--- a/docs/developer/how-to/custom-search-provider.mdx
+++ b/docs/developer/how-to/custom-search-provider.mdx
@@ -230,6 +230,12 @@ Background jobs (`IndexJob`, `RemoveJob`) fire on `after_commit` when `indexing_
Always use prefixed IDs (`ctg_abc`, `prod_xyz`, `optval_abc`) when indexing. Never use raw database IDs — Spree supports UUID primary keys.
+### Metafield search schema
+
+Product metafields marked `searchable` / `sortable` on `MetafieldDefinition` are projected through `Spree::SearchProvider::MetafieldSchema` — shared by providers and `ProductPresenter`. Toggle participation with definition flags; run `rake spree:search:reindex` after changes when using Meilisearch.
+
+Document shaping for `mf_*` fields stays on `search_product_presenter` — the only search-related dependency.
+
## Related Documentation
- [Search & Filtering](/developer/core-concepts/search-filtering) — Store API search reference
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index 1b892d9c40..f788ecf8c1 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -561,6 +561,18 @@ export interface CustomFieldDefinitionCreateParams {
field_type: string
resource_type: string
storefront_visible?: boolean
+ /**
+ * Include values in storefront product text search. Supported
+ * `field_type`s: `short_text`, `long_text`, `number`. Other types are
+ * rejected by the API with 422.
+ */
+ searchable?: boolean
+ /**
+ * Allow storefront product listings to sort by this field
+ * (`sort=mf_{n}_{namespace}_{key}`). Supported `field_type`s:
+ * `short_text`, `number`. Other types are rejected by the API with 422.
+ */
+ sortable?: boolean
}
export interface CustomFieldDefinitionUpdateParams {
@@ -569,6 +581,18 @@ export interface CustomFieldDefinitionUpdateParams {
label?: string
field_type?: string
storefront_visible?: boolean
+ /**
+ * Include values in storefront product text search. Supported
+ * `field_type`s: `short_text`, `long_text`, `number`. Other types are
+ * rejected by the API with 422.
+ */
+ searchable?: boolean
+ /**
+ * Allow storefront product listings to sort by this field
+ * (`sort=mf_{n}_{namespace}_{key}`). Supported `field_type`s:
+ * `short_text`, `number`. Other types are rejected by the API with 422.
+ */
+ sortable?: boolean
}
export interface ApiKeyCreateParams {
diff --git a/packages/admin-sdk/src/types/generated/CustomFieldDefinition.ts b/packages/admin-sdk/src/types/generated/CustomFieldDefinition.ts
index c6170aef6e..d04425d38c 100644
--- a/packages/admin-sdk/src/types/generated/CustomFieldDefinition.ts
+++ b/packages/admin-sdk/src/types/generated/CustomFieldDefinition.ts
@@ -1,4 +1,4 @@
-// Typelizer digest e4af80d6144d122b646f8f57cbbe910f
+// Typelizer digest 83586c68ee2b4b6847ae2261e626fb8d
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -10,6 +10,9 @@ interface CustomFieldDefinition {
field_type: 'short_text' | 'long_text' | 'rich_text' | 'number' | 'boolean' | 'json';
resource_type: string;
storefront_visible: boolean;
+ searchable: boolean;
+ sortable: boolean;
+ search_key: string;
created_at: string;
updated_at: string;
}
diff --git a/packages/admin-sdk/tests/custom-fields.test.ts b/packages/admin-sdk/tests/custom-fields.test.ts
index 68e02c02f0..90b1b04156 100644
--- a/packages/admin-sdk/tests/custom-fields.test.ts
+++ b/packages/admin-sdk/tests/custom-fields.test.ts
@@ -70,6 +70,7 @@ describe('custom fields', () => {
it('gets a definition', async () => {
const defn = await client.customFieldDefinitions.get('cfdef_1')
expect(defn.key).toBe('fabric')
+ expect(defn.search_key).toBe('mf_5_specs_fabric')
})
it('creates a definition', async () => {
diff --git a/packages/admin-sdk/tests/mocks/handlers.ts b/packages/admin-sdk/tests/mocks/handlers.ts
index ee71574930..243c78d550 100644
--- a/packages/admin-sdk/tests/mocks/handlers.ts
+++ b/packages/admin-sdk/tests/mocks/handlers.ts
@@ -24,6 +24,9 @@ export const fixtures = {
label: 'Fabric',
field_type: 'short_text',
storefront_visible: true,
+ searchable: false,
+ sortable: false,
+ search_key: 'mf_5_specs_fabric',
created_at: '2026-05-01T00:00:00.000Z',
updated_at: '2026-05-01T00:00:00.000Z',
},
diff --git a/packages/dashboard-core/src/components/resource-table.tsx b/packages/dashboard-core/src/components/resource-table.tsx
index 3a33f1ab2f..c27f9e4e85 100644
--- a/packages/dashboard-core/src/components/resource-table.tsx
+++ b/packages/dashboard-core/src/components/resource-table.tsx
@@ -174,6 +174,10 @@ interface ResourceTableProps<T> {
* menu on the trailing edge.
*/
rowActions?: (row: T) => ReactNode
+ /**
+ * Metafield sort fields for the Sort dropdown
+ */
+ metafieldSortColumns?: ColumnDef[]
}
export interface ReorderConfig<T> {
@@ -197,6 +201,7 @@ export function ResourceTable<T extends Record<string, any>>({
reorder,
bulkActions,
rowActions,
+ metafieldSortColumns,
}: ResourceTableProps<T>) {
const table = getTable<T>(tableKey)
const { t } = useTranslation()
@@ -431,6 +436,7 @@ export function ResourceTable<T extends Record<string, any>>({
title={title ?? table.title}
actions={resolvedActions}
hideSort={reorderActive}
+ metafieldSortColumns={metafieldSortColumns}
/>
<CardContent className="p-0">
{reorderActive ? (
diff --git a/packages/dashboard-core/src/components/table-toolbar.tsx b/packages/dashboard-core/src/components/table-toolbar.tsx
index 9fc354dc99..f4a50a23e9 100644
--- a/packages/dashboard-core/src/components/table-toolbar.tsx
+++ b/packages/dashboard-core/src/components/table-toolbar.tsx
@@ -65,6 +65,10 @@ interface TableToolbarProps {
actions?: React.ReactNode
/** Hide the sort dropdown — used when the table is drag-reorderable, where free sorting would defeat the drag. */
hideSort?: boolean
+ /**
+ * Metafield sort fields for the Sort dropdown
+ */
+ metafieldSortColumns?: ColumnDef[]
}
// ============================================================================
@@ -149,6 +153,7 @@ export function TableToolbar({
title,
actions,
hideSort = false,
+ metafieldSortColumns,
}: TableToolbarProps) {
const { t } = useTranslation()
const [filterOpen, setFilterOpen] = useState(false)
@@ -158,7 +163,13 @@ export function TableToolbar({
// Memoize so `FilterPanel`'s `useMemo` deps stay stable across parent
// re-renders. Otherwise picking a filter value triggers an `items` change
// in the field-picker Select, which Base UI re-emits as a state change.
- const sortableColumns = useMemo(() => allCols.filter((c) => c.sortable), [allCols])
+ const sortableColumns = useMemo(
+ () => [
+ ...allCols.filter((c) => c.sortable),
+ ...(metafieldSortColumns ?? []).filter((c) => !!c.sortable),
+ ],
+ [allCols, metafieldSortColumns],
+ )
const filterableColumns = useMemo(() => allCols.filter((c) => c.filterable), [allCols])
const activeFilterCount = filters.length
diff --git a/packages/dashboard/src/components/spree/custom-fields/definition-form.tsx b/packages/dashboard/src/components/spree/custom-fields/definition-form.tsx
index a078c9433c..41f41244d7 100644
--- a/packages/dashboard/src/components/spree/custom-fields/definition-form.tsx
+++ b/packages/dashboard/src/components/spree/custom-fields/definition-form.tsx
@@ -17,6 +17,8 @@ import {
DEFAULT_RESOURCE_TYPES,
FIELD_TYPES,
fieldTypeLabel,
+ fieldTypeSupportsSearchable,
+ fieldTypeSupportsSortable,
resourceTypeLabel,
} from '../../../schemas/custom-field-definition'
@@ -58,6 +60,9 @@ export function DefinitionFormFields({
}: DefinitionFormFieldsProps) {
const { t } = useTranslation()
const { errors } = form.formState
+ const fieldType = form.watch('field_type')
+ const searchableSupported = fieldTypeSupportsSearchable(fieldType)
+ const sortableSupported = fieldTypeSupportsSortable(fieldType)
const fieldTypeItems = FIELD_TYPES.map((value) => ({
value,
@@ -169,7 +174,17 @@ export function DefinitionFormFields({
<Select
items={fieldTypeItems}
value={field.value}
- onValueChange={field.onChange}
+ onValueChange={(value) => {
+ field.onChange(value)
+ const next = String(value)
+ if (!fieldTypeSupportsSearchable(next)) {
+ form.setValue('searchable', false)
+ }
+ if (!fieldTypeSupportsSortable(next)) {
+ form.setValue('sortable', false)
+ }
+ form.clearErrors(['searchable', 'sortable'])
+ }}
disabled={fieldTypeReadOnly}
>
<SelectTrigger id="cfd-field-type" aria-invalid={!!errors.field_type || undefined}>
@@ -211,6 +226,58 @@ export function DefinitionFormFields({
/>
</div>
</Field>
+
+ <Field>
+ <div className="flex items-start justify-between gap-4">
+ <div className="flex flex-col gap-1">
+ <FieldLabel htmlFor="cfd-searchable" className="cursor-pointer">
+ {t('admin.fields.custom_field_definition.searchable.label')}
+ </FieldLabel>
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.custom_field_definition.searchable.help')}
+ </span>
+ </div>
+ <Controller
+ name="searchable"
+ control={form.control}
+ render={({ field }) => (
+ <Switch
+ id="cfd-searchable"
+ checked={!!field.value}
+ onCheckedChange={field.onChange}
+ disabled={!searchableSupported}
+ />
+ )}
+ />
+ </div>
+ <FieldError errors={[errors.searchable]} />
+ </Field>
+
+ <Field>
+ <div className="flex items-start justify-between gap-4">
+ <div className="flex flex-col gap-1">
+ <FieldLabel htmlFor="cfd-sortable" className="cursor-pointer">
+ {t('admin.fields.custom_field_definition.sortable.label')}
+ </FieldLabel>
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.custom_field_definition.sortable.help')}
+ </span>
+ </div>
+ <Controller
+ name="sortable"
+ control={form.control}
+ render={({ field }) => (
+ <Switch
+ id="cfd-sortable"
+ checked={!!field.value}
+ onCheckedChange={field.onChange}
+ disabled={!sortableSupported}
+ />
+ )}
+ />
+ </div>
+ <FieldError errors={[errors.sortable]} />
+ </Field>
</div>
)
}
diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.json
index 6c4fe8e720..d28bb4c96c 100644
--- a/packages/dashboard/src/locales/ar.json
+++ b/packages/dashboard/src/locales/ar.json
@@ -235,6 +235,14 @@
"storefront_visible": {
"label": "مرئي في المتجر",
"column_label": "المتجر"
+ },
+ "searchable": {
+ "label": "قابل للبحث",
+ "help": "تضمين القيم في بحث منتجات الواجهة (نص قصير ونص طويل ورقم فقط). بعد التفعيل مع Meilisearch، نفّذ rake spree:search:reindex لتحديث المنتجات الحالية."
+ },
+ "sortable": {
+ "label": "قابل للفرز",
+ "help": "السماح بفرز قوائم منتجات الواجهة حسب هذا الحقل (نص قصير ورقم فقط). بعد التفعيل مع Meilisearch، نفّذ rake spree:search:reindex لتحديث المنتجات الحالية."
}
},
"tax_category": {
diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.json
index 0dd7b760f9..ba4547b6b4 100644
--- a/packages/dashboard/src/locales/de.json
+++ b/packages/dashboard/src/locales/de.json
@@ -187,6 +187,14 @@
"storefront_visible": {
"label": "Im Storefront sichtbar",
"column_label": "Storefront"
+ },
+ "searchable": {
+ "label": "Durchsuchbar",
+ "help": "Werte in die Storefront-Produktsuche aufnehmen (nur Kurztext, Langtext und Zahl). Nach dem Aktivieren mit Meilisearch rake spree:search:reindex ausführen, damit bestehende Produkte aktualisiert werden."
+ },
+ "sortable": {
+ "label": "Sortierbar",
+ "help": "Storefront-Produktlisten nach diesem Feld sortieren lassen (nur Kurztext und Zahl). Nach dem Aktivieren mit Meilisearch rake spree:search:reindex ausführen, damit bestehende Produkte aktualisiert werden."
}
},
"tax_category": {
diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.json
index 6e325ffdb5..0cb4b14025 100644
--- a/packages/dashboard/src/locales/en.json
+++ b/packages/dashboard/src/locales/en.json
@@ -238,6 +238,14 @@
"storefront_visible": {
"label": "Visible on storefront",
"column_label": "Storefront"
+ },
+ "searchable": {
+ "label": "Searchable",
+ "help": "Include values in storefront product text search (short text, long text, and number only). After enabling with Meilisearch, run rake spree:search:reindex so existing products are updated."
+ },
+ "sortable": {
+ "label": "Sortable",
+ "help": "Allow storefront product listings to sort by this field (short text and number only). After enabling with Meilisearch, run rake spree:search:reindex so existing products are updated."
}
},
"tax_category": {
diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.json
index ceda495bee..8bcef75370 100644
--- a/packages/dashboard/src/locales/fr.json
+++ b/packages/dashboard/src/locales/fr.json
@@ -187,6 +187,14 @@
"storefront_visible": {
"label": "Visible sur la boutique",
"column_label": "Boutique"
+ },
+ "searchable": {
+ "label": "Recherchable",
+ "help": "Inclure les valeurs dans la recherche de produits de la boutique (texte court, texte long et nombre uniquement). Après activation avec Meilisearch, exécutez rake spree:search:reindex pour mettre à jour les produits existants."
+ },
+ "sortable": {
+ "label": "Triable",
+ "help": "Autoriser le tri des listes de produits de la boutique par ce champ (texte court et nombre uniquement). Après activation avec Meilisearch, exécutez rake spree:search:reindex pour mettre à jour les produits existants."
}
},
"tax_category": {
diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.json
index 9e04cf5460..3f7b878a1b 100644
--- a/packages/dashboard/src/locales/pl.json
+++ b/packages/dashboard/src/locales/pl.json
@@ -187,6 +187,14 @@
"storefront_visible": {
"label": "Widoczne w sklepie",
"column_label": "Sklep"
+ },
+ "searchable": {
+ "label": "Przeszukiwalne",
+ "help": "Uwzględnij wartości w wyszukiwaniu produktów storefront (tylko krótki tekst, długi tekst i liczba). Po włączeniu z Meilisearch uruchom rake spree:search:reindex, aby zaktualizować istniejące produkty."
+ },
+ "sortable": {
+ "label": "Sortowalne",
+ "help": "Pozwól sortować listy produktów storefront według tego pola (tylko krótki tekst i liczba). Po włączeniu z Meilisearch uruchom rake spree:search:reindex, aby zaktualizować istniejące produkty."
}
},
"tax_category": {
diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.json
index f65adebaef..79e2b84aad 100644
--- a/packages/dashboard/src/locales/zh-CN.json
+++ b/packages/dashboard/src/locales/zh-CN.json
@@ -235,6 +235,14 @@
"storefront_visible": {
"label": "在网店中显示",
"column_label": "网店"
+ },
+ "searchable": {
+ "label": "可搜索",
+ "help": "将值纳入店面商品全文搜索(仅短文本、长文本和数字)。启用 Meilisearch 后请运行 rake spree:search:reindex,以便更新现有商品。"
+ },
+ "sortable": {
+ "label": "可排序",
+ "help": "允许店面商品列表按此字段排序(仅短文本和数字)。启用 Meilisearch 后请运行 rake spree:search:reindex,以便更新现有商品。"
}
},
"tax_category": {
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/index.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/index.tsx
index 6149bf5d2b..7987e735d3 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/index.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/index.tsx
@@ -1,5 +1,5 @@
import type { Product } from '@spree/admin-sdk'
-import type { BulkAction, BulkActionFormProps } from '@spree/dashboard-core'
+import type { BulkAction, BulkActionFormProps, ColumnDef } from '@spree/dashboard-core'
import {
adminClient,
ExportButton,
@@ -9,6 +9,7 @@ import {
resourceSearchSchema,
Subject,
TagCombobox,
+ useCustomFieldDefinitions,
usePermissions,
} from '@spree/dashboard-core'
import {
@@ -273,6 +274,18 @@ function ProductsPage() {
[storeId],
)
+ const { data: definitionsResponse } = useCustomFieldDefinitions('Spree::Product')
+ const metafieldSortColumns = useMemo<ColumnDef[]>(() => {
+ const definitions = definitionsResponse?.data ?? []
+ return definitions
+ .filter((definition) => definition.sortable && definition.search_key)
+ .map((definition) => ({
+ key: definition.search_key,
+ label: definition.label,
+ sortable: true,
+ }))
+ }, [definitionsResponse])
+
return (
<>
<ResourceTable
@@ -283,6 +296,7 @@ function ProductsPage() {
searchParams={searchParams}
bulkActions={bulkActions}
rowActions={renderRowActions}
+ metafieldSortColumns={metafieldSortColumns}
actions={(ctx) => (
<>
<ImportButton
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/custom-field-definitions.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/custom-field-definitions.tsx
index 0a8ecdef35..7f14069cad 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/custom-field-definitions.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/custom-field-definitions.tsx
@@ -237,6 +237,8 @@ function EditSheet({
field_type: definition.field_type,
resource_type: definition.resource_type,
storefront_visible: definition.storefront_visible,
+ searchable: definition.searchable,
+ sortable: definition.sortable,
})
}
}, [definition, form])
diff --git a/packages/dashboard/src/schemas/custom-field-definition.ts b/packages/dashboard/src/schemas/custom-field-definition.ts
index c0ea5e496e..52ca035ece 100644
--- a/packages/dashboard/src/schemas/custom-field-definition.ts
+++ b/packages/dashboard/src/schemas/custom-field-definition.ts
@@ -20,6 +20,20 @@ export const FIELD_TYPES = [
export type FieldType = (typeof FIELD_TYPES)[number]
+/** Field types that may set `searchable: true` (mirrors backend validation). */
+export const SEARCHABLE_FIELD_TYPES = ['short_text', 'long_text', 'number'] as const
+
+/** Field types that may set `sortable: true` (mirrors backend validation). */
+export const SORTABLE_FIELD_TYPES = ['short_text', 'number'] as const
+
+export function fieldTypeSupportsSearchable(fieldType: string): boolean {
+ return (SEARCHABLE_FIELD_TYPES as readonly string[]).includes(fieldType)
+}
+
+export function fieldTypeSupportsSortable(fieldType: string): boolean {
+ return (SORTABLE_FIELD_TYPES as readonly string[]).includes(fieldType)
+}
+
export function fieldTypeLabel(value: string): string {
return i18n.t(`admin.fields.custom_field_definition.field_type.options.${value}`, {
defaultValue: value,
@@ -70,6 +84,8 @@ export const customFieldDefinitionSchema = z.object({
.string()
.min(1, { error: requiredMessage('custom_field_definition.resource_type') }),
storefront_visible: z.boolean(),
+ searchable: z.boolean(),
+ sortable: z.boolean(),
})
export type CustomFieldDefinitionFormValues = z.infer<typeof customFieldDefinitionSchema>
@@ -81,6 +97,8 @@ export const CUSTOM_FIELD_DEFINITION_DEFAULTS: CustomFieldDefinitionFormValues =
field_type: 'short_text',
resource_type: 'Spree::Product',
storefront_visible: false,
+ searchable: false,
+ sortable: false,
}
export function customFieldDefinitionValuesToCreateParams(
@@ -93,6 +111,8 @@ export function customFieldDefinitionValuesToCreateParams(
field_type: v.field_type,
resource_type: v.resource_type,
storefront_visible: v.storefront_visible,
+ searchable: v.searchable,
+ sortable: v.sortable,
}
}
@@ -110,5 +130,7 @@ export function customFieldDefinitionValuesToUpdateParams(
namespace: v.namespace,
key: v.key,
storefront_visible: v.storefront_visible,
+ searchable: v.searchable,
+ sortable: v.sortable,
}
}
diff --git a/packages/sdk/src/types/generated/ProductFilterSortOption.ts b/packages/sdk/src/types/generated/ProductFilterSortOption.ts
index a4623c6f45..c6fe0f1648 100644
--- a/packages/sdk/src/types/generated/ProductFilterSortOption.ts
+++ b/packages/sdk/src/types/generated/ProductFilterSortOption.ts
@@ -1,9 +1,10 @@
-// Typelizer digest 22213cc47cc63b7e426e559c3be7e787
+// Typelizer digest 665463997ac503409a6f563ac6cd58dd
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
interface ProductFilterSortOption {
id: string;
+ label: string | null;
}
export default ProductFilterSortOption;
diff --git a/packages/sdk/src/zod/generated/ProductFilterSortOption.ts b/packages/sdk/src/zod/generated/ProductFilterSortOption.ts
index 49134abc30..28e72afcfe 100644
--- a/packages/sdk/src/zod/generated/ProductFilterSortOption.ts
+++ b/packages/sdk/src/zod/generated/ProductFilterSortOption.ts
@@ -3,6 +3,7 @@ import { z } from 'zod';
export const ProductFilterSortOptionSchema = z.object({
id: z.string(),
+ label: z.string().nullable(),
});
export type ProductFilterSortOption = z.infer<typeof ProductFilterSortOptionSchema>;
diff --git a/spree/admin/app/javascript/spree/admin/application.js b/spree/admin/app/javascript/spree/admin/application.js
index e7e6be4031..5bb0b9b34f 100644
--- a/spree/admin/app/javascript/spree/admin/application.js
+++ b/spree/admin/app/javascript/spree/admin/application.js
@@ -63,6 +63,7 @@ import FontPickerController from 'spree/admin/controllers/font_picker_controller
import HighlightController from 'spree/admin/controllers/highlight_controller'
import ImportFormController from 'spree/admin/controllers/import_form_controller'
import MediaFormController from 'spree/admin/controllers/media_form_controller'
+import MetafieldFormController from 'spree/admin/controllers/metafield_form_controller'
import MoneyFieldController from 'spree/admin/controllers/money_field_controller'
import MultiInputController from 'spree/admin/controllers/multi_input_controller'
import MultiTomSelectController from 'spree/admin/controllers/multi_tom_select_controller'
@@ -135,6 +136,7 @@ application.register('font-picker', FontPickerController)
application.register('highlight', HighlightController)
application.register('import-form', ImportFormController)
application.register('media-form', MediaFormController)
+application.register('metafield-form', MetafieldFormController)
application.register('money-field', MoneyFieldController)
application.register('multi-input', MultiInputController)
application.register('multi-tom-select', MultiTomSelectController)
diff --git a/spree/admin/app/javascript/spree/admin/controllers/metafield_form_controller.js b/spree/admin/app/javascript/spree/admin/controllers/metafield_form_controller.js
new file mode 100644
index 0000000000..52d793aa48
--- /dev/null
+++ b/spree/admin/app/javascript/spree/admin/controllers/metafield_form_controller.js
@@ -0,0 +1,79 @@
+import { Controller } from '@hotwired/stimulus'
+
+// Mirrors Spree::MetafieldDefinition searchable/sortable type capabilities.
+const SEARCHABLE_TYPES = new Set([
+ 'Spree::Metafields::ShortText',
+ 'Spree::Metafields::LongText',
+ 'Spree::Metafields::Number',
+])
+
+const SORTABLE_TYPES = new Set([
+ 'Spree::Metafields::ShortText',
+ 'Spree::Metafields::Number',
+])
+
+export default class extends Controller {
+ static targets = ['metafieldType', 'searchable', 'sortable']
+
+ connect() {
+ this.restoreCheckbox(this.searchableTarget)
+ this.restoreCheckbox(this.sortableTarget)
+ this.syncCapabilities()
+ }
+
+ typeChanged(event) {
+ if (this.hasMetafieldTypeTarget && event?.target && event.target !== this.metafieldTypeTarget) {
+ return
+ }
+
+ this.syncCapabilities()
+ this.clearCapabilityErrors(this.searchableTarget)
+ this.clearCapabilityErrors(this.sortableTarget)
+ this.clearAlertErrors(['searchable', 'sortable'])
+ }
+
+ syncCapabilities() {
+ if (!this.hasMetafieldTypeTarget) return
+
+ const type = this.metafieldTypeTarget.value
+ this.applyCapability(this.searchableTarget, SEARCHABLE_TYPES.has(type))
+ this.applyCapability(this.sortableTarget, SORTABLE_TYPES.has(type))
+ }
+
+ applyCapability(input, supported) {
+ if (!input) return
+
+ input.disabled = !supported
+ if (!supported) input.checked = false
+ }
+
+ // Unwrap .field_with_errors so input~label sibling styles work again.
+ // Leaves .formError text in place until Type changes.
+ restoreCheckbox(input) {
+ if (!input) return
+
+ const checkbox = input.closest('.form-checkbox')
+ checkbox?.querySelectorAll(':scope > .field_with_errors').forEach((wrapper) => {
+ wrapper.replaceWith(...wrapper.childNodes)
+ })
+ }
+
+ clearCapabilityErrors(input) {
+ if (!input) return
+
+ this.restoreCheckbox(input)
+ input.closest('.form-group')?.querySelector('.formError')?.remove()
+ }
+
+ clearAlertErrors(fields) {
+ const form = this.element.closest('form') || this.element
+ const alert = form.querySelector('.alert-danger')
+ if (!alert) return
+
+ alert.querySelectorAll('li').forEach((li) => {
+ const text = li.textContent.toLowerCase()
+ if (fields.some((name) => text.includes(name))) li.remove()
+ })
+ if (!alert.querySelector('li')) alert.remove()
+ }
+}
diff --git a/spree/admin/app/views/spree/admin/metafield_definitions/_form.html.erb b/spree/admin/app/views/spree/admin/metafield_definitions/_form.html.erb
index 2a565996d8..ac935c766e 100644
--- a/spree/admin/app/views/spree/admin/metafield_definitions/_form.html.erb
+++ b/spree/admin/app/views/spree/admin/metafield_definitions/_form.html.erb
@@ -1,4 +1,6 @@
-<div class="card mb-6">
+<div class="card mb-6"
+ data-controller="metafield-form"
+ data-action="change->metafield-form#typeChanged">
<div class="card-body">
<div class="form-group">
<%= f.spree_text_field :name, required: true, autofocus: f.object.new_record? %>
@@ -19,7 +21,10 @@
</div>
<div class="form-group">
- <%= f.spree_select :metafield_type, metafield_definition_types, { include_blank: true, autocomplete: true, label: Spree.t(:type) }, { required: true } %>
+ <%= f.spree_select :metafield_type,
+ metafield_definition_types,
+ { include_blank: true, autocomplete: true, label: Spree.t(:type) },
+ { required: true, data: { metafield_form_target: 'metafieldType' } } %>
</div>
<% else %>
<div class="alert alert-warning">
@@ -40,5 +45,17 @@
<div class="form-group">
<%= f.spree_select :display_on, display_on_options(Spree::MetafieldDefinition), { include_blank: true, autocomplete: true }, { required: true } %>
</div>
+
+ <div class="form-group">
+ <%= f.spree_check_box :searchable,
+ help: Spree.t('admin.metafield_definitions.searchable_help'),
+ data: { metafield_form_target: 'searchable' } %>
+ </div>
+
+ <div class="form-group">
+ <%= f.spree_check_box :sortable,
+ help: Spree.t('admin.metafield_definitions.sortable_help'),
+ data: { metafield_form_target: 'sortable' } %>
+ </div>
</div>
-</div>
\ No newline at end of file
+</div>
diff --git a/spree/admin/config/locales/en.yml b/spree/admin/config/locales/en.yml
index 9b48477f43..cb4dfe8f5f 100644
--- a/spree/admin/config/locales/en.yml
+++ b/spree/admin/config/locales/en.yml
@@ -260,6 +260,8 @@ en:
supported_locales_hint: Comma-separated list of additional locale codes (e.g. fr,de,es)
metafield_definitions:
edit_warning: You can't change the resource type or metafield type after the definition has been used.
+ searchable_help: Include this field's values in storefront product text search (short text, long text, and number only). After enabling, run rake spree:search:reindex if using Meilisearch so existing products are updated.
+ sortable_help: Allow storefront product listings to sort by this field (short text and number only). After enabling, run rake spree:search:reindex if using Meilisearch so existing products are updated.
used_in: Used in
metafields:
none_configured_for: No metafield definitions configured for %{resource}.
diff --git a/spree/api/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb
index 82d59b6f45..f6d43dc2c5 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb
@@ -25,7 +25,8 @@ module Spree
# API → DB column rename lands in 6.0 and this controller stays flat.
def permitted_params
params.permit(:namespace, :key, :label, :field_type,
- :resource_type, :storefront_visible)
+ :resource_type, :storefront_visible,
+ :searchable, :sortable)
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/store/products/filters_controller.rb b/spree/api/app/controllers/spree/api/v3/store/products/filters_controller.rb
index 8daf57206a..2742859f87 100644
--- a/spree/api/app/controllers/spree/api/v3/store/products/filters_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/products/filters_controller.rb
@@ -44,7 +44,8 @@ module Spree
search_query,
search_filters&.sort_by(&:first)&.to_json,
max_updated,
- product_count
+ product_count,
+ search_provider.metafield_schema.schema_version
]
parts.compact.join('/')
diff --git a/spree/api/app/serializers/spree/api/v3/admin/custom_field_definition_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/custom_field_definition_serializer.rb
index 180cbd9a63..797fdaa42b 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/custom_field_definition_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/custom_field_definition_serializer.rb
@@ -10,9 +10,13 @@ module Spree
label: :string,
field_type: Spree::Metafield::FIELD_TYPE_TOKENS,
resource_type: :string,
- storefront_visible: :boolean
+ storefront_visible: :boolean,
+ searchable: :boolean,
+ sortable: :boolean,
+ search_key: :string
attributes :namespace, :key, :label, :field_type, :resource_type, :storefront_visible,
+ :searchable, :sortable, :search_key,
created_at: :iso8601, updated_at: :iso8601
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/product_filter_sort_option_serializer.rb b/spree/api/app/serializers/spree/api/v3/product_filter_sort_option_serializer.rb
index 1f99106869..d5895149fa 100644
--- a/spree/api/app/serializers/spree/api/v3/product_filter_sort_option_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/product_filter_sort_option_serializer.rb
@@ -2,9 +2,9 @@ module Spree
module Api
module V3
class ProductFilterSortOptionSerializer < BaseSerializer
- typelize id: :string
+ typelize id: :string, label: 'string | null'
- attributes :id
+ attributes :id, :label
end
end
end
diff --git a/spree/api/app/services/spree/api/v3/filters_aggregator.rb b/spree/api/app/services/spree/api/v3/filters_aggregator.rb
index 09ea41123a..54cc3d4e51 100644
--- a/spree/api/app/services/spree/api/v3/filters_aggregator.rb
+++ b/spree/api/app/services/spree/api/v3/filters_aggregator.rb
@@ -36,7 +36,7 @@ module Spree
end
def sort_options
- Spree::Taxon::SORT_ORDERS.map { |id| { id: to_api_sort(id) } }
+ Spree::Taxon::SORT_ORDERS.map { |id| { id: to_api_sort(id), label: nil } }
end
# Converts internal sort format ('price asc') to API format ('price', '-price')
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/custom_field_definitions_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/custom_field_definitions_controller_spec.rb
index 13fd6bf34a..4bfff08b82 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/custom_field_definitions_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/custom_field_definitions_controller_spec.rb
@@ -37,7 +37,10 @@ RSpec.describe Spree::Api::V3::Admin::CustomFieldDefinitionsController, type: :c
expect(item).to include(
'namespace' => 'specs',
'field_type' => 'short_text',
- 'storefront_visible' => true
+ 'storefront_visible' => true,
+ 'searchable' => false,
+ 'sortable' => false,
+ 'search_key' => 'mf_5_specs_fabric'
)
end
end
@@ -63,6 +66,20 @@ RSpec.describe Spree::Api::V3::Admin::CustomFieldDefinitionsController, type: :c
expect(json_response['label']).to eq('Country of Origin')
expect(json_response['field_type']).to eq('short_text')
expect(json_response['storefront_visible']).to eq(true)
+ expect(json_response['searchable']).to eq(false)
+ expect(json_response['sortable']).to eq(false)
+ end
+
+ it 'persists searchable and sortable flags' do
+ post :create, params: create_params.merge(searchable: true, sortable: true, key: 'material'), as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['searchable']).to eq(true)
+ expect(json_response['sortable']).to eq(true)
+
+ defn = Spree::CustomFieldDefinition.find_by_prefix_id(json_response['id'])
+ expect(defn.searchable).to eq(true)
+ expect(defn.sortable).to eq(true)
end
context 'with storefront_visible: false' do
diff --git a/spree/api/spec/controllers/spree/api/v3/store/products/filters_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/products/filters_controller_spec.rb
index e50b38ffd2..5a3bb9f2c2 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/products/filters_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/products/filters_controller_spec.rb
@@ -101,6 +101,19 @@ RSpec.describe Spree::Api::V3::Store::Products::FiltersController, type: :contro
)
end
+ it 'invalidates cached sort options when a metafield definition becomes sortable' do
+ get :index
+ expect(json_response['sort_options'].map { |s| s['id'] }).not_to include('mf_6_custom_weight')
+
+ create(:metafield_definition, :number_field, :sortable,
+ namespace: 'custom', key: 'weight', name: 'Weight')
+
+ get :index
+ expect(json_response['sort_options'].map { |s| s['id'] }).to include(
+ 'mf_6_custom_weight', '-mf_6_custom_weight'
+ )
+ end
+
it 'returns total product count' do
get :index
diff --git a/spree/api/spec/controllers/spree/api/v3/store/products/meilisearch_integration_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/products/meilisearch_integration_spec.rb
index acf828ba61..0b1358b5fa 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/products/meilisearch_integration_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/products/meilisearch_integration_spec.rb
@@ -236,6 +236,99 @@ RSpec.describe 'Meilisearch Integration', type: :controller, if: ENV['MEILISEARC
end
end
+ describe 'searchable / sortable metafields' do
+ let!(:label_definition) do
+ create(:metafield_definition, :short_text_field, :searchable, :sortable,
+ namespace: 'custom', key: 'label')
+ end
+ let!(:weight_definition) do
+ create(:metafield_definition, :number_field, :sortable,
+ namespace: 'custom', key: 'weight')
+ end
+ # Product with neither metafield — exercises missing-attribute sort placement.
+ let!(:missing_metafield_product) do
+ create(:product, name: 'Green Linen Shirt', status: 'active', store: store, taxons: [clothing_category])
+ end
+
+ before do
+ cheap_red_shirt.set_metafield(label_definition, 'Apple')
+ expensive_blue_shirt.set_metafield(label_definition, 'Cherry')
+ # blue_shoes left without label metafield
+
+ cheap_red_shirt.set_metafield(weight_definition, '10')
+ expensive_blue_shirt.set_metafield(weight_definition, '2')
+ blue_shoes.set_metafield(weight_definition, '3')
+
+ provider.reindex(store.products)
+ wait_for_meilisearch_indexing!
+ end
+
+ it 'includes metafield keys in searchable and sortable settings' do
+ settings = ::Meilisearch::Client.new(ENV['MEILISEARCH_URL']).index(index_name).get_settings
+ expect(settings['searchableAttributes']).to include('mf_6_custom_label')
+ expect(settings['sortableAttributes']).to include('mf_6_custom_label', 'mf_6_custom_weight')
+ end
+
+ it 'finds products by searchable metafield value' do
+ get :index, params: { q: { search: 'Apple' } }
+
+ expect(response).to have_http_status(:ok)
+ names = json_response['data'].map { |p| p['name'] }
+ expect(names).to include('Red Cotton Shirt')
+ expect(names).not_to include('Blue Silk Shirt')
+ end
+
+ it 'sorts by short_text metafield ascending and descending with missing values last' do
+ get :index, params: { sort: 'mf_6_custom_label' }
+ expect(response).to have_http_status(:ok)
+ asc_names = json_response['data'].map { |p| p['name'] }
+ expect(asc_names.first(2)).to eq(['Red Cotton Shirt', 'Blue Silk Shirt'])
+ expect(asc_names.last(2)).to match_array(['Green Linen Shirt', 'Blue Running Shoes'])
+
+ get :index, params: { sort: '-mf_6_custom_label' }
+ expect(response).to have_http_status(:ok)
+ desc_names = json_response['data'].map { |p| p['name'] }
+ expect(desc_names.first(2)).to eq(['Blue Silk Shirt', 'Red Cotton Shirt'])
+ expect(desc_names.last(2)).to match_array(['Green Linen Shirt', 'Blue Running Shoes'])
+ end
+
+ it 'sorts by number metafield numerically' do
+ get :index, params: { sort: 'mf_6_custom_weight' }
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].map { |p| p['name'] }.first(3)).to eq(
+ ['Blue Silk Shirt', 'Blue Running Shoes', 'Red Cotton Shirt']
+ )
+
+ get :index, params: { sort: '-mf_6_custom_weight' }
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].map { |p| p['name'] }.first(3)).to eq(
+ ['Red Cotton Shirt', 'Blue Running Shoes', 'Blue Silk Shirt']
+ )
+ end
+ end
+
+ describe 'sorting by a newly sortable metafield' do
+ it 'self-heals when the sort attribute is not yet configured on the index' do
+ definition = create(:metafield_definition, :short_text_field, :sortable,
+ namespace: 'custom', key: 'label')
+ cheap_red_shirt.set_metafield(definition, 'aaa')
+ expensive_blue_shirt.set_metafield(definition, 'zzz')
+ provider.reindex(store.products)
+ wait_for_meilisearch_indexing!
+
+ # Strip the metafield from sortable attributes so the next sort request
+ # hits invalid_search_sort and must refresh settings + retry.
+ client = ::Meilisearch::Client.new(ENV['MEILISEARCH_URL'])
+ client.index(index_name).update_sortable_attributes(%w[name price created_at available_on units_sold_count]).await
+
+ get :index, params: { sort: definition.search_key }
+
+ expect(response).to have_http_status(:ok)
+ names = json_response['data'].map { |p| p['name'] }
+ expect(names.first).to eq('Red Cotton Shirt')
+ end
+ end
+
describe 'pagination' do
it 'paginates results' do
get :index, params: { limit: 2, page: 1 }
diff --git a/spree/api/spec/integration/spree/api/v3/admin/custom_field_definitions_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/custom_field_definitions_spec.rb
index d15d9d89a4..640d9a7f5f 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/custom_field_definitions_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/custom_field_definitions_spec.rb
@@ -42,6 +42,7 @@ RSpec.describe 'Admin Custom Field Definitions API', type: :request, swagger_doc
expect(item['field_type']).to eq('short_text')
expect(item['storefront_visible']).to eq(true)
expect(item['resource_type']).to eq('Spree::Product')
+ expect(item['search_key']).to eq('mf_5_specs_fabric')
end
end
end
@@ -75,6 +76,14 @@ RSpec.describe 'Admin Custom Field Definitions API', type: :request, swagger_doc
storefront_visible: {
type: :boolean,
description: 'When false, definition is admin-only (was `display_on: back_end`)'
+ },
+ searchable: {
+ type: :boolean,
+ description: 'When true, values are included in storefront product text search'
+ },
+ sortable: {
+ type: :boolean,
+ description: 'When true, storefront product listings can sort by this field'
}
}
}
@@ -149,7 +158,9 @@ RSpec.describe 'Admin Custom Field Definitions API', type: :request, swagger_doc
type: :object,
properties: {
label: { type: :string },
- storefront_visible: { type: :boolean }
+ storefront_visible: { type: :boolean },
+ searchable: { type: :boolean },
+ sortable: { type: :boolean }
}
}
diff --git a/spree/api/spec/serializers/spree/api/v3/product_filters_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/product_filters_serializer_spec.rb
index c2d6620fb9..a8d207e8fb 100644
--- a/spree/api/spec/serializers/spree/api/v3/product_filters_serializer_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/product_filters_serializer_spec.rb
@@ -45,7 +45,7 @@ RSpec.describe Spree::Api::V3::ProductFiltersSerializer do
]
}
],
- sort_options: [{ id: 'price' }, { id: '-price' }],
+ sort_options: [{ id: 'price', label: nil }, { id: '-price', label: nil }],
default_sort: 'manual',
total_count: 5
)
@@ -99,7 +99,10 @@ RSpec.describe Spree::Api::V3::ProductFiltersSerializer do
}
],
'id' => nil,
- 'sort_options' => [{ 'id' => 'price' }, { 'id' => '-price' }],
+ 'sort_options' => [
+ { 'id' => 'price', 'label' => nil },
+ { 'id' => '-price', 'label' => nil }
+ ],
'default_sort' => 'manual',
'total_count' => 5
)
diff --git a/spree/core/app/models/spree/metafield.rb b/spree/core/app/models/spree/metafield.rb
index fb07425c1e..970591f865 100644
--- a/spree/core/app/models/spree/metafield.rb
+++ b/spree/core/app/models/spree/metafield.rb
@@ -21,6 +21,17 @@ module Spree
# in OpenAPI (string-array form was added in typelizer 0.10.0).
FIELD_TYPE_TOKENS = TYPE_TOKENS.keys.freeze
+ # Whether MetafieldDefinition may enable `searchable` / `sortable` for this
+ # STI type. Used only by definition validations (not by SearchProvider
+ # indexing). Defaults to false; subclasses override (e.g. ShortText).
+ def self.searchable?
+ false
+ end
+
+ def self.sortable?
+ false
+ end
+
has_prefix_id :cf
#
diff --git a/spree/core/app/models/spree/metafield_definition.rb b/spree/core/app/models/spree/metafield_definition.rb
index d696f6be1c..71b761ecb2 100644
--- a/spree/core/app/models/spree/metafield_definition.rb
+++ b/spree/core/app/models/spree/metafield_definition.rb
@@ -3,6 +3,7 @@ module Spree
has_prefix_id :cfdef
include Spree::DisplayOn
+ include Spree::MetafieldDefinition::SearchCapabilities
DISPLAY = [:both, :back_end]
@@ -49,7 +50,7 @@ module Spree
#
# Ransack
#
- self.whitelisted_ransackable_attributes = %w[key namespace name resource_type display_on]
+ self.whitelisted_ransackable_attributes = %w[key namespace name resource_type display_on searchable sortable]
self.whitelisted_ransackable_scopes = %w[search multi_search]
# API naming bridge — internal columns rename in 6.0. `label` matches
diff --git a/spree/core/app/models/spree/metafield_definition/search_capabilities.rb b/spree/core/app/models/spree/metafield_definition/search_capabilities.rb
new file mode 100644
index 0000000000..d97c2634fc
--- /dev/null
+++ b/spree/core/app/models/spree/metafield_definition/search_capabilities.rb
@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Spree
+ class MetafieldDefinition
+ module SearchCapabilities
+ extend ActiveSupport::Concern
+
+ included do
+ attribute :searchable, :boolean, default: false
+ attribute :sortable, :boolean, default: false
+
+ validate :search_sort_capabilities_compatible_with_type
+
+ scope :searchable, -> { where(searchable: true) }
+ scope :sortable, -> { where(sortable: true) }
+ end
+
+ class_methods do
+ # @return [Array<String>] API field_type tokens whose STI class is searchable
+ def searchable_field_type_tokens
+ @searchable_field_type_tokens ||= build_field_type_tokens(&:searchable?)
+ end
+
+ # @return [Array<String>] API field_type tokens whose STI class is sortable
+ def sortable_field_type_tokens
+ @sortable_field_type_tokens ||= build_field_type_tokens(&:sortable?)
+ end
+
+ private
+
+ # Builds API tokens from {Spree::MetafieldDefinition.available_types}
+ # (`Spree.metafields.types` — in-memory registry, not a DB query).
+ def build_field_type_tokens(&block)
+ available_types.filter_map do |klass|
+ next unless block.call(klass)
+
+ Spree::Metafield::TYPE_CLASS_TO_TOKEN[klass.to_s] || klass.to_s
+ end
+ end
+ end
+
+ # SearchProvider document key. Namespace is length-prefixed so
+ # (a_b, c) and (a, b_c) cannot collide as the same mf_* attribute.
+ # @return [String] e.g. +mf_6_custom_label+
+ def search_key
+ "mf_#{namespace.to_s.length}_#{namespace}_#{key}"
+ end
+
+ private
+
+ def metafield_type_class
+ metafield_type.presence&.safe_constantize
+ end
+
+ def search_sort_capabilities_compatible_with_type
+ return unless searchable? || sortable?
+
+ klass = metafield_type_class
+ return if klass.nil?
+
+ %i[searchable sortable].each do |capability|
+ next unless public_send("#{capability}?")
+ next if klass.public_send("#{capability}?")
+
+ errors.add(capability, capability_error_message(capability))
+ end
+ end
+
+ def capability_error_message(capability)
+ labels = self.class
+ .public_send("#{capability}_field_type_tokens")
+ .map { |token| token.tr('_', ' ') }
+ .join(', ')
+
+ "is only supported for field types: #{labels}"
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/metafields/long_text.rb b/spree/core/app/models/spree/metafields/long_text.rb
index a58625e9c9..c022e80a65 100644
--- a/spree/core/app/models/spree/metafields/long_text.rb
+++ b/spree/core/app/models/spree/metafields/long_text.rb
@@ -2,6 +2,10 @@ module Spree
module Metafields
class LongText < Spree::Metafield
normalizes :value, with: ->(value) { value.to_s.strip }
+
+ def self.searchable?
+ true
+ end
end
end
end
diff --git a/spree/core/app/models/spree/metafields/number.rb b/spree/core/app/models/spree/metafields/number.rb
index 9c5ba3d8db..bd996a417b 100644
--- a/spree/core/app/models/spree/metafields/number.rb
+++ b/spree/core/app/models/spree/metafields/number.rb
@@ -3,6 +3,14 @@ module Spree
class Number < Spree::Metafield
validates :value, numericality: true
+ def self.searchable?
+ true
+ end
+
+ def self.sortable?
+ true
+ end
+
def serialize_value
value.to_d
end
diff --git a/spree/core/app/models/spree/metafields/short_text.rb b/spree/core/app/models/spree/metafields/short_text.rb
index 4edbd2da7a..0f941db062 100644
--- a/spree/core/app/models/spree/metafields/short_text.rb
+++ b/spree/core/app/models/spree/metafields/short_text.rb
@@ -2,6 +2,14 @@ module Spree
module Metafields
class ShortText < Spree::Metafield
normalizes :value, with: ->(value) { value.to_s.strip }
+
+ def self.searchable?
+ true
+ end
+
+ def self.sortable?
+ true
+ end
end
end
end
diff --git a/spree/core/app/models/spree/product.rb b/spree/core/app/models/spree/product.rb
index 96be729ec1..5f3f078b25 100644
--- a/spree/core/app/models/spree/product.rb
+++ b/spree/core/app/models/spree/product.rb
@@ -171,7 +171,13 @@ module Spree
next none if query.blank?
product_ids = Spree::Variant.search_by_product_name_or_sku(query).pluck(:product_id)
- where(id: product_ids.uniq.compact)
+ term = "%#{sanitize_sql_like(query.to_s.downcase)}%"
+ metafield_ids = joins(metafields: :metafield_definition)
+ .merge(Spree::MetafieldDefinition.for_resource_type('Spree::Product').searchable)
+ .where(Spree::Metafield.arel_table[:value].lower.matches(term))
+ .unscope(:order).distinct.pluck(:id)
+
+ where(id: (product_ids + metafield_ids).uniq.compact)
}
# Backward compatibility alias — remove in Spree 6.0
diff --git a/spree/core/app/models/spree/search_provider/base.rb b/spree/core/app/models/spree/search_provider/base.rb
index a15e2e40e9..6b7a10d96d 100644
--- a/spree/core/app/models/spree/search_provider/base.rb
+++ b/spree/core/app/models/spree/search_provider/base.rb
@@ -13,6 +13,11 @@ module Spree
@store = store
end
+ # @return [MetafieldSchema]
+ def metafield_schema
+ @metafield_schema ||= MetafieldSchema.new
+ end
+
# Search and paginate products. Does NOT compute filter facets — use #filters for that.
#
# @param scope [ActiveRecord::Relation] base scope (store-scoped, visibility-filtered, authorized)
diff --git a/spree/core/app/models/spree/search_provider/database.rb b/spree/core/app/models/spree/search_provider/database.rb
index 0535e4ce5f..b7f4b47791 100644
--- a/spree/core/app/models/spree/search_provider/database.rb
+++ b/spree/core/app/models/spree/search_provider/database.rb
@@ -46,6 +46,7 @@ module Spree
end
filter_facets = build_facets(scope_with_options, category: category, option_value_ids: option_value_ids, scope_before_options: scope_before_options)
+ filter_facets[:sort_options] = filter_facets[:sort_options] + metafield_sort_options
FiltersResult.new(
filters: filter_facets[:filters],
@@ -74,7 +75,7 @@ module Spree
end
def build_facets(scope, category: nil, option_value_ids: [], scope_before_options: nil)
- return { filters: [], sort_options: available_sort_options, default_sort: 'manual', total_count: scope.distinct.count } unless defined?(Spree::Api::V3::FiltersAggregator)
+ return { filters: [], sort_options: built_in_sort_options, default_sort: 'manual', total_count: scope.distinct.count } unless defined?(Spree::Api::V3::FiltersAggregator)
Spree::Api::V3::FiltersAggregator.new(
scope: scope,
@@ -98,6 +99,8 @@ module Spree
scope_method = CUSTOM_SORT_SCOPES[sort]
if scope_method
scope.reorder(nil).send(scope_method)
+ elsif (parsed = metafield_schema.parse_sort(sort))
+ apply_metafield_sort(scope, parsed)
else
# Standard Ransack sort: 'name' → 'name asc', '-name' → 'name desc'
ransack_sort = sort.split(',').map { |field|
@@ -112,8 +115,66 @@ module Spree
end
end
- def available_sort_options
- %w[price -price best_selling name -name -available_on available_on].map { |id| { id: id } }
+ # Project the ORDER BY expression into the SELECT list so PostgreSQL
+ # accepts it when DISTINCT is applied. Null-rank keeps products without
+ # the metafield last for both ASC and DESC.
+ def apply_metafield_sort(scope, parsed)
+ definition = metafield_schema.entry_for(parsed[:attribute])
+ return scope unless definition
+
+ p_table = Spree::Product.quoted_table_name
+ mf_table = Spree::Metafield.quoted_table_name
+ connection = scope.klass.connection
+ adapter = connection.adapter_name
+
+ mf_join_alias = 'sort_mf'
+
+ sort_expr = Arel.sql(metafield_sort_expression(definition.field_type, adapter))
+ null_rank = Arel.sql(metafield_sort_null_rank(definition.field_type, adapter))
+
+ direction = parsed[:direction] == 'desc' ? :desc : :asc
+ def_id = connection.quote(definition.id)
+
+ join_sql = "LEFT JOIN #{mf_table} AS #{mf_join_alias} " \
+ "ON #{mf_join_alias}.resource_type = 'Spree::Product' " \
+ "AND #{mf_join_alias}.resource_id = #{p_table}.id " \
+ "AND #{mf_join_alias}.metafield_definition_id = #{def_id}"
+
+ scope
+ .joins(join_sql)
+ .select("#{p_table}.*")
+ .select(Arel::Nodes::As.new(sort_expr, Arel.sql('mf_sort_value')))
+ .select(Arel::Nodes::As.new(null_rank, Arel.sql('mf_sort_missing')))
+ .reorder(Arel.sql('mf_sort_missing ASC'), sort_expr.send(direction))
+ end
+
+ # Type-cast sort_mf.value for numeric metafields across PostgreSQL / MySQL / SQLite.
+ def metafield_sort_expression(field_type, adapter_name)
+ column = 'sort_mf.value'
+ return column unless field_type == 'number'
+
+ case adapter_name
+ when /PostgreSQL/i
+ "#{column}::numeric"
+ when /Mysql|Trilogy/i
+ "CAST(#{column} AS DECIMAL(30, 10))"
+ else
+ "CAST(#{column} AS REAL)"
+ end
+ end
+
+ # NULL-rank so products missing the metafield sort last (Meilisearch parity).
+ # Projected as mf_sort_missing because PostgreSQL rejects (alias IS NULL) in ORDER BY.
+ def metafield_sort_null_rank(field_type, adapter_name)
+ "(#{metafield_sort_expression(field_type, adapter_name)} IS NULL)"
+ end
+
+ def built_in_sort_options
+ %w[price -price best_selling name -name -available_on available_on].map { |id| { id: id, label: nil } }
+ end
+
+ def metafield_sort_options
+ metafield_schema.sort_options
end
end
end
diff --git a/spree/core/app/models/spree/search_provider/meilisearch.rb b/spree/core/app/models/spree/search_provider/meilisearch.rb
index ffe76bd0ec..a2382b31c7 100644
--- a/spree/core/app/models/spree/search_provider/meilisearch.rb
+++ b/spree/core/app/models/spree/search_provider/meilisearch.rb
@@ -51,7 +51,7 @@ module Spree
unless ms_result
return FiltersResult.new(
filters: [],
- sort_options: available_sort_options.map { |id| { id: id } },
+ sort_options: built_in_and_metafield_sort_options,
default_sort: 'manual',
total_count: 0
)
@@ -59,7 +59,7 @@ module Spree
FiltersResult.new(
filters: build_facet_response(facet_distribution),
- sort_options: available_sort_options.map { |id| { id: id } },
+ sort_options: built_in_and_metafield_sort_options,
default_sort: 'manual',
total_count: ms_result['estimatedTotalHits'] || 0
)
@@ -91,6 +91,7 @@ module Spree
def reindex(scope = nil)
scope ||= store.products
+ @metafield_schema = MetafieldSchema.new
ensure_index_settings!
indexed = 0
@@ -180,7 +181,7 @@ module Spree
# is referenced before the index settings were refreshed — otherwise
# every search on an upgraded store returns empty until a reindex or
# the next product write.
- if e.code == 'invalid_search_filter' && !settings_refreshed
+ if %w[invalid_search_filter invalid_search_sort].include?(e.code) && !settings_refreshed
settings_refreshed = true
ensure_index_settings!
retry
@@ -240,7 +241,7 @@ module Spree
end
def searchable_attributes
- %w[name description sku option_values category_names tags]
+ %w[name description sku option_values category_names tags] + metafield_schema.searchable_attribute_keys
end
def filterable_attributes
@@ -248,7 +249,7 @@ module Spree
end
def sortable_attributes
- %w[name price created_at available_on units_sold_count]
+ %w[name price created_at available_on units_sold_count] + metafield_schema.sortable_attribute_keys
end
def facet_attributes
@@ -256,7 +257,12 @@ module Spree
end
def available_sort_options
- %w[price -price name -name -available_on available_on best_selling]
+ %w[price -price name -name -available_on available_on best_selling] + metafield_schema.sort_ids
+ end
+
+ def built_in_and_metafield_sort_options
+ %w[price -price name -name -available_on available_on best_selling].map { |id| { id: id, label: nil } } +
+ metafield_schema.sort_options
end
# Build Meilisearch filter conditions from API params.
@@ -380,6 +386,9 @@ module Spree
when '-available_on' then ['available_on:desc']
when 'available_on' then ['available_on:asc']
when 'best_selling' then ['units_sold_count:desc']
+ else
+ parsed = metafield_schema.parse_sort(sort)
+ parsed && ["#{parsed[:attribute]}:#{parsed[:direction]}"]
end
end
diff --git a/spree/core/app/presenters/spree/search_provider/product_presenter.rb b/spree/core/app/presenters/spree/search_provider/product_presenter.rb
index c1c5884cb1..b02ad40f58 100644
--- a/spree/core/app/presenters/spree/search_provider/product_presenter.rb
+++ b/spree/core/app/presenters/spree/search_provider/product_presenter.rb
@@ -75,7 +75,27 @@ module Spree
available_on: product.available_on&.iso8601,
created_at: product.created_at&.iso8601,
updated_at: product.updated_at&.iso8601
- }
+ }.merge(metafield_document_attributes)
+ end
+
+ # Flat mf_* hash for searchable ∪ sortable metafields (Meilisearch docs).
+ def metafield_document_attributes
+ @metafield_document_attributes ||= product.metafields.filter_map do |metafield|
+ definition = metafield.metafield_definition
+ next unless definition&.searchable? || definition&.sortable?
+
+ [definition.search_key, metafield_index_value(metafield, definition.field_type)]
+ end.to_h
+ end
+
+ def metafield_index_value(metafield, field_type)
+ serialized = metafield.serialize_value
+ case field_type
+ when 'number'
+ serialized.to_f
+ else
+ serialized.to_s
+ end
end
# Returns all market × locale pairs for this store
diff --git a/spree/core/app/services/spree/search_provider/metafield_schema.rb b/spree/core/app/services/spree/search_provider/metafield_schema.rb
new file mode 100644
index 0000000000..fd7cdbdfe4
--- /dev/null
+++ b/spree/core/app/services/spree/search_provider/metafield_schema.rb
@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Spree
+ module SearchProvider
+ # Product metafield definitions that participate in search/sort.
+ class MetafieldSchema
+ # @return [Hash{String => Spree::MetafieldDefinition}]
+ def entries
+ @entries ||= product_definitions.index_by(&:search_key)
+ end
+
+ # @return [Array<String>]
+ def searchable_attribute_keys
+ @searchable_attribute_keys ||= entries.each_value.filter_map do |definition|
+ definition.search_key if definition.searchable?
+ end
+ end
+
+ # @return [Array<String>]
+ def sortable_attribute_keys
+ @sortable_attribute_keys ||= entries.each_value.filter_map do |definition|
+ definition.search_key if definition.sortable?
+ end
+ end
+
+ # @param attribute_key [String]
+ # @return [Spree::MetafieldDefinition, nil]
+ def entry_for(attribute_key)
+ entries[attribute_key.to_s]
+ end
+
+ # @return [Array<String>]
+ def sort_ids
+ @sort_ids ||= sortable_attribute_keys.flat_map { |key| [key, "-#{key}"] }
+ end
+
+ # @return [Array<Hash>] +{ id:, label: }+
+ def sort_options
+ @sort_options ||= entries.each_value.select(&:sortable?).flat_map do |definition|
+ key = definition.search_key
+ name = definition.name.presence || key
+
+ [
+ { id: key, label: sort_option_label(name, definition.field_type, :asc) },
+ { id: "-#{key}", label: sort_option_label(name, definition.field_type, :desc) }
+ ]
+ end
+ end
+
+ # @param sort [String, nil]
+ # @return [Hash, nil] { attribute:, direction: 'asc'|'desc' }
+ def parse_sort(sort)
+ value = sort.to_s.strip
+ return if value.blank?
+
+ attribute = value.delete_prefix('-')
+ definition = entry_for(attribute)
+ return unless definition&.sortable?
+
+ {
+ attribute: attribute,
+ direction: value.start_with?('-') ? 'desc' : 'asc'
+ }
+ end
+
+ # Stamp for Store API filters cache keys.
+ #
+ # @return [String]
+ def schema_version
+ @schema_version ||= [
+ entries.size,
+ entries.each_value.filter_map(&:updated_at).max&.utc&.iso8601(6)
+ ].join('-')
+ end
+
+ private
+
+ def product_definitions
+ scope = Spree::MetafieldDefinition.for_resource_type('Spree::Product')
+ scope.where(searchable: true).or(scope.where(sortable: true))
+ end
+
+ def sort_option_label(name, field_type, direction)
+ suffix =
+ if field_type == 'number'
+ direction == :asc ? Spree.t(:sort_low_to_high) : Spree.t(:sort_high_to_low)
+ else
+ direction == :asc ? Spree.t(:sort_a_to_z) : Spree.t(:sort_z_to_a)
+ end
+ "#{name} (#{suffix})"
+ end
+ end
+ end
+end
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index 87af144a8e..1e676d5296 100644
--- a/spree/core/config/locales/en.yml
+++ b/spree/core/config/locales/en.yml
@@ -71,6 +71,8 @@ en:
quantity: Quantity
spree/metafield_definition:
namespace: Namespace
+ searchable: Searchable
+ sortable: Sortable
spree/option_type:
filterable: Filterable
kind: Kind
@@ -1479,7 +1481,11 @@ en:
skus: SKUs
slug: Slug
social: Social
+ sort_a_to_z: A-Z
sort_by: Sort by
+ sort_high_to_low: high-low
+ sort_low_to_high: low-high
+ sort_z_to_a: Z-A
source: Source
special_instructions: Special Instructions
split: Split
diff --git a/spree/core/db/migrate/20260722000001_add_searchable_sortable_to_spree_metafield_definitions.rb b/spree/core/db/migrate/20260722000001_add_searchable_sortable_to_spree_metafield_definitions.rb
new file mode 100644
index 0000000000..1970cae16e
--- /dev/null
+++ b/spree/core/db/migrate/20260722000001_add_searchable_sortable_to_spree_metafield_definitions.rb
@@ -0,0 +1,6 @@
+class AddSearchableSortableToSpreeMetafieldDefinitions < ActiveRecord::Migration[7.2]
+ def change
+ add_column :spree_metafield_definitions, :searchable, :boolean, if_not_exists: true
+ add_column :spree_metafield_definitions, :sortable, :boolean, if_not_exists: true
+ end
+end
diff --git a/spree/core/lib/spree/permitted_attributes.rb b/spree/core/lib/spree/permitted_attributes.rb
index ecf90b0281..5c9851ca9e 100644
--- a/spree/core/lib/spree/permitted_attributes.rb
+++ b/spree/core/lib/spree/permitted_attributes.rb
@@ -152,7 +152,11 @@ module Spree
@@metafield_attributes = [:id, :value, :type, :metafield_definition_id, :_destroy]
- @@metafield_definition_attributes = [:key, :name, :namespace, :metafield_type, :resource_type, :display_on]
+ @@metafield_definition_attributes = [
+ :key, :name, :namespace, :metafield_type, :resource_type, :display_on,
+ :searchable, :sortable
+ ]
+
@@option_type_attributes = [:name, :presentation, :position, :filterable, :kind,
option_values_attributes: [:id, :name, :presentation, :position, :color_code, :image, :_destroy]]
diff --git a/spree/core/lib/spree/testing_support/factories/metafield_definition_factory.rb b/spree/core/lib/spree/testing_support/factories/metafield_definition_factory.rb
index 178ce23f60..341e6f5095 100644
--- a/spree/core/lib/spree/testing_support/factories/metafield_definition_factory.rb
+++ b/spree/core/lib/spree/testing_support/factories/metafield_definition_factory.rb
@@ -6,6 +6,8 @@ FactoryBot.define do
metafield_type { 'Spree::Metafields::ShortText' }
resource_type { 'Spree::Product' }
display_on { 'both' }
+ searchable { false }
+ sortable { false }
trait :front_end_only do
display_on { 'front_end' }
@@ -51,6 +53,14 @@ FactoryBot.define do
name { 'Metadata' }
end
+ trait :searchable do
+ searchable { true }
+ end
+
+ trait :sortable do
+ sortable { true }
+ end
+
trait :for_variant do
resource_type { 'Spree::Variant' }
key { 'variant_custom' }
diff --git a/spree/core/spec/models/spree/metafield_definition_spec.rb b/spree/core/spec/models/spree/metafield_definition_spec.rb
index a8190d6f45..542a50b38f 100644
--- a/spree/core/spec/models/spree/metafield_definition_spec.rb
+++ b/spree/core/spec/models/spree/metafield_definition_spec.rb
@@ -9,6 +9,8 @@ RSpec.describe Spree::MetafieldDefinition, type: :model do
let!(:back_end_definition) { create(:metafield_definition, :back_end_only) }
let!(:product_definition) { create(:metafield_definition, resource_type: 'Spree::Product') }
let!(:variant_definition) { create(:metafield_definition, :for_variant) }
+ let!(:searchable_definition) { create(:metafield_definition, :searchable, key: 'searchable_field') }
+ let!(:sortable_definition) { create(:metafield_definition, :sortable, key: 'sortable_field') }
describe '.available' do
it 'returns only both definitions (from DisplayOn concern)' do
@@ -41,6 +43,104 @@ RSpec.describe Spree::MetafieldDefinition, type: :model do
expect(described_class.for_resource_type('Spree::Variant')).not_to include(product_definition)
end
end
+
+ describe '.searchable' do
+ it 'returns only searchable definitions' do
+ expect(described_class.searchable).to include(searchable_definition)
+ expect(described_class.searchable).not_to include(product_definition)
+ end
+ end
+
+ describe '.sortable' do
+ it 'returns only sortable definitions' do
+ expect(described_class.sortable).to include(sortable_definition)
+ expect(described_class.sortable).not_to include(product_definition)
+ end
+ end
+ end
+
+ describe 'searchable / sortable validations' do
+ it 'allows searchable on short_text' do
+ definition = build(:metafield_definition, :short_text_field, searchable: true)
+ expect(definition).to be_valid
+ end
+
+ it 'allows searchable on long_text' do
+ definition = build(:metafield_definition, :long_text_field, searchable: true)
+ expect(definition).to be_valid
+ end
+
+ it 'rejects searchable on rich_text' do
+ definition = build(:metafield_definition, :rich_text_field, searchable: true)
+ expect(definition).not_to be_valid
+ expect(definition.errors[:searchable].first).to include('short text', 'long text', 'number')
+ end
+
+ it 'rejects searchable on boolean' do
+ definition = build(:metafield_definition, :boolean_field, searchable: true)
+ expect(definition).not_to be_valid
+ expect(definition.errors[:searchable]).to be_present
+ end
+
+ it 'allows sortable on short_text and number' do
+ expect(build(:metafield_definition, :short_text_field, sortable: true)).to be_valid
+ expect(build(:metafield_definition, :number_field, sortable: true)).to be_valid
+ end
+
+ it 'rejects sortable on long_text' do
+ definition = build(:metafield_definition, :long_text_field, sortable: true)
+ expect(definition).not_to be_valid
+ expect(definition.errors[:sortable].first).to include('short text', 'number')
+ expect(definition.errors[:sortable].first).not_to include('long text')
+ end
+
+ it 'rejects changing metafield_type to a non-searchable class while searchable stays true' do
+ definition = create(:metafield_definition, :short_text_field, searchable: true)
+ definition.field_type = 'boolean'
+ expect(definition).not_to be_valid
+ expect(definition.errors[:searchable]).to be_present
+ end
+
+ it 'rejects changing metafield_type to a non-sortable class while sortable stays true' do
+ definition = create(:metafield_definition, :short_text_field, sortable: true)
+ definition.field_type = 'long_text'
+ expect(definition).not_to be_valid
+ expect(definition.errors[:sortable]).to be_present
+ end
+ end
+
+ describe '.searchable_field_type_tokens / .sortable_field_type_tokens' do
+ it 'derives tokens from metafield type class capabilities' do
+ expect(described_class.searchable_field_type_tokens).to match_array(%w[short_text long_text number])
+ expect(described_class.sortable_field_type_tokens).to match_array(%w[short_text number])
+ end
+ end
+
+ describe '#search_key' do
+ it 'returns the SearchProvider attribute key with a length-prefixed namespace' do
+ metafield_definition = build(:metafield_definition, namespace: 'custom', key: 'material')
+ expect(metafield_definition.search_key).to eq('mf_6_custom_material')
+ end
+
+ it 'produces distinct keys when namespace/key underscore boundaries differ' do
+ left = build(:metafield_definition, namespace: 'a_b', key: 'c')
+ right = build(:metafield_definition, namespace: 'a', key: 'b_c')
+
+ expect(left.search_key).to eq('mf_3_a_b_c')
+ expect(right.search_key).to eq('mf_1_a_b_c')
+ expect(left.search_key).not_to eq(right.search_key)
+ end
+ end
+
+ describe 'Ransack allowlist' do
+ it 'allows filtering by searchable and sortable' do
+ matching = create(:metafield_definition, :short_text_field, :searchable, :sortable, key: 'ransack_match')
+ create(:metafield_definition, :short_text_field, key: 'ransack_other')
+
+ result = described_class.ransack(searchable_eq: true, sortable_eq: true).result
+ expect(result).to include(matching)
+ expect(result.map(&:key)).not_to include('ransack_other')
+ end
end
describe '#csv_header_name' do
diff --git a/spree/core/spec/models/spree/metafields/boolean_spec.rb b/spree/core/spec/models/spree/metafields/boolean_spec.rb
index a6aad76275..f1aab6cd91 100644
--- a/spree/core/spec/models/spree/metafields/boolean_spec.rb
+++ b/spree/core/spec/models/spree/metafields/boolean_spec.rb
@@ -24,4 +24,11 @@ describe Spree::Metafields::Boolean, type: :model do
expect(metafield.csv_value).to eq('Yes')
end
end
+
+ describe '.searchable? / .sortable?' do
+ it 'is neither searchable nor sortable (filterable in Phase 6)' do
+ expect(described_class.searchable?).to eq(false)
+ expect(described_class.sortable?).to eq(false)
+ end
+ end
end
diff --git a/spree/core/spec/models/spree/metafields/long_text_spec.rb b/spree/core/spec/models/spree/metafields/long_text_spec.rb
new file mode 100644
index 0000000000..9b438e05fe
--- /dev/null
+++ b/spree/core/spec/models/spree/metafields/long_text_spec.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Spree::Metafields::LongText, type: :model do
+ describe '.searchable? / .sortable?' do
+ it 'is searchable but not sortable' do
+ expect(described_class.searchable?).to eq(true)
+ expect(described_class.sortable?).to eq(false)
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/metafields/number_spec.rb b/spree/core/spec/models/spree/metafields/number_spec.rb
index 3f1f941e48..5de0bcea5e 100644
--- a/spree/core/spec/models/spree/metafields/number_spec.rb
+++ b/spree/core/spec/models/spree/metafields/number_spec.rb
@@ -26,4 +26,11 @@ describe Spree::Metafields::Number, type: :model do
expect(metafield.csv_value).to eq('123.0')
end
end
+
+ describe '.searchable? / .sortable?' do
+ it 'is searchable and sortable' do
+ expect(described_class.searchable?).to eq(true)
+ expect(described_class.sortable?).to eq(true)
+ end
+ end
end
diff --git a/spree/core/spec/models/spree/metafields/short_text_spec.rb b/spree/core/spec/models/spree/metafields/short_text_spec.rb
new file mode 100644
index 0000000000..fd32e84ffa
--- /dev/null
+++ b/spree/core/spec/models/spree/metafields/short_text_spec.rb
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Spree::Metafields::ShortText, type: :model do
+ describe '.searchable? / .sortable?' do
+ it 'is searchable and sortable' do
+ expect(described_class.searchable?).to eq(true)
+ expect(described_class.sortable?).to eq(true)
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/product_spec.rb b/spree/core/spec/models/spree/product_spec.rb
index 1fa01f5624..29ca06cbda 100644
--- a/spree/core/spec/models/spree/product_spec.rb
+++ b/spree/core/spec/models/spree/product_spec.rb
@@ -2260,4 +2260,23 @@ describe Spree::Product, type: :model do
end
end
end
+
+ describe '.search' do
+ let!(:matching) { create(:product, name: 'Unrelated Name', store: store) }
+ let!(:other) { create(:product, name: 'Other Product', store: store) }
+ let!(:definition) do
+ create(:metafield_definition, :short_text_field, :searchable,
+ namespace: 'custom', key: 'pinyin_name')
+ end
+
+ before do
+ matching.set_metafield(definition, 'hong-ku-zi')
+ other.set_metafield(definition, 'something-else')
+ end
+
+ it 'finds products by searchable metafield value via plain SQL' do
+ expect(described_class.search('hong-ku')).to include(matching)
+ expect(described_class.search('hong-ku')).not_to include(other)
+ end
+ end
end
diff --git a/spree/core/spec/models/spree/search_provider/database_spec.rb b/spree/core/spec/models/spree/search_provider/database_spec.rb
index 9e759ecf77..3d56d15cee 100644
--- a/spree/core/spec/models/spree/search_provider/database_spec.rb
+++ b/spree/core/spec/models/spree/search_provider/database_spec.rb
@@ -194,6 +194,94 @@ module Spree
expect(result.products).not_to include(product_3)
end
end
+
+ context 'with searchable metafields' do
+ let!(:definition) do
+ create(:metafield_definition, :short_text_field, :searchable,
+ namespace: 'custom', key: 'label')
+ end
+
+ before do
+ product_2.set_metafield(definition, 'wool-blend')
+ end
+
+ it 'finds products by searchable metafield value' do
+ result = provider.search_and_filter(scope: scope, query: 'wool')
+ expect(result.products).to include(product_2)
+ expect(result.products).not_to include(product_1, product_3)
+ end
+ end
+
+ context 'with sortable metafields' do
+ let!(:definition) do
+ create(:metafield_definition, :short_text_field, :sortable,
+ namespace: 'custom', key: 'label')
+ end
+
+ before do
+ product_1.set_metafield(definition, 'charlie')
+ product_2.set_metafield(definition, 'alpha')
+ product_3.set_metafield(definition, 'bravo')
+ end
+
+ it 'sorts ascending by mf_* attribute' do
+ result = provider.search_and_filter(scope: scope, sort: 'mf_6_custom_label')
+ expect(result.products.map(&:id)).to eq([product_2.id, product_3.id, product_1.id])
+ end
+
+ it 'sorts descending by -mf_* attribute' do
+ result = provider.search_and_filter(scope: scope, sort: '-mf_6_custom_label')
+ expect(result.products.map(&:id)).to eq([product_1.id, product_3.id, product_2.id])
+ end
+
+ it 'sorts with Ransack filters present (SELECT DISTINCT compatible)' do
+ result = provider.search_and_filter(
+ scope: scope,
+ filters: { 'name_cont' => 'Blue' },
+ sort: 'mf_6_custom_label'
+ )
+ expect(result.products.map(&:id)).to eq([product_3.id, product_1.id])
+ end
+
+ context 'with missing metafield values' do
+ before do
+ product_2.metafields.destroy_all
+ end
+
+ it 'keeps missing values last when sorting ascending' do
+ result = provider.search_and_filter(scope: scope, sort: 'mf_6_custom_label')
+ expect(result.products.map(&:id)).to eq([product_3.id, product_1.id, product_2.id])
+ end
+
+ it 'keeps missing values last when sorting descending' do
+ result = provider.search_and_filter(scope: scope, sort: '-mf_6_custom_label')
+ expect(result.products.map(&:id)).to eq([product_1.id, product_3.id, product_2.id])
+ end
+ end
+ end
+
+ context 'with sortable number metafields' do
+ let!(:definition) do
+ create(:metafield_definition, :number_field, :sortable,
+ namespace: 'custom', key: 'weight')
+ end
+
+ before do
+ product_1.set_metafield(definition, '10')
+ product_2.set_metafield(definition, '2')
+ product_3.set_metafield(definition, '3')
+ end
+
+ it 'sorts ascending numerically rather than lexicographically' do
+ result = provider.search_and_filter(scope: scope, sort: 'mf_6_custom_weight')
+ expect(result.products.map(&:id)).to eq([product_2.id, product_3.id, product_1.id])
+ end
+
+ it 'sorts descending numerically' do
+ result = provider.search_and_filter(scope: scope, sort: '-mf_6_custom_weight')
+ expect(result.products.map(&:id)).to eq([product_1.id, product_3.id, product_2.id])
+ end
+ end
end
describe '#filters' do
@@ -211,6 +299,24 @@ module Spree
expect(ids).to include('price', '-price', 'best_selling')
end
+ context 'with sortable metafield definitions' do
+ let!(:definition) do
+ create(:metafield_definition, :short_text_field, :sortable,
+ namespace: 'custom', key: 'label', name: 'Material')
+ end
+
+ it 'includes metafield sort options' do
+ ids = result.sort_options.map { |o| o[:id] }
+ expect(ids).to include('mf_6_custom_label', '-mf_6_custom_label')
+ end
+
+ it 'includes human-readable labels for metafield sort options' do
+ by_id = result.sort_options.index_by { |o| o[:id] }
+ expect(by_id['mf_6_custom_label'][:label]).to eq("Material (#{Spree.t(:sort_a_to_z)})")
+ expect(by_id['-mf_6_custom_label'][:label]).to eq("Material (#{Spree.t(:sort_z_to_a)})")
+ end
+ end
+
it 'returns total count' do
expect(result.total_count).to eq(3)
end
@@ -247,5 +353,19 @@ module Spree
expect { provider.reindex(store.products) }.not_to raise_error
end
end
+
+ describe 'metafield sort SQL helpers' do
+ it 'casts numeric metafields per adapter' do
+ expect(provider.send(:metafield_sort_expression, 'number', 'PostgreSQL')).to eq('sort_mf.value::numeric')
+ expect(provider.send(:metafield_sort_expression, 'number', 'Mysql2')).to eq('CAST(sort_mf.value AS DECIMAL(30, 10))')
+ expect(provider.send(:metafield_sort_expression, 'number', 'SQLite')).to eq('CAST(sort_mf.value AS REAL)')
+ expect(provider.send(:metafield_sort_expression, 'short_text', 'PostgreSQL')).to eq('sort_mf.value')
+ end
+
+ it 'builds a null-rank expression from the sort expression' do
+ expect(provider.send(:metafield_sort_null_rank, 'number', 'PostgreSQL')).to eq('(sort_mf.value::numeric IS NULL)')
+ expect(provider.send(:metafield_sort_null_rank, 'short_text', 'PostgreSQL')).to eq('(sort_mf.value IS NULL)')
+ end
+ end
end
end
diff --git a/spree/core/spec/models/spree/search_provider/meilisearch_spec.rb b/spree/core/spec/models/spree/search_provider/meilisearch_spec.rb
index e2a73d2976..9c6a529a0f 100644
--- a/spree/core/spec/models/spree/search_provider/meilisearch_spec.rb
+++ b/spree/core/spec/models/spree/search_provider/meilisearch_spec.rb
@@ -147,8 +147,8 @@ module Spree
end
end
- # A newly added filterable attribute (e.g. `preorder`) referenced before
- # the index settings were refreshed rejects the whole query on upgraded
+ # A newly added filterable or sortable attribute referenced before the
+ # index settings were refreshed rejects the whole query on upgraded
# stores — the provider must push settings and retry instead of serving
# an empty listing until a reindex.
context 'when a filter attribute is not yet filterable' do
@@ -173,6 +173,29 @@ module Spree
expect(result.products).to include(product_1, product_2)
end
end
+
+ context 'when a sort attribute is not yet sortable' do
+ before do
+ error = ::Meilisearch::ApiError.new(
+ 400, 'Bad Request',
+ { 'code' => 'invalid_search_sort', 'message' => 'Attribute `mf_6_custom_label` is not sortable.' }
+ )
+ calls = 0
+ allow(mock_index).to receive(:search) do
+ calls += 1
+ raise error if calls == 1
+
+ ms_response
+ end
+ end
+
+ it 'pushes index settings and retries the search once' do
+ expect(mock_index).to receive(:update_sortable_attributes)
+
+ result = provider.search_and_filter(scope: store.products, query: 'shirt', sort: 'mf_6_custom_label')
+ expect(result.products).to include(product_1, product_2)
+ end
+ end
end
describe '#filters' do
@@ -334,5 +357,26 @@ module Spree
provider.reindex(store.products)
end
end
+
+ describe 'metafield searchable / sortable settings' do
+ let!(:definition) do
+ create(:metafield_definition, :short_text_field, :searchable, :sortable,
+ namespace: 'custom', key: 'label')
+ end
+
+ it 'includes mf_* in searchable and sortable attributes' do
+ expect(provider.send(:searchable_attributes)).to include('mf_6_custom_label')
+ expect(provider.send(:sortable_attributes)).to include('mf_6_custom_label')
+ end
+
+ it 'does not put mf_* on filterable attributes' do
+ expect(provider.send(:filterable_attributes)).not_to include('mf_6_custom_label')
+ end
+
+ it 'maps mf_* sort params without namespace resolution' do
+ expect(provider.send(:sort_mapping, 'mf_6_custom_label')).to eq(['mf_6_custom_label:asc'])
+ expect(provider.send(:sort_mapping, '-mf_6_custom_label')).to eq(['mf_6_custom_label:desc'])
+ end
+ end
end
end
diff --git a/spree/core/spec/presenters/spree/search_provider/product_presenter_spec.rb b/spree/core/spec/presenters/spree/search_provider/product_presenter_spec.rb
index 3ff3a630c8..ec2f55fdff 100644
--- a/spree/core/spec/presenters/spree/search_provider/product_presenter_spec.rb
+++ b/spree/core/spec/presenters/spree/search_provider/product_presenter_spec.rb
@@ -184,6 +184,72 @@ module Spree
end
end
end
+
+ context 'with searchable / sortable metafields' do
+ let!(:searchable_def) do
+ create(:metafield_definition, :short_text_field, :searchable,
+ namespace: 'custom', key: 'pinyin_name', name: 'Pinyin')
+ end
+ let!(:sortable_def) do
+ create(:metafield_definition, :number_field, :sortable,
+ namespace: 'custom', key: 'priority', name: 'Priority')
+ end
+ let!(:ignored_def) do
+ create(:metafield_definition, :short_text_field,
+ namespace: 'custom', key: 'internal_note', name: 'Note')
+ end
+
+ before do
+ product.set_metafield(searchable_def, 'mao-tai')
+ product.set_metafield(sortable_def, '10')
+ product.set_metafield(ignored_def, 'secret')
+ end
+
+ it 'indexes searchable and sortable metafield values as mf_* attributes' do
+ doc = documents.first
+ expect(doc['mf_6_custom_pinyin_name']).to eq('mao-tai')
+ expect(doc['mf_6_custom_priority']).to eq(10.0)
+ expect(doc).not_to have_key('mf_6_custom_internal_note')
+ end
+
+ it 'uses the same mf_* attributes on every market/locale document' do
+ create(:market, store: store, name: 'US', currency: 'USD', default_locale: 'en')
+ create(:market, store: store, name: 'EU', currency: 'EUR', default_locale: 'de')
+ create(:price, variant: product.master, amount: 9.99, currency: 'EUR')
+
+ docs = described_class.new(product.reload, store.reload).call
+ expect(docs.size).to be > 1
+
+ mf_keys = docs.first.keys.grep(/\Amf_/)
+ docs.each do |doc|
+ expect(doc.slice(*mf_keys)).to eq(docs.first.slice(*mf_keys))
+ end
+ end
+
+ it 'casts number metafield values to Float' do
+ decimal_def = create(:metafield_definition, :number_field, :sortable,
+ namespace: 'custom', key: 'rating', name: 'Rating')
+ product.set_metafield(decimal_def, '42.5')
+
+ doc = described_class.new(product.reload, store).call.first
+ expect(doc['mf_6_custom_rating']).to eq(42.5)
+ end
+
+ it 'omits registered keys when the product has no value' do
+ create(:metafield_definition, :short_text_field, :searchable,
+ namespace: 'custom', key: 'origin', name: 'Origin')
+
+ doc = described_class.new(product.reload, store).call.first
+ expect(doc).not_to have_key('mf_6_custom_origin')
+ end
+
+ it 'includes no mf_* attributes when no definitions are searchable or sortable' do
+ Spree::MetafieldDefinition.destroy_all
+
+ doc = described_class.new(product.reload, store).call.first
+ expect(doc.keys.grep(/\Amf_/)).to be_empty
+ end
+ end
end
end
end
diff --git a/spree/core/spec/services/spree/search_provider/metafield_schema_spec.rb b/spree/core/spec/services/spree/search_provider/metafield_schema_spec.rb
new file mode 100644
index 0000000000..1322947989
--- /dev/null
+++ b/spree/core/spec/services/spree/search_provider/metafield_schema_spec.rb
@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Spree::SearchProvider::MetafieldSchema do
+ subject(:schema) { described_class.new }
+
+ describe 'accessors' do
+ it 'exposes definitions by mf_* key' do
+ definition = create(:metafield_definition, :number_field, :sortable, :searchable,
+ namespace: 'custom', key: 'weight', name: 'Weight')
+
+ entry = schema.entry_for('mf_6_custom_weight')
+
+ expect(entry).to eq(definition)
+ expect(schema.searchable_attribute_keys).to include('mf_6_custom_weight')
+ expect(schema.sortable_attribute_keys).to include('mf_6_custom_weight')
+ end
+ end
+
+ describe '#entries' do
+ it 'exposes participating definitions keyed by search_key' do
+ label = create(:metafield_definition, :short_text_field, :searchable, namespace: 'custom', key: 'label')
+ priority = create(:metafield_definition, :number_field, :sortable, namespace: 'custom', key: 'priority')
+
+ expect(schema.entries).to include(
+ 'mf_6_custom_label' => label,
+ 'mf_6_custom_priority' => priority
+ )
+ end
+ end
+
+ describe '#parse_sort' do
+ before do
+ create(:metafield_definition, :short_text_field, :sortable, namespace: 'custom', key: 'name')
+ end
+
+ it 'parses ascending and descending mf_* sorts' do
+ expect(schema.parse_sort('mf_6_custom_name')).to eq(attribute: 'mf_6_custom_name', direction: 'asc')
+ expect(schema.parse_sort('-mf_6_custom_name')).to eq(attribute: 'mf_6_custom_name', direction: 'desc')
+ end
+
+ it 'returns nil for unknown or non-sortable keys' do
+ create(:metafield_definition, :short_text_field, :searchable, namespace: 'custom', key: 'notes')
+
+ expect(schema.parse_sort('mf_6_custom_unknown')).to be_nil
+ expect(schema.parse_sort('name')).to be_nil
+ expect(schema.parse_sort('mf_6_custom_notes')).to be_nil
+ end
+ end
+
+ describe '#sort_ids' do
+ before do
+ create(:metafield_definition, :short_text_field, :sortable, namespace: 'custom', key: 'color')
+ create(:metafield_definition, :number_field, :sortable, namespace: 'custom', key: 'weight')
+ end
+
+ it 'returns both ascending and descending variants' do
+ expect(schema.sort_ids).to contain_exactly(
+ 'mf_6_custom_color', '-mf_6_custom_color',
+ 'mf_6_custom_weight', '-mf_6_custom_weight'
+ )
+ end
+ end
+
+ describe '#sort_options' do
+ it 'returns labeled ascending and descending options for text fields' do
+ create(:metafield_definition, :short_text_field, :sortable,
+ namespace: 'custom', key: 'label', name: 'Material')
+
+ expect(schema.sort_options).to include(
+ { id: 'mf_6_custom_label', label: "Material (#{Spree.t(:sort_a_to_z)})" },
+ { id: '-mf_6_custom_label', label: "Material (#{Spree.t(:sort_z_to_a)})" }
+ )
+ end
+
+ it 'returns low-high labels for number fields' do
+ create(:metafield_definition, :number_field, :sortable,
+ namespace: 'custom', key: 'weight', name: 'Weight')
+
+ expect(schema.sort_options).to include(
+ { id: 'mf_6_custom_weight', label: "Weight (#{Spree.t(:sort_low_to_high)})" },
+ { id: '-mf_6_custom_weight', label: "Weight (#{Spree.t(:sort_high_to_low)})" }
+ )
+ end
+
+ it 'translates direction suffixes for the current locale' do
+ create(:metafield_definition, :number_field, :sortable,
+ namespace: 'custom', key: 'weight', name: 'Weight')
+
+ I18n.backend.store_translations(:pl, spree: {
+ sort_low_to_high: 'od najniższej',
+ sort_high_to_low: 'od najwyższej'
+ })
+
+ I18n.locale = :pl
+ Spree::Current.locale = 'pl'
+ labels = schema.sort_options.index_by { |o| o[:id] }
+
+ expect(labels['mf_6_custom_weight'][:label]).to eq('Weight (od najniższej)')
+ expect(labels['-mf_6_custom_weight'][:label]).to eq('Weight (od najwyższej)')
+ ensure
+ I18n.locale = I18n.default_locale
+ Spree::Current.locale = nil
+ end
+ end
+
+ describe '#schema_version' do
+ it 'returns a stamp derived from participating entries' do
+ definition = create(:metafield_definition, :short_text_field, :sortable,
+ namespace: 'custom', key: 'weight')
+
+ version = schema.schema_version
+
+ expect(version).to start_with('1-')
+ expect(version).to include(definition.updated_at.utc.iso8601(6))
+ end
+ end
+end