Component Grouping

Group components by category, lifecycle status, type, modified-by user, or label — server-side, in a single GraphQL call. Each group returns a capped preview of its components with cursor-based pagination for loading more.

Quick start

query GroupByCategory {
  component {
    componentGroups(
      groupBy: CATEGORY
      pagination: { first: 10 }
    ) {
      edges {
        node {
          key
          label
          totalCount
          components {
            edges {
              node {
                id
                name
                identifier { displayValue }
              }
            }
            pageInfo {
              hasNextPage
            }
          }
        }
      }
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

This returns up to 10 groups, each containing a preview of up to 50 components sorted by the default order (CREATED_AT DESC). Groups with more than 50 components signal overflow via components.pageInfo.hasNextPage, and the remaining items can be fetched with the componentsInGroup query.

---

When to use grouping

Use componentGroups when your integration needs to:

• Render a grouped UI — category buckets, status lanes, label-based views

• Count items per dimension — each group carries a totalCount without a separate aggregation query

• Combine grouping with filtering — pass filter or advancedFilter alongside groupBy to scope results before grouping

For flat, ungrouped lists, continue using component.findAll or component.filter.

---

Grouping dimensions

The ComponentGroupField enum defines the five available dimensions:

Value	Groups by	Group key	Group label
CATEGORY	Component category	Category UUID	Category name (e.g., "Capacitor")
LIFECYCLE_STATUS	Custom lifecycle status	Status UUID	Status name (e.g., "Design", "Production")
TYPE	Category type	ASSEMBLY, PART, or DOCUMENT	Same as key, title-cased
MODIFIED_BY	Last-modified user	User UUID	User display name
LABEL	Attached labels	Label UUID	Label display name

Sentinel groups for null values

Components that lack a value for the grouping dimension are collected into synthetic "null-bucket" groups with sentinel keys:

Dimension	Sentinel key	Label
CATEGORY	__uncategorized__	Uncategorized
LIFECYCLE_STATUS	__unknown-status__	Unknown status
TYPE	__unknown-type__	Unknown type
MODIFIED_BY	__unknown-user__	Unknown user
LABEL	__no-label__	No label

Sentinel groups always sort last in the response. Your integration should handle these keys gracefully — they are stable strings, not UUIDs.

Labels are many-to-many. A component with multiple labels appears in every label group it belongs to. The component's totalCount across label groups may exceed the library's total component count.

---

Pagination across groups

The outer componentGroups connection uses offset-based cursor pagination to page through groups:

query NextGroupPage {
  component {
    componentGroups(
      groupBy: LIFECYCLE_STATUS
      pagination: {
        first: 5
        after: "eyJvZmZzZXQiOjV9"  # endCursor from previous page
      }
    ) {
      edges {
        node { key label totalCount }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
      totalCount   # true total across all pages
    }
  }
}

totalCount on the outer connection is the total number of groups matching the active filters, not the number returned on this page. Use it for "Showing 1-5 of 12 groups" labels.

---

Loading more components in a group

Each group's components connection is capped at 50 items. When components.pageInfo.hasNextPage is true, use componentsInGroup to fetch the next batch:

query LoadMoreInGroup {
  component {
    componentsInGroup(
      groupBy: CATEGORY
      groupKey: "550e8400-e29b-41d4-a716-446655440000"
      pagination: {
        first: 50
        after: "cursor-from-last-edge"
        orderBy: { field: NAME, direction: ASC }
      }
    ) {
      edges {
        cursor
        node {
          id
          name
          identifier { displayValue }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
      totalCount
    }
  }
}

The groupKey matches the key field from the parent group. For sentinel groups, use the sentinel string directly (e.g., "__uncategorized__").

componentsInGroup uses keyset cursor pagination — pass the last edge's cursor as after to advance. The cursor encodes the sort-field value and the component ID, so it's tied to the orderBy you specify. Changing the sort field or direction invalidates previous cursors.

---

Filtering + grouping

Both filter (simple) and advancedFilter (AND/OR logic) work with componentGroups. When both are provided, advancedFilter takes priority and the simple filter is ignored.

Simple filter

query GroupReleasedParts {
  component {
    componentGroups(
      groupBy: CATEGORY
      filter: { categoryType: PART, isArchived: false }
    ) {
      edges {
        node {
          key
          label
          totalCount
        }
      }
    }
  }
}

Advanced filter

query GroupByStatusFilteredByLabel {
  component {
    componentGroups(
      groupBy: LIFECYCLE_STATUS
      advancedFilter: {
        and: [
          { labels: { name: { eq: "High Priority" } } }
          { category: { type: { eq: "PART" } } }
        ]
      }
    ) {
      edges {
        node {
          key
          label
          totalCount
        }
      }
    }
  }
}

See Searching and Filtering for the full AdvancedComponentFilterInput reference.

---

Sorting within groups

Control how components are ordered inside each group using pagination.orderBy:

query GroupSortedByName {
  component {
    componentGroups(
      groupBy: LABEL
      pagination: {
        first: 20
        orderBy: { field: NAME, direction: ASC }
      }
    ) {
      edges {
        node {
          key
          label
          components {
            edges {
              node { id name }
            }
          }
        }
      }
    }
  }
}

Available sort fields:

Field	Description
NAME	Component name (alphabetical)
CPN	Component Part Number (identifier display value)
CREATED_AT	Creation timestamp
UPDATED_AT	Last-modified timestamp

Directions: ASC, DESC

Default: When orderBy is omitted, components are sorted by CREATED_AT DESC (most recently created first). This matches the default behavior of component.findAll and component.filter.

The orderBy applies to both the initial per-group preview AND subsequent componentsInGroup calls. If you change the sort when loading more, the cursor from the previous page becomes invalid — start a fresh pagination sequence.

---

Complete API reference

ComponentGroupField

"""Fields that can be used to group components via the componentGroups query."""
enum ComponentGroupField {
  CATEGORY
  LIFECYCLE_STATUS
  TYPE
  MODIFIED_BY
  LABEL
}

componentGroups field

type ComponentQuery {
  componentGroups(
    groupBy: ComponentGroupField!
    filter: ComponentFilterInput
    advancedFilter: AdvancedComponentFilterInput
    pagination: PaginationInput
  ): ComponentGroupConnection!
}

ComponentGroupConnection

type ComponentGroupConnection {
  edges: [ComponentGroupEdge!]!
  pageInfo: PageInfo!
  """Total number of distinct groups matching the active filters, across all pages."""
  totalCount: Int!
}

type ComponentGroupEdge {
  node: ComponentGroup!
  cursor: String!
}

ComponentGroup

type ComponentGroup {
  """Stable server-defined group identifier (entity UUID or sentinel key)."""
  key: ID!

  """Human-readable group name."""
  label: String!

  """Total components in this group matching the active filters."""
  totalCount: Int!

  """Paginated component preview, capped at 50 items per group."""
  components: ComponentConnection!
}

componentsInGroup field

type ComponentQuery {
  componentsInGroup(
    groupBy: ComponentGroupField!
    groupKey: String!
    filter: ComponentFilterInput
    advancedFilter: AdvancedComponentFilterInput
    pagination: PaginationInput
  ): ComponentConnection!
}

PaginationInput

input PaginationInput {
  """Number of items to return (max 100)."""
  first: Int

  """Cursor from a previous page's endCursor."""
  after: String

  """Sort order for results."""
  orderBy: GenericOrderInput
}

input GenericOrderInput {
  field: String!
  direction: OrderDirection!
}

enum OrderDirection {
  ASC
  DESC
}

---

Next steps

• Learn about Searching and Filtering for the full filter reference

• Explore Components for create, update, and assembly operations

• Set up Webhooks to react to component changes in real-time