--- title: "Preview diff between imported semantic groups and current DB state" method: POST path: "/api/{org_id}/alerts/deduplication/semantic-groups/preview-diff" tags: ["Alerts"] --- # Preview diff between imported semantic groups and current DB state `POST /api/{org_id}/alerts/deduplication/semantic-groups/preview-diff` ## Request - Base URL: `https://api.openobserve.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.openobserve.ai/api/{org_id}/alerts/deduplication/semantic-groups/preview-diff` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) This endpoint compares the provided semantic groups with what's currently stored and returns a diff showing additions, modifications, and unchanged groups. The UI can use this to show users what will change before they commit. ## Path parameters - `org_id` string, required ## Request body - FieldAlias[] - `display` string, required: Human-readable display name (e.g., "Host", "K8s Cluster") - `fields` string[], required: List of field names that are equivalent (e.g., ["host", "hostname", "node"]) Note: Field names can overlap with other groups. First-defined group wins. - `group` string, nullable: Category/group this semantic field belongs to (e.g., "Common", "Kubernetes", "AWS", "GCP", "Azure") Used for UI organization and preset templates - `id` string, required: Unique identifier (lowercase, dash-separated, e.g., "host", "k8s-cluster") - `is_workload_type` boolean: When true, this alias is a workload-type dimension used to build identity sets. Aliases with this flag are grouped by their `group` field to form `IdentitySet` entries with `distinguish_by` populated from those alias IDs. Aliases without this flag (HTTP, Database, System, etc.) are never used as identity set discriminators. ## Response `200` Success - SemanticGroupDiff - `additions` FieldAlias[], required: Groups that exist in the imported JSON but not in DB (new) - `display` string, required: Human-readable display name (e.g., "Host", "K8s Cluster") - `fields` string[], required: List of field names that are equivalent (e.g., ["host", "hostname", "node"]) Note: Field names can overlap with other groups. First-defined group wins. - `group` string, nullable: Category/group this semantic field belongs to (e.g., "Common", "Kubernetes", "AWS", "GCP", "Azure") Used for UI organization and preset templates - `id` string, required: Unique identifier (lowercase, dash-separated, e.g., "host", "k8s-cluster") - `is_workload_type` boolean: When true, this alias is a workload-type dimension used to build identity sets. Aliases with this flag are grouped by their `group` field to form `IdentitySet` entries with `distinguish_by` populated from those alias IDs. Aliases without this flag (HTTP, Database, System, etc.) are never used as identity set discriminators. - `modifications` SemanticGroupModification[], required: Groups that exist in both but have different content - `current` FieldAlias, required: Field alias group — defines a set of field names that represent the same concept. Used for: - Mapping equivalent field names across logs, traces, and metrics (e.g., `service`, `service.name`, `app` all mean "service identity") - Incident correlation and alert dimensions - Populating `ServiceIdentityConfig` via the recommendations UI # Field Name Overlaps Field names can appear in multiple semantic groups. When extracting dimensions, the **first-defined group** takes precedence. This allows flexible configurations where a field like "service" can have different meanings in different contexts. Example: ``` // Group 1: service-primary (defined first) // field_names: ["service", "primary_service"] // // Group 2: service-backup (defined second) // field_names: ["service", "backup_service"] // // When extracting dimensions from {"service": "api"}: // → Matches "service-primary" group (first occurrence wins) ``` - `display` string, required: Human-readable display name (e.g., "Host", "K8s Cluster") - `fields` string[], required: List of field names that are equivalent (e.g., ["host", "hostname", "node"]) Note: Field names can overlap with other groups. First-defined group wins. - `group` string, nullable: Category/group this semantic field belongs to (e.g., "Common", "Kubernetes", "AWS", "GCP", "Azure") Used for UI organization and preset templates - `id` string, required: Unique identifier (lowercase, dash-separated, e.g., "host", "k8s-cluster") - `is_workload_type` boolean: When true, this alias is a workload-type dimension used to build identity sets. Aliases with this flag are grouped by their `group` field to form `IdentitySet` entries with `distinguish_by` populated from those alias IDs. Aliases without this flag (HTTP, Database, System, etc.) are never used as identity set discriminators. - `proposed` FieldAlias, required: Field alias group — defines a set of field names that represent the same concept. Used for: - Mapping equivalent field names across logs, traces, and metrics (e.g., `service`, `service.name`, `app` all mean "service identity") - Incident correlation and alert dimensions - Populating `ServiceIdentityConfig` via the recommendations UI # Field Name Overlaps Field names can appear in multiple semantic groups. When extracting dimensions, the **first-defined group** takes precedence. This allows flexible configurations where a field like "service" can have different meanings in different contexts. Example: ``` // Group 1: service-primary (defined first) // field_names: ["service", "primary_service"] // // Group 2: service-backup (defined second) // field_names: ["service", "backup_service"] // // When extracting dimensions from {"service": "api"}: // → Matches "service-primary" group (first occurrence wins) ``` - `display` string, required: Human-readable display name (e.g., "Host", "K8s Cluster") - `fields` string[], required: List of field names that are equivalent (e.g., ["host", "hostname", "node"]) Note: Field names can overlap with other groups. First-defined group wins. - `group` string, nullable: Category/group this semantic field belongs to (e.g., "Common", "Kubernetes", "AWS", "GCP", "Azure") Used for UI organization and preset templates - `id` string, required: Unique identifier (lowercase, dash-separated, e.g., "host", "k8s-cluster") - `is_workload_type` boolean: When true, this alias is a workload-type dimension used to build identity sets. Aliases with this flag are grouped by their `group` field to form `IdentitySet` entries with `distinguish_by` populated from those alias IDs. Aliases without this flag (HTTP, Database, System, etc.) are never used as identity set discriminators. - `unchanged` FieldAlias[], required: Groups that are identical in both - `display` string, required: Human-readable display name (e.g., "Host", "K8s Cluster") - `fields` string[], required: List of field names that are equivalent (e.g., ["host", "hostname", "node"]) Note: Field names can overlap with other groups. First-defined group wins. - `group` string, nullable: Category/group this semantic field belongs to (e.g., "Common", "Kubernetes", "AWS", "GCP", "Azure") Used for UI organization and preset templates - `id` string, required: Unique identifier (lowercase, dash-separated, e.g., "host", "k8s-cluster") - `is_workload_type` boolean: When true, this alias is a workload-type dimension used to build identity sets. Aliases with this flag are grouped by their `group` field to form `IdentitySet` entries with `distinguish_by` populated from those alias IDs. Aliases without this flag (HTTP, Database, System, etc.) are never used as identity set discriminators. ## Other responses - `400`: Bad request - Invalid semantic groups - `500`: Internal server error --- [API](https://skmtc.dev/openobserve/apis/openobserve-api-http.md) - [All operations](https://skmtc.dev/openobserve/apis/openobserve-api-http/llms.txt) - [OpenAPI document](https://skmtc.dev/openobserve/apis/openobserve-api-http/revisions/0529b8a10252?raw)