Skip to content

Grouping Operations

The grouping operations are implemented in internal/grouping/grouping.go.

Group Structure

type Group struct {
    ID        string    `json:"id"`
    Name      string    `json:"name"`
    Assets    []Asset   `json:"assets"`
    CreatedAt time.Time `json:"createdAt"`
    UpdatedAt time.Time `json:"updatedAt"`
}

Available Operations

Group Assets

func GroupAssets(ctx context.Context, client *immich.Client, assets []Asset, criteria []Criterion) ([]Group, error)

Groups assets based on specified criteria.

Parameters:

  • ctx: Context for the operation
  • client: Immich API client
  • assets: Array of assets to group
  • criteria: Array of grouping criteria

Returns:

  • []Group: Array of groups
  • error: Any error that occurred

Get Group

func GetGroup(ctx context.Context, client *immich.Client, groupID string) (*Group, error)

Retrieves a group by ID.

Parameters:

  • ctx: Context for the operation
  • client: Immich API client
  • groupID: ID of the group to retrieve

Returns:

  • *Group: Retrieved group
  • error: Any error that occurred

Update Group

func UpdateGroup(ctx context.Context, client *immich.Client, group *Group) error

Updates an existing group.

Parameters:

  • ctx: Context for the operation
  • client: Immich API client
  • group: Group to update

Returns:

  • error: Any error that occurred

Delete Group

func DeleteGroup(ctx context.Context, client *immich.Client, groupID string) error

Deletes a group by ID.

Parameters:

  • ctx: Context for the operation
  • client: Immich API client
  • groupID: ID of the group to delete

Returns:

  • error: Any error that occurred

Grouping Criteria

type Criterion struct {
    Key    string      `json:"key"`
    Split  *SplitConfig `json:"split,omitempty"`
    Delta  *DeltaConfig `json:"delta,omitempty"`
}

type SplitConfig struct {
    Delimiters []string `json:"delimiters"`
    Index      int      `json:"index"`
}

type DeltaConfig struct {
    Milliseconds int64 `json:"milliseconds"`
}

Error Handling

All operations handle the following error cases:

  • Invalid group ID
  • Group not found
  • API errors
  • Network errors
  • Invalid group data
  • Invalid criteria

Best Practices

  1. Error Handling

  2. Always check returned errors

  3. Use appropriate error handling strategies
  4. Log errors for debugging

  5. Context Usage

  6. Pass context through all operations

  7. Use context for cancellation
  8. Set appropriate timeouts

  9. Group Management

  10. Validate groups before operations

  11. Handle missing groups gracefully
  12. Maintain group consistency

  13. Criteria Usage

  14. Use appropriate criteria
  15. Handle edge cases
  16. Consider performance implications

Example Usage

// Group assets with criteria
criteria := []Criterion{
    {
        Key: "originalFileName",
        Split: &SplitConfig{
            Delimiters: []string{"~", "."},
            Index:      0,
        },
    },
    {
        Key: "localDateTime",
        Delta: &DeltaConfig{
            Milliseconds: 1000,
        },
    },
}
groups, err := GroupAssets(ctx, client, assets, criteria)
if err != nil {
    log.Printf("Error grouping assets: %v", err)
    return
}

// Get single group
group, err := GetGroup(ctx, client, "group-id")
if err != nil {
    log.Printf("Error getting group: %v", err)
    return
}

// Update group
group.Name = "New Name"
err = UpdateGroup(ctx, client, group)
if err != nil {
    log.Printf("Error updating group: %v", err)
    return
}

// Delete group
err = DeleteGroup(ctx, client, "group-id")
if err != nil {
    log.Printf("Error deleting group: %v", err)
    return
}