Search Products

About

The searchProducts query enables advanced product search with support for text queries, filtering, and sorting. Use this query to:

• Implement full-text product search functionality
• Build auto-complete and suggestion interfaces
• Filter products by multiple criteria (price range, categories, attributes)
• Sort search results by relevance, price, date, or custom fields
• Implement faceted search interfaces
• Create advanced query-based product discovery

The search supports Bagisto's advanced search syntax for building complex, multi-criteria queries. It efficiently ranks results by relevance while maintaining performance across large product catalogs.

Arguments

Argument	Type	Description
query	String	Search term or advanced query string. Searches product name, description, SKU, and other fields.
first	Int	Maximum number of results per page (default: 20, max: 250).
after	String	Cursor for pagination. Returns results after this cursor.
last	Int	Maximum results for backward pagination (max: 250).
before	String	Cursor for backward pagination.
sortKey	ProductSortKeys	Sort results by: RELEVANCE, TITLE, PRICE, CREATED_AT, POPULARITY. Default: RELEVANCE
reverse	Boolean	Reverse sort order. Default: false
filters	ProductFilterInput	Advanced filters for price range, categories, tags, and custom attributes.
filter	String	JSON-encoded filter string. Supports keys like category_id to filter products by category (e.g. "{\"category_id\": \"22\"}")

Possible Returns

Field	Type	Description
edges	[ProductEdge!]!	Search result edges containing product nodes and pagination cursors.
edges.node	Product!	Product object with all searchable fields (name, description, SKU, tags).
edges.node.score	Float	Relevance score of the product match (0-1). Higher scores indicate better matches.
edges.cursor	String!	Pagination cursor for this result.
nodes	[Product!]!	Simplified array of products without edge wrapping.
pageInfo	PageInfo!	Pagination metadata.
pageInfo.hasNextPage	Boolean!	True if more results available after current page.
pageInfo.endCursor	String	Cursor of last result on page.
facets	[SearchFacet!]	Available facets for filtering (categories, price ranges, attributes).
facets.name	String!	Facet name (e.g., "category", "price_range").
facets.values	[FacetValue!]!	Available values and counts for this facet.
totalCount	Int!	Total matching products across all pages.

Filter Reference

The filter argument accepts a JSON-encoded string. You can combine multiple filters in a single object.

Available Filter Keys

Filter Key	Type	Description	Example
category_id	String	Filter by category ID	"{\"category_id\": \"22\"}"
type	String	Filter by product type (simple, configurable, virtual, downloadable, grouped, bundle)	"{\"type\": \"configurable\"}"
color	String	Filter by color attribute option ID	"{\"color\": \"3\"}"
size	String	Filter by size attribute option ID	"{\"size\": \"1\"}"
brand	String	Filter by brand attribute option ID	"{\"brand\": \"5\"}"
new	String	Filter for new products only	"{\"new\": \"1\"}"
featured	String	Filter for featured products only	"{\"featured\": \"1\"}"

Combining Filters

Pass multiple keys in a single JSON object:

products(filter: "{\"color\": \"5\", \"size\": \"1\", \"brand\": \"5\"}")

Sorting Reference

Use sortKey and reverse to control result ordering:

Sort	sortKey	reverse	Description
A → Z	"TITLE"	false	Alphabetical ascending
Z → A	"TITLE"	true	Alphabetical descending
Newest First	"CREATED_AT"	true	Most recently created
Oldest First	"CREATED_AT"	false	Earliest created
Cheapest First	"PRICE"	false	Lowest price first
Most Expensive First	"PRICE"	true	Highest price first

How Price Sorting Works

When sorting by PRICE, the sort is not based on the price field alone. Instead, it is based on the minimumPrice column — the effective price shown to the customer on the storefront.

minimumPrice reflects the lowest applicable price for a product after accounting for:

• Special price — if a discounted price is set, minimumPrice will reflect that instead of the regular price
• Configurable variants — for products with multiple variants, minimumPrice is the lowest price across all variants
• Regular price — if no special price or variant pricing applies, minimumPrice equals price

This means when you sort by price, you are sorting by what the customer actually sees — not the base catalog price. Always use minimumPrice in your UI when displaying the effective price alongside price-sorted results.

REST API Equivalents

Use Case	REST Endpoint	GraphQL Equivalent
New Products	/api/products?new=1&sort=created_at-desc&limit=10	products(filter: "{\"new\": \"1\"}", sortKey: "CREATED_AT", reverse: true, first: 10)
Featured Products	/api/products?sort=created_at-desc&limit=12	products(filter: "{\"featured\": \"1\"}", sortKey: "CREATED_AT", reverse: true, first: 12)
Popular by Brand	/api/products?sort=created_at-desc&brand=25&limit=12	products(filter: "{\"brand\": \"25\"}", sortKey: "CREATED_AT", reverse: true, first: 12)
All (Price Desc)	/api/products?sort=price-desc&limit=12	products(sortKey: "PRICE", reverse: true, first: 12)