Group same-field relations by group ID, not label.

Author: apognu

api/handle_graph_walk.go

@@ -5,7 +5,9 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/cockroachdb/errors"
 	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
 
 	"github.com/checkmarble/marble-backend/dto"
 	"github.com/checkmarble/marble-backend/models"
@@ -25,18 +27,16 @@ func handleGraphWalk(uc usecases.Usecases) func(c *gin.Context) {
 		nodeType := c.Param("node_type")
 		nodeId := c.Param("node_id")
 
+		relationGroupIds, err := parseGraphRelationGroups(c.Query("same_field_relations"))
+		if presentError(ctx, c, err) {
+			return
+		}
+
 		opts := models.GraphWalkOptions{
 			EndTypes:               parseGraphEndTypes(c.Query("types")),
 			Degrees:                parseGraphDegrees(c.Query("degrees")),
 			SkipSameFieldRelations: c.Query("skip_same_field_relations") == "true",
-			SameFieldRelations: func() []string {
-				switch sfr := c.Query("same_field_relations"); sfr {
-				case "":
-					return nil
-				default:
-					return strings.Split(sfr, ",")
-				}
-			}(),
+			SameFieldRelations:     relationGroupIds,
 		}
 
 		usecase := usecasesWithCreds(ctx, uc).NewGraphWalkUsecase()
@@ -50,6 +50,29 @@ func handleGraphWalk(uc usecases.Usecases) func(c *gin.Context) {
 	}
 }
 
+// parseGraphRelationGroups reads the relation groups a walk should restrict its same-field
+// traversal to, as a comma-separated list of group ids. Empty means "every group".
+func parseGraphRelationGroups(raw string) ([]uuid.UUID, error) {
+	var groupIds []uuid.UUID
+
+	for part := range strings.SplitSeq(raw, ",") {
+		trimmed := strings.TrimSpace(part)
+		if trimmed == "" {
+			continue
+		}
+
+		groupId, err := uuid.Parse(trimmed)
+		if err != nil {
+			return nil, errors.Wrapf(models.BadParameterError,
+				"%q is not a valid relation group id", trimmed)
+		}
+
+		groupIds = append(groupIds, groupId)
+	}
+
+	return groupIds, nil
+}
+
 func parseGraphEndTypes(raw string) []string {
 	var endTypes []string
 

api/handle_graph_walk_test.go

@@ -0,0 +1,54 @@
+package api
+
+import (
+	"testing"
+
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/checkmarble/marble-backend/models"
+)
+
+func TestParseGraphRelationGroups(t *testing.T) {
+	first := uuid.New()
+	second := uuid.New()
+
+	tests := []struct {
+		name     string
+		raw      string
+		expected []uuid.UUID
+	}{
+		{name: "absent means every group", raw: "", expected: nil},
+		{name: "one group", raw: first.String(), expected: []uuid.UUID{first}},
+		{
+			name:     "several groups",
+			raw:      first.String() + "," + second.String(),
+			expected: []uuid.UUID{first, second},
+		},
+		{
+			// A list is easier to build with a trailing comma or a space after each one, and
+			// neither says anything different from the list without them.
+			name:     "padding and empty segments are not an error",
+			raw:      " " + first.String() + ", " + second.String() + ",",
+			expected: []uuid.UUID{first, second},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			groupIds, err := parseGraphRelationGroups(tt.raw)
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.expected, groupIds)
+		})
+	}
+}
+
+func TestParseGraphRelationGroups_ReportsSomethingThatIsNotAGroupIdAsBadInput(t *testing.T) {
+	// Bad input from a query string is the caller's mistake, not ours: it must not read as an
+	// internal failure, which is what would be reported and alerted on otherwise.
+	_, err := parseGraphRelationGroups("same_iban")
+
+	assert.ErrorIs(t, err, models.BadParameterError)
+}

dto/graph_relation_dto.go

@@ -10,6 +10,7 @@ import (
 
 type GraphRelation struct {
 	Id         uuid.UUID `json:"id"`
+	GroupId    uuid.UUID `json:"group_id"`
 	Label      string    `json:"label"`
 	LeftType   string    `json:"left_type"`
 	LeftField  string    `json:"left_field"`
@@ -21,6 +22,7 @@ type GraphRelation struct {
 func AdaptGraphRelationDto(r models.GraphRelation) GraphRelation {
 	return GraphRelation{
 		Id:         r.Id,
+		GroupId:    r.GroupId,
 		Label:      r.Label,
 		LeftType:   r.LeftType,
 		LeftField:  r.LeftField,
@@ -31,15 +33,17 @@ func AdaptGraphRelationDto(r models.GraphRelation) GraphRelation {
 }
 
 type CreateGraphRelationBody struct {
-	Label      string `json:"label" binding:"required"`
-	LeftType   string `json:"left_type" binding:"required"`
-	LeftField  string `json:"left_field" binding:"required"`
-	RightType  string `json:"right_type" binding:"required"`
-	RightField string `json:"right_field" binding:"required"`
+	GroupId    uuid.UUID `json:"group_id"`
+	Label      string    `json:"label" binding:"required"`
+	LeftType   string    `json:"left_type" binding:"required"`
+	LeftField  string    `json:"left_field" binding:"required"`
+	RightType  string    `json:"right_type" binding:"required"`
+	RightField string    `json:"right_field" binding:"required"`
 }
 
 func AdaptCreateGraphRelation(body CreateGraphRelationBody) models.CreateGraphRelation {
 	return models.CreateGraphRelation{
+		GroupId:    body.GroupId,
 		Label:      body.Label,
 		LeftType:   body.LeftType,
 		LeftField:  body.LeftField,

mocks/graph_relation_repository.go

@@ -21,6 +21,11 @@ func (r *GraphRelationRepository) ListGraphRelations(
 	return args.Get(0).([]models.GraphRelation), args.Error(1)
 }
 
+func (r *GraphRelationRepository) GetGraphRelationGroupLabel(ctx context.Context, exec repositories.Executor, orgId, groupId uuid.UUID) (string, error) {
+	args := r.Called(ctx, exec, orgId, groupId)
+	return args.Get(0).(string), args.Error(1)
+}
+
 func (r *GraphRelationRepository) GetGraphRelation(
 	ctx context.Context, exec repositories.Executor, id uuid.UUID,
 ) (models.GraphRelation, error) {

models/graph_walk.go

@@ -74,8 +74,9 @@ type GraphResultNode struct {
 	// the value it pivots on.
 	//
 	//   - "match": a value two or more records share on a field an organization declared as
-	//     meaningful. Type is the relation's label, Id the shared value. Its edges are the
-	//     records carrying it, so a value shared by n records costs n edges rather than n².
+	//     meaningful. Type is the relation's group id, Id the shared value, so relations sharing
+	//     a group converge on one connector whatever each is labelled. Its edges are the records
+	//     carrying it, so a value shared by n records costs n edges rather than n².
 	//
 	//   - "link": the records hanging off one record through a single data-model link, when
 	//     there are too many of them to pull in. Type is the link's name, Id the value the
@@ -94,12 +95,23 @@ type GraphResultNode struct {
 	Metadata GraphResultNodeMetadata
 }
 
+// GraphResultNodeMetadata is what is known about a node beyond its identity: the label to show
+// it under, and — for a record — the risk it carries.
 type GraphResultNodeMetadata struct {
 	Index int
-	// Label is the record's caption: the value it carries on the field its table declares as
-	// its caption field. It is empty on a connector, which is not a record, and on a record
-	// whose table declares no caption field.
-	Label     string
+
+	// Label is what to show the node under, and where it comes from depends on what the node is:
+	//
+	//   - on a record, its caption: the value it carries on the field its table declares as its
+	//     caption field. Empty when its table declares no such field.
+	//   - on a connector, what to call the relationship: the relation group's label for a "match"
+	//     one, the link's name for a "link" one. There it is deliberately not an identity — two
+	//     independent groups may well be labelled the same — so Type still carries the group id,
+	//     and Type/Id is what edges refer to.
+	Label string
+
+	// RiskLevel and Tags come from the records' own scoring, so they are only ever set on a
+	// record node: a connector is not a record and has nothing to score.
 	RiskLevel int
 	Tags      []uuid.UUID
 }
@@ -122,19 +134,22 @@ type GraphWalkOptions struct {
 	EndTypes               []string
 	Degrees                int
 	SkipSameFieldRelations bool
-	SameFieldRelations     []string
+	SameFieldRelations     []uuid.UUID
 }
 
 // GraphRelation declares that equal values of two (record type, field) endpoints connect the
 // records carrying them, even though no link exists between those records. An organization
 // defines its own relations against the tables and fields of its own data model.
 //
 // Relations are one-to-one: a group of three endpoints that should all count as sharing a
-// value is expressed as three relations (A<->B, B<->C, C<->A). Relations sharing a Label
-// converge on the same connector node, so such a group still renders as a single star.
+// value is expressed as three relations (A<->B, B<->C, C<->A). Relations sharing a GroupId
+// converge on the same connector node, so such a group still renders as a single star. The
+// creation path keeps Label consistent across a group, but GroupId — not Label — is what
+// identifies it: unlike a label, it survives a rename without splitting or merging groups.
 type GraphRelation struct {
 	Id         uuid.UUID
 	OrgId      uuid.UUID
+	GroupId    uuid.UUID
 	Label      string
 	LeftType   string
 	LeftField  string
@@ -263,6 +278,7 @@ func GraphIndexedFields(dataModel DataModel, relations []GraphRelation) map[stri
 // database.
 type CreateGraphRelation struct {
 	OrgId      uuid.UUID
+	GroupId    uuid.UUID
 	Label      string
 	LeftType   string
 	LeftField  string

repositories/dbmodels/db_graph_relation.go

@@ -16,6 +16,7 @@ var SelectGraphRelationColumn = utils.ColumnList[DBGraphRelation]()
 type DBGraphRelation struct {
 	Id         uuid.UUID `db:"id"`
 	OrgId      uuid.UUID `db:"org_id"`
+	GroupId    uuid.UUID `db:"group_id"`
 	Label      string    `db:"label"`
 	LeftType   string    `db:"left_type"`
 	LeftField  string    `db:"left_field"`
@@ -28,6 +29,7 @@ func AdaptGraphRelation(db DBGraphRelation) (models.GraphRelation, error) {
 	return models.GraphRelation{
 		Id:         db.Id,
 		OrgId:      db.OrgId,
+		GroupId:    db.GroupId,
 		Label:      db.Label,
 		LeftType:   db.LeftType,
 		LeftField:  db.LeftField,

repositories/graph_relation_repository.go

@@ -6,7 +6,9 @@ import (
 	"strings"
 
 	"github.com/Masterminds/squirrel"
+	"github.com/cockroachdb/errors"
 	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
 
 	"github.com/checkmarble/marble-backend/models"
 	"github.com/checkmarble/marble-backend/pure_utils"
@@ -15,6 +17,7 @@ import (
 
 type GraphRelationRepository interface {
 	ListGraphRelations(ctx context.Context, exec Executor, orgId uuid.UUID) ([]models.GraphRelation, error)
+	GetGraphRelationGroupLabel(ctx context.Context, exec Executor, orgId, groupId uuid.UUID) (string, error)
 	GetGraphRelation(ctx context.Context, exec Executor, id uuid.UUID) (models.GraphRelation, error)
 	CreateGraphRelation(ctx context.Context, exec Executor, relation models.CreateGraphRelation) (models.GraphRelation, error)
 	DeleteGraphRelation(ctx context.Context, exec Executor, id uuid.UUID) error
@@ -38,6 +41,37 @@ func (repo *MarbleDbRepository) ListGraphRelations(
 	return SqlToListOfModels(ctx, exec, query, dbmodels.AdaptGraphRelation)
 }
 
+func (repo *MarbleDbRepository) GetGraphRelationGroupLabel(ctx context.Context, exec Executor, orgId, groupId uuid.UUID) (string, error) {
+	if err := validateMarbleDbExecutor(exec); err != nil {
+		return "", err
+	}
+
+	sql := NewQueryBuilder().
+		Select("label").
+		From(dbmodels.TABLE_GRAPH_RELATIONS).
+		Where(squirrel.Eq{"org_id": orgId, "group_id": groupId}).
+		Limit(1)
+
+	query, args, err := sql.ToSql()
+	if err != nil {
+		return "", err
+	}
+
+	row := exec.QueryRow(ctx, query, args...)
+
+	var label string
+
+	if err := row.Scan(&label); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return "", errors.Wrap(models.NotFoundError, "provided group does not exist")
+		}
+
+		return "", err
+	}
+
+	return label, nil
+}
+
 func (repo *MarbleDbRepository) GetGraphRelation(
 	ctx context.Context, exec Executor, id uuid.UUID,
 ) (models.GraphRelation, error) {
@@ -60,10 +94,11 @@ func (repo *MarbleDbRepository) CreateGraphRelation(ctx context.Context, exec Ex
 
 	query := NewQueryBuilder().
 		Insert(dbmodels.TABLE_GRAPH_RELATIONS).
-		Columns("id", "org_id", "label", "left_type", "left_field", "right_type", "right_field").
+		Columns("id", "org_id", "group_id", "label", "left_type", "left_field", "right_type", "right_field").
 		Values(
 			pure_utils.NewId(),
 			relation.OrgId,
+			relation.GroupId,
 			relation.Label,
 			relation.LeftType,
 			relation.LeftField,

repositories/migrations/20260810081900_graph_walking.sql

@@ -3,6 +3,7 @@
 create table graph_relations (
     id uuid primary key default gen_random_uuid(),
     org_id uuid not null,
+    group_id uuid not null,
     label text not null,
     left_type text not null,
     left_field text not null,
@@ -12,7 +13,7 @@ create table graph_relations (
 
     constraint fk_org foreign key (org_id) references organizations (id) on delete cascade,
 
-    unique (org_id, label, left_type, left_field, right_type, right_field)
+    unique (org_id, group_id, left_type, left_field, right_type, right_field)
 );
 
 create index idx_graph_relations_org_id on graph_relations (org_id);

usecases/graph_relation_usecase.go

@@ -7,6 +7,7 @@ import (
 	"github.com/google/uuid"
 
 	"github.com/checkmarble/marble-backend/models"
+	"github.com/checkmarble/marble-backend/pure_utils"
 	"github.com/checkmarble/marble-backend/repositories"
 	"github.com/checkmarble/marble-backend/usecases/executor_factory"
 	"github.com/checkmarble/marble-backend/usecases/security"
@@ -44,6 +45,24 @@ func (uc GraphRelationUsecase) CreateGraphRelation(ctx context.Context, input mo
 		return models.GraphRelation{}, err
 	}
 
+	switch input.GroupId {
+	case uuid.Nil:
+		input.GroupId = pure_utils.NewId()
+
+	default:
+		// A label belongs to the group, not to the relation, so joining an existing one adopts
+		// its label rather than setting one. Silently discarding a different label would leave
+		// the caller believing it took, so say so instead.
+		label, err := uc.graphRelationRepository.GetGraphRelationGroupLabel(ctx, exec, input.OrgId, input.GroupId)
+		if err != nil {
+			return models.GraphRelation{}, err
+		}
+		if input.Label != label {
+			return models.GraphRelation{}, errors.Wrapf(models.BadParameterError,
+				"group %s is labelled %q, not %q", input.GroupId, label, input.Label)
+		}
+	}
+
 	endpoints := [][2]string{
 		{input.LeftType, input.LeftField},
 		{input.RightType, input.RightField},