> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jakan.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Group Operations

> Operations for managing groups (movies/collections).

Operations for managing groups (movies/collections).

Bases: `StashClientProtocol`

Mixin for group-related client methods.

## Functions

### find\_group

```python theme={null}
find_group(group_id: str) -> Group | None
```

Find a group by ID.

Parameters:

| Name       | Type  | Description            | Default    |
| ---------- | ----- | ---------------------- | ---------- |
| `group_id` | `str` | Group ID to search for | *required* |

Returns:

| Type            | Description                           |
| --------------- | ------------------------------------- |
| `Group \| None` | Group object if found, None otherwise |

Examples:

```python theme={null}
group = await client.find_group("123")
if group:
    print(f"Found group: {group.name}")
    print(f"Duration: {group.duration} seconds")
    print(f"Director: {group.director}")
```

Access group relationships:

```python theme={null}
group = await client.find_group("123")
if group:
    # Get scene titles
    scene_titles = [s.title for s in group.scenes]
    # Get studio name
    studio_name = group.studio.name if group.studio else None
    # Get tag names
    tags = [t.name for t in group.tags]
    # Get sub-groups
    sub_groups = [sg.group.name for sg in group.sub_groups]
```

### find\_groups

```python theme={null}
find_groups(
    filter_: dict[str, Any] | None = None,
    group_filter: dict[str, Any] | None = None,
    ids: list[str] | None = None,
    q: str | None = None,
) -> FindGroupsResultType
```

Find groups matching the given filters.

Parameters:

| Name           | Type                     | Description                                                                                                                                                                                                                                                                                                                                                                     | Default |
| -------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `filter_`      | `dict[str, Any] \| None` | Optional general filter parameters: - q: str (search query) - direction: SortDirectionEnum (ASC/DESC) - page: int - per\_page: int - sort: str (field to sort by)                                                                                                                                                                                                               | `None`  |
| `group_filter` | `dict[str, Any] \| None` | Optional group-specific filter: - name: StringCriterionInput - director: StringCriterionInput - synopsis: StringCriterionInput - duration: IntCriterionInput - rating100: IntCriterionInput - date: DateCriterionInput - url: StringCriterionInput - is\_missing: str (what data is missing) - studios: HierarchicalMultiCriterionInput - tags: HierarchicalMultiCriterionInput | `None`  |
| `ids`          | `list[str] \| None`      | Optional list of group IDs to filter by                                                                                                                                                                                                                                                                                                                                         | `None`  |
| `q`            | `str \| None`            | Optional search query (alternative to filter\_\["q"])                                                                                                                                                                                                                                                                                                                           | `None`  |

Returns:

| Type                   | Description           |
| ---------------------- | --------------------- |
| `FindGroupsResultType` | FindGroupsResultType. |

Examples:

Find all groups:

```python theme={null}
result = await client.find_groups()
print(f"Found {result.count} groups")
for group in result.groups:
    print(f"- {group.name}")
```

Search by name:

```python theme={null}
result = await client.find_groups(q="Action")
print(f"Found {result.count} groups matching 'Action'")
```

Find groups by filter:

```python theme={null}
result = await client.find_groups(
    group_filter={
        "name": {
            "value": "Series",
            "modifier": "INCLUDES"
        }
    }
)
```

Find groups with specific tags:

```python theme={null}
result = await client.find_groups(
    group_filter={
        "tags": {
            "value": ["tag1", "tag2"],
            "modifier": "INCLUDES_ALL"
        }
    }
)
```

Find groups with high rating and sort by name:

```python theme={null}
result = await client.find_groups(
    filter_={
        "direction": "ASC",
        "sort": "name",
    },
    group_filter={
        "rating100": {
            "value": 80,
            "modifier": "GREATER_THAN"
        }
    }
)
```

Paginate results:

```python theme={null}
result = await client.find_groups(
    filter_={
        "page": 1,
        "per_page": 25,
    }
)
```

Find specific groups by IDs:

```python theme={null}
result = await client.find_groups(ids=["123", "456", "789"])
```

### create\_group

```python theme={null}
create_group(group: Group) -> Group
```

Create a new group in Stash.

Parameters:

| Name    | Type    | Description                                                               | Default    |
| ------- | ------- | ------------------------------------------------------------------------- | ---------- |
| `group` | `Group` | Group object with the data to create. Required fields: - name: Group name | *required* |

Returns:

| Type    | Description                                                  |
| ------- | ------------------------------------------------------------ |
| `Group` | Created Group object with ID and any server-generated fields |

Raises:

| Type             | Description                  |
| ---------------- | ---------------------------- |
| `ValueError`     | If the group data is invalid |
| `TransportError` | If the request fails         |

Examples:

Create a basic group:

```python theme={null}
group = Group(name="Test Series")
created = await client.create_group(group)
print(f"Created group with ID: {created.id}")
```

Create group with metadata:

```python theme={null}
group = Group(
    name="Action Movie Series",
    director="John Director",
    synopsis="An action-packed series",
    duration=7200,
    date="2020-01-01",
    rating100=85,
)
created = await client.create_group(group)
```

Create group with relationships:

```python theme={null}
from stash_graphql_client.types import Tag, Studio

# Fetch tags and studio
tag1 = await client.find_tag("tag1_id")
tag2 = await client.find_tag("tag2_id")
studio = await client.find_studio("studio_id")

group = Group(
    name="Tagged Group",
    tags=[tag1, tag2],
    studio=studio,
)
created = await client.create_group(group)
```

### update\_group

```python theme={null}
update_group(group: Group) -> Group
```

Update an existing group in Stash.

Parameters:

| Name    | Type    | Description                                            | Default    |
| ------- | ------- | ------------------------------------------------------ | ---------- |
| `group` | `Group` | Group object with updated data. Must include ID field. | *required* |

Returns:

| Type    | Description          |
| ------- | -------------------- |
| `Group` | Updated Group object |

Raises:

| Type             | Description                                   |
| ---------------- | --------------------------------------------- |
| `ValueError`     | If the group ID is missing or data is invalid |
| `TransportError` | If the request fails                          |

Examples:

Update group name and director:

```python theme={null}
group = await client.find_group("123")
group.name = "Updated Name"
group.director = "New Director"
updated = await client.update_group(group)
```

Update group rating:

```python theme={null}
group = await client.find_group("123")
group.rating100 = 90
updated = await client.update_group(group)
```

Update group tags:

```python theme={null}
group = await client.find_group("123")
tag1 = await client.find_tag("tag1_id")
tag2 = await client.find_tag("tag2_id")
group.tags = [tag1, tag2]
updated = await client.update_group(group)
```

### group\_destroy

```python theme={null}
group_destroy(
    input_data: GroupDestroyInput | dict[str, Any],
) -> bool
```

Delete a group from Stash.

Parameters:

| Name         | Type                                  | Description                                              | Default    |
| ------------ | ------------------------------------- | -------------------------------------------------------- | ---------- |
| `input_data` | `GroupDestroyInput \| dict[str, Any]` | GroupDestroyInput or dict with: - id: Group ID to delete | *required* |

Returns:

| Type   | Description                     |
| ------ | ------------------------------- |
| `bool` | True if deletion was successful |

Raises:

| Type             | Description          |
| ---------------- | -------------------- |
| `TransportError` | If the request fails |

Examples:

Delete by ID using dict:

```python theme={null}
result = await client.group_destroy({"id": "123"})
if result:
    print("Group deleted successfully")
```

Delete using GroupDestroyInput:

```python theme={null}
from stash_graphql_client.types import GroupDestroyInput

input_data = GroupDestroyInput(id="123")
result = await client.group_destroy(input_data)
```

### groups\_destroy

```python theme={null}
groups_destroy(ids: list[str]) -> bool
```

Delete multiple groups from Stash.

Parameters:

| Name  | Type        | Description                 | Default    |
| ----- | ----------- | --------------------------- | ---------- |
| `ids` | `list[str]` | List of group IDs to delete | *required* |

Returns:

| Type   | Description                     |
| ------ | ------------------------------- |
| `bool` | True if deletion was successful |

Raises:

| Type             | Description          |
| ---------------- | -------------------- |
| `TransportError` | If the request fails |

Examples:

```python theme={null}
result = await client.groups_destroy(["123", "456", "789"])
if result:
    print("Groups deleted successfully")
```

### bulk\_group\_update

```python theme={null}
bulk_group_update(
    input_data: BulkGroupUpdateInput | dict[str, Any],
) -> list[Group]
```

```python theme={null}
bulk_group_update(
    input_data: BulkGroupUpdateInput | dict[str, Any],
    *,
    return_fields: str,
) -> list[dict[str, Any]]
```

```python theme={null}
bulk_group_update(
    input_data: BulkGroupUpdateInput | dict[str, Any],
    *,
    return_fields: str | None = None,
) -> list[Group] | list[dict[str, Any]]
```

Bulk update multiple groups.

Parameters:

| Name            | Type                                     | Description                                                                                                                        | Default    |
| --------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `input_data`    | `BulkGroupUpdateInput \| dict[str, Any]` | BulkGroupUpdateInput or dict with fields to update.                                                                                | *required* |
| `return_fields` | `str \| None`                            | If provided, use a minimal inline mutation requesting only these fields (e.g. `"id"`). Returns raw dicts instead of Group objects. | `None`     |

Returns:

| Type                                  | Description                                                    |
| ------------------------------------- | -------------------------------------------------------------- |
| `list[Group] \| list[dict[str, Any]]` | List of updated Group objects (default), or list of dicts when |
| `list[Group] \| list[dict[str, Any]]` | `return_fields` is provided.                                   |

Examples:

Update rating for multiple groups:

```python theme={null}
result = await client.bulk_group_update({
    "ids": ["1", "2", "3"],
    "rating100": 85
})
print(f"Updated {len(result)} groups")
```

Fire-and-forget bulk update (minimal server load):

```python theme={null}
await client.bulk_group_update(
    {"ids": ["1", "2", "3"], "studio_id": "42"},
    return_fields="id",
)
```

### add\_group\_sub\_groups

```python theme={null}
add_group_sub_groups(
    input_data: GroupSubGroupAddInput | dict[str, Any],
) -> bool
```

Add sub-groups to a group.

Parameters:

| Name         | Type                                      | Description                                                                                                                                                                                                                                                | Default    |
| ------------ | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `input_data` | `GroupSubGroupAddInput \| dict[str, Any]` | GroupSubGroupAddInput or dict with: - containing\_group\_id: ID of the parent group - sub\_groups: List of GroupDescriptionInput dicts with group\_id and optional description - insert\_index: Optional index at which to insert (default: append to end) | *required* |

Returns:

| Type   | Description        |
| ------ | ------------------ |
| `bool` | True if successful |

Raises:

| Type             | Description          |
| ---------------- | -------------------- |
| `TransportError` | If the request fails |

Examples:

Add sub-groups to end:

```python theme={null}
result = await client.add_group_sub_groups({
    "containing_group_id": "parent_123",
    "sub_groups": [
        {"group_id": "child_456"},
        {"group_id": "child_789", "description": "Episode 1"}
    ]
})
```

Insert sub-groups at specific index:

```python theme={null}
from stash_graphql_client.types import (
    GroupSubGroupAddInput,
    GroupDescriptionInput
)

input_data = GroupSubGroupAddInput(
    containing_group_id="parent_123",
    sub_groups=[
        GroupDescriptionInput(group_id="child_456", description="Episode 2")
    ],
    insert_index=1
)
result = await client.add_group_sub_groups(input_data)
```

### remove\_group\_sub\_groups

```python theme={null}
remove_group_sub_groups(
    input_data: GroupSubGroupRemoveInput | dict[str, Any],
) -> bool
```

Remove sub-groups from a group.

Parameters:

| Name         | Type                                         | Description                                                                                                                               | Default    |
| ------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `input_data` | `GroupSubGroupRemoveInput \| dict[str, Any]` | GroupSubGroupRemoveInput or dict with: - containing\_group\_id: ID of the parent group - sub\_group\_ids: List of sub-group IDs to remove | *required* |

Returns:

| Type   | Description        |
| ------ | ------------------ |
| `bool` | True if successful |

Raises:

| Type             | Description          |
| ---------------- | -------------------- |
| `TransportError` | If the request fails |

Examples:

Remove sub-groups:

```python theme={null}
result = await client.remove_group_sub_groups({
    "containing_group_id": "parent_123",
    "sub_group_ids": ["child_456", "child_789"]
})
```

Using typed input:

```python theme={null}
from stash_graphql_client.types import GroupSubGroupRemoveInput

input_data = GroupSubGroupRemoveInput(
    containing_group_id="parent_123",
    sub_group_ids=["child_456", "child_789"]
)
result = await client.remove_group_sub_groups(input_data)
```

### reorder\_sub\_groups

```python theme={null}
reorder_sub_groups(
    input_data: ReorderSubGroupsInput | dict[str, Any],
) -> bool
```

Reorder sub-groups within a group.

Parameters:

| Name         | Type                                      | Description                                                                                                                                                                                                                                                                                                    | Default    |
| ------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `input_data` | `ReorderSubGroupsInput \| dict[str, Any]` | ReorderSubGroupsInput or dict with: - group\_id: ID of the parent group - sub\_group\_ids: List of sub-group IDs to reorder (must be subset of existing) - insert\_at\_id: Sub-group ID at which to insert the reordered groups - insert\_after: If True, insert after insert\_at\_id; if False, insert before | *required* |

Returns:

| Type   | Description        |
| ------ | ------------------ |
| `bool` | True if successful |

Raises:

| Type             | Description          |
| ---------------- | -------------------- |
| `TransportError` | If the request fails |

Examples:

Reorder sub-groups:

```python theme={null}
result = await client.reorder_sub_groups({
    "group_id": "parent_123",
    "sub_group_ids": ["child_2", "child_3"],
    "insert_at_id": "child_1",
    "insert_after": True
})
```

Using typed input:

```python theme={null}
from stash_graphql_client.types import ReorderSubGroupsInput

input_data = ReorderSubGroupsInput(
    group_id="parent_123",
    sub_group_ids=["child_2", "child_3"],
    insert_at_id="child_1",
    insert_after=False,
)
result = await client.reorder_sub_groups(input_data)
```