Skip to content

Category option combos

client.category_option_combos — read-only accessor over /api/categoryOptionCombos. A CategoryOptionCombo is one cell of a CategoryCombo's materialised cross-product: a tuple of CategoryOption values (e.g. (Male, <1y)). The server generates the matrix automatically when a CategoryCombo is saved (with the v43 manual-regen caveat).

async with Dhis2Client(...) as client:
    cocs = await client.category_option_combos.list_for_combo(combo_uid)
    for coc in cocs:
        print(coc.name, coc.id, [o.id for o in coc.categoryOptions or []])

CategoryOptionCombo UIDs are the targets of every DataValue.categoryOptionCombo / attributeOptionCombo reference, so this accessor is the standard way to enumerate the disaggregation slots a data element expects. Writes go through CategoryCombo lifecycle, not directly.

category_option_combos

CategoryOptionCombo read access — Dhis2Client.category_option_combos.

CategoryOptionCombos are the cells of the disaggregation matrix. DHIS2 generates and owns them — every CategoryCombo's options cross-product materialises here on save, and aggregate data values key on the resulting UIDs. Callers do not author CategoryOptionCombos directly; they edit the parent CategoryCombo + its Categories' option lists and DHIS2 regenerates the matrix.

This accessor is read-only: list / get / list-for-combo. For write flows (creating combos, adding categories, polling the matrix regeneration), reach for Dhis2Client.category_combos.

Classes

CategoryOptionCombo

Bases: BaseModel

Generated model for DHIS2 CategoryOptionCombo.

DHIS2 Category Option Combo - persisted metadata (generated from /api/schemas at DHIS2 v42).

API endpoint: /api/categoryOptionCombos.

Field Field(description=...) entries flag DHIS2 semantics the bare type can't capture: which side of a relationship owns the link (writable) vs the inverse side (ignored by the API), uniqueness constraints, and length bounds.

Source code in packages/dhis2w-client/src/dhis2w_client/generated/v42/schemas/category_option_combo.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
class CategoryOptionCombo(BaseModel):
    """Generated model for DHIS2 `CategoryOptionCombo`.

    DHIS2 Category Option Combo - persisted metadata (generated from /api/schemas at DHIS2 v42).

    API endpoint: /api/categoryOptionCombos.

    Field `Field(description=...)` entries flag DHIS2 semantics the bare
    type can't capture: which side of a relationship owns the link
    (writable) vs the inverse side (ignored by the API), uniqueness
    constraints, and length bounds.
    """

    model_config = ConfigDict(extra="allow", populate_by_name=True)

    access: Any | None = Field(default=None, description="Reference to Access. Read-only (inverse side).")
    aggregationType: AggregationType | None = None
    attributeValues: Any | None = Field(default=None, description="Reference to AttributeValues. Length/value max=255.")
    categoryCombo: Reference | None = Field(default=None, description="Reference to CategoryCombo.")
    categoryOptions: list[Any] | None = Field(default=None, description="Collection of CategoryOption.")
    code: str | None = Field(default=None, description="Unique. Length/value max=50.")
    created: datetime | None = None
    createdBy: Reference | None = Field(default=None, description="Reference to User. Read-only (inverse side).")
    description: str | None = Field(default=None, description="Length/value min=1, max=2147483647.")
    dimensionItem: str | None = Field(default=None, description="Read-only.")
    dimensionItemType: DimensionItemType | None = None
    displayDescription: str | None = Field(default=None, description="Read-only.")
    displayFormName: str | None = Field(default=None, description="Read-only.")
    displayName: str | None = Field(default=None, description="Read-only.")
    displayShortName: str | None = Field(default=None, description="Read-only.")
    favorite: bool | None = Field(default=None, description="Read-only.")
    favorites: list[Any] | None = Field(default=None, description="Collection of String. Read-only (inverse side).")
    formName: str | None = Field(default=None, description="Length/value max=2147483647.")
    href: str | None = None
    id: str | None = Field(default=None, description="Unique. Length/value min=11, max=11.")
    ignoreApproval: bool | None = None
    lastUpdated: datetime | None = None
    lastUpdatedBy: Reference | None = Field(default=None, description="Reference to User.")
    legendSet: Reference | None = Field(default=None, description="Reference to LegendSet. Read-only (inverse side).")
    legendSets: list[Any] | None = Field(default=None, description="Collection of LegendSet. Read-only (inverse side).")
    name: str | None = Field(default=None, description="Length/value max=2147483647.")
    queryMods: Any | None = Field(default=None, description="Reference to QueryModifiers. Read-only (inverse side).")
    sharing: Any | None = Field(default=None, description="Reference to Sharing. Read-only (inverse side).")
    shortName: str | None = Field(default=None, description="Length/value max=2147483647.")
    translations: list[Any] | None = Field(default=None, description="Collection of Translation. Length/value max=255.")
    user: Reference | None = Field(default=None, description="Reference to User. Read-only (inverse side).")

CategoryOptionCombosAccessor

Dhis2Client.category_option_combos — read-only access to the materialised matrix.

Source code in packages/dhis2w-client/src/dhis2w_client/v42/category_option_combos.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
class CategoryOptionCombosAccessor:
    """`Dhis2Client.category_option_combos` — read-only access to the materialised matrix."""

    def __init__(self, client: Dhis2Client) -> None:
        """Bind to the sharing client."""
        self._client = client

    async def list_all(
        self,
        *,
        page: int = 1,
        page_size: int = 50,
    ) -> list[CategoryOptionCombo]:
        """Page through every CategoryOptionCombo across every CategoryCombo."""
        raw = await self._client.get_raw(
            "/api/categoryOptionCombos",
            params={
                "fields": _COC_FIELDS,
                "page": str(page),
                "pageSize": str(page_size),
            },
        )
        return parse_collection(raw, "categoryOptionCombos", CategoryOptionCombo)

    async def get(self, uid: str) -> CategoryOptionCombo:
        """Fetch one CategoryOptionCombo by UID."""
        return await self._client.get(
            f"/api/categoryOptionCombos/{uid}", model=CategoryOptionCombo, params={"fields": _COC_FIELDS}
        )

    async def list_for_combo(self, combo_uid: str) -> list[CategoryOptionCombo]:
        """List every CategoryOptionCombo materialised by one CategoryCombo."""
        raw = await self._client.get_raw(
            "/api/categoryOptionCombos",
            params={
                "fields": _COC_FIELDS,
                "filter": f"categoryCombo.id:eq:{combo_uid}",
                "pageSize": "1000",
            },
        )
        return parse_collection(raw, "categoryOptionCombos", CategoryOptionCombo)
Functions
__init__(client)

Bind to the sharing client.

Source code in packages/dhis2w-client/src/dhis2w_client/v42/category_option_combos.py 
31
32
33
def __init__(self, client: Dhis2Client) -> None:
    """Bind to the sharing client."""
    self._client = client
list_all(*, page=1, page_size=50) async

Page through every CategoryOptionCombo across every CategoryCombo.

Source code in packages/dhis2w-client/src/dhis2w_client/v42/category_option_combos.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
async def list_all(
    self,
    *,
    page: int = 1,
    page_size: int = 50,
) -> list[CategoryOptionCombo]:
    """Page through every CategoryOptionCombo across every CategoryCombo."""
    raw = await self._client.get_raw(
        "/api/categoryOptionCombos",
        params={
            "fields": _COC_FIELDS,
            "page": str(page),
            "pageSize": str(page_size),
        },
    )
    return parse_collection(raw, "categoryOptionCombos", CategoryOptionCombo)
get(uid) async

Fetch one CategoryOptionCombo by UID.

Source code in packages/dhis2w-client/src/dhis2w_client/v42/category_option_combos.py 
52
53
54
55
56
async def get(self, uid: str) -> CategoryOptionCombo:
    """Fetch one CategoryOptionCombo by UID."""
    return await self._client.get(
        f"/api/categoryOptionCombos/{uid}", model=CategoryOptionCombo, params={"fields": _COC_FIELDS}
    )
list_for_combo(combo_uid) async

List every CategoryOptionCombo materialised by one CategoryCombo.

Source code in packages/dhis2w-client/src/dhis2w_client/v42/category_option_combos.py 
58
59
60
61
62
63
64
65
66
67
68
async def list_for_combo(self, combo_uid: str) -> list[CategoryOptionCombo]:
    """List every CategoryOptionCombo materialised by one CategoryCombo."""
    raw = await self._client.get_raw(
        "/api/categoryOptionCombos",
        params={
            "fields": _COC_FIELDS,
            "filter": f"categoryCombo.id:eq:{combo_uid}",
            "pageSize": "1000",
        },
    )
    return parse_collection(raw, "categoryOptionCombos", CategoryOptionCombo)

Functions