ProductGroup
Represents a product group in the store, including its metadata, SEO fields, relationships, and available filters for GraphQL queries.
Type Definition
type ProductGroup {
productsCount: Int
seoDescription: String
seoTitle: String
seoKeywords: String
id: Int
title: String
handle: String
description: String
image: String
productGroups: [ProductGroup]
parent: ProductGroup
breadcrumbs: [ProductGroup]
filters: [Filter]
products: ProductConnection
}
Fields
Field | Type | Nullable | Description | Relationship |
---|---|---|---|---|
productsCount | Int | Yes | The total number of products in this product group, not affected by filters. | None |
seoDescription | String | Yes | SEO meta description for this product group. | None |
seoTitle | String | Yes | SEO meta title for this product group. | None |
seoKeywords | String | Yes | SEO meta keywords for this product group. | None |
id | Int | Yes | Unique identifier for this product group. | None |
title | String | Yes | Display name/title of this product group. | None |
handle | String | Yes | Handle (unique string or id) for this product group. | None |
description | String | Yes | HTML-formatted description of this product group. | None |
image | String | Yes | Image URL for this product group. | None |
productGroups | [ProductGroup] | Yes | Child product groups (subcategories) for this product group. | Self-referential |
parent | ProductGroup | Yes | Parent product group if it exists, otherwise null. | Self-referential |
breadcrumbs | [ProductGroup] | Yes | Breadcrumb trail (list of parent product groups) for this product group. | Self-referential |
filters | [Filter] | Yes | Available filters for this product group, or null if none are set. | Related to Filter type |
products | ProductConnection | Yes | Connection to products belonging to this product group. | Related to ProductConnection |
Relationships
- productGroups: Represents child product groups (subcategories) of this product group, allowing hierarchical navigation.
- parent: Points to the parent product group, enabling traversal up the category tree.
- breadcrumbs: Provides a list of ancestor product groups forming the breadcrumb trail for UI navigation.
- filters: Lists available filters applicable to this product group, useful for refining product queries.
- products: A connection to the products within this product group, supporting pagination and filtering.
Usage Examples
Basic Query
Fetch basic metadata and SEO information about a product group by its ID:
query {
productGroup(id: 12345) {
id
title
handle
seoTitle
seoDescription
productsCount
}
}
Field Selection
Retrieve detailed information including description, image, and SEO keywords:
query {
productGroup(id: 12345) {
title
description
image
seoKeywords
}
}
Nested Queries
Access child product groups and their titles, as well as the breadcrumb trail for navigation:
query {
productGroup(id: 12345) {
title
productGroups {
id
title
handle
}
breadcrumbs {
id
title
}
}
}
Traverse the products connection to get product details with pagination:
query {
productGroup(id: 12345) {
products(first: 5) {
edges {
node {
id
title
handle
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
Filtering and Sorting
Filter products within a product group by available filters and sort by title ascending:
query {
productGroup(id: 12345) {
filters {
id
name
type
options {
id
label
}
}
products(first: 10, filter: { priceRange: { min: 10, max: 100 } }, sort: { field: TITLE, direction: ASC }) {
edges {
node {
id
title
price
}
}
}
}
}
Note: The exact filter input structure depends on the Filter
type schema.
Implements
The ProductGroup
type does not explicitly implement any interfaces.
Connections
- products: This field returns a
ProductConnection
object, which supports pagination throughedges
andpageInfo
. Use arguments such asfirst
,after
,last
, andbefore
to paginate through products.
Example of paginating products:
query {
productGroup(id: 12345) {
products(first: 10, after: "cursorString") {
edges {
node {
id
title
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
Related Types
ProductGroup
(self-referential for parent, children, and breadcrumbs)Filter
(used in thefilters
field to represent available filters)ProductConnection
(used in theproducts
field for product listings)
Best Practices
- Use the
id
field to uniquely identify product groups in queries. - Leverage the
filters
field to dynamically build UI filter options for product listings. - Use pagination arguments on the
products
connection to efficiently load products in batches. - When displaying navigation, use
breadcrumbs
to provide users with context and easy traversal. - Avoid querying large nested structures unnecessarily to maintain query performance.
- Cache frequently requested product group metadata to reduce repeated network calls.
Notes
- All fields in
ProductGroup
are optional and may returnnull
if data is not available. - The
productsCount
field reflects the total number of products in the group without applying any filters. - The API currently requires no authentication, but this may change in future versions.
- Use appropriate error handling in your client to manage cases where fields return null or data is missing.
- The
description
field contains HTML-formatted content; sanitize or render appropriately in your UI. - The
image
field provides a URL string; ensure your application handles image loading and fallback gracefully. - Filtering and sorting capabilities depend on the schema of the related
Filter
andProductConnection
types; consult their documentation for details.
Last updated on