> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/groups.md). # Grouping entities Groups are how you slice your catalog. They are free-form tags with no hierarchy or ownership semantics. Apply them to any set of [entities](/ingesting-data-into-cortex/entities-overview/entities.md) that belong together, and use those labels to filter, report, and scope work across Cortex. Think of groups as the vocabulary you invent to describe your system. You might use them to express priority (`tier-0`, `tier-1`), stack (`python`, `java`, `kotlin`), architectural role (`backend`, `frontend`, `library`, `api`), or any other dimension that matters to your organization. Once entities are tagged, groups become a cross-cutting lens: filter a Scorecard to only Python services, build a catalog view of all tier-0 systems, or aggregate production readiness scores by tier. ## What you can do with groups **Segment entities** - Tag entities with whatever labels make sense for your org. Groups are additive; an entity can belong to any number of groups. **Filter throughout Cortex** - Use groups as inclusion or exclusion criteria in [Scorecards](/standardize/scorecards.md), [catalogs](/ingesting-data-into-cortex/catalogs.md), and [CQL reports](/standardize/cql/cql-reports.md). For example, apply a security Scorecard only to backend services, or surface a catalog view that shows only tier-0 entities. **Aggregate and report** - Break down Scorecard results by group. For example, view a Production Readiness Scorecard segmented by tier to see which tier is furthest from your standards. ## Viewing groups on an entity When you open an [entity's detail page](/ingesting-data-into-cortex/entities-overview/entities/details.md), its groups are listed in the upper-right corner. Clicking any group name takes you to a list of all other entities that share that tag.

## Defining and applying groups Groups can be created and applied via the Cortex UI, an entity descriptor YAML file, or the API. Each method has distinct behavior. ### Behavior by method There are important differences in how groups created via different methods interact with each other:

	UI	Entity descriptor	API
Visible in entity YAML
Removable via UI
Overwritten by API			—

Specifically: * Groups set in the entity descriptor YAML cannot be overwritten by an API call. * Groups created via the API do not appear in the entity descriptor YAML. * Groups created via the API cannot be removed from the Cortex UI. ### Defining and applying groups via the Cortex UI 1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details.md). 2. In the upper-right corner, click **Configure entity**. 3. Locate the **Details** section. 4. From the **Groups** drop-down menu, select a group or groups to apply to the entity. * To create a new group, type the group name into the **Search items** field, then click **Add new \[group name]**. The group is created and applied to the entity. 5. Click **Save changes**. ### Defining and applying groups via an entity descriptor Define groups as a list under `x-cortex-groups`: ```yaml x-cortex-groups: - tier-0 - language:kotlin ``` Note that group name may not contain whitespace. ### Defining and applying groups via the API Use the [Groups API](/api/readme/groups.md) to add groups to an entity programmatically. ## Troubleshooting and FAQ **When should I use groups instead of** **custom data?** Groups work best for categorical, enumerable labels, e.g. `backend` vs. `frontend` or `tier-0` vs. `tier-1`. If you need freeform or structured metadata (e.g. `availability-zones`: \[`east`, `west`]), use [custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data.md) instead. **What is the difference between `x-cortex-service-groups` and `x-cortex-groups`?** There is no functional difference. `x-cortex-service-groups` is deprecated in favor of `x-cortex-groups`, but the change is backward-compatible; existing configurations using the old key will continue to work. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/groups.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.