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 operationclient
: Immich API clientassets
: Array of assets to groupcriteria
: Array of grouping criteria
Returns:
[]Group
: Array of groupserror
: 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 operationclient
: Immich API clientgroupID
: ID of the group to retrieve
Returns:
*Group
: Retrieved grouperror
: 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 operationclient
: Immich API clientgroup
: 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 operationclient
: Immich API clientgroupID
: 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¶
-
Error Handling
-
Always check returned errors
- Use appropriate error handling strategies
-
Log errors for debugging
-
Context Usage
-
Pass context through all operations
- Use context for cancellation
-
Set appropriate timeouts
-
Group Management
-
Validate groups before operations
- Handle missing groups gracefully
-
Maintain group consistency
-
Criteria Usage
- Use appropriate criteria
- Handle edge cases
- 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
}