Background Updates¶

Endpoints¶

BackgroundUpdates ¶

This API allows a server administrator to manage the background updates being run against the database.

Source code in matrix_admin_sdk/endpoints/v1/background_updates.py

class BackgroundUpdates(Endpoint):
    """
    This API allows a server administrator to manage the background
    updates being run against the database.
    """

    async def status(self) -> StatusModel:
        """
        This API gets the current status of the background updates.
        """
        url = self.url("background_updates/status")
        result = await self.request(RequestMethods.GET, url)
        return StatusModel.from_dict(result)

    async def enabled(self, enabled: bool) -> EnabledModel:
        """
        This API allows pausing background updates.

        Background updates should not be paused for significant periods of time,
        as this can affect the performance of Synapse.

        Note: This won't persist over restarts.

        Note: This won't cancel any update query that is currently running.
        This is usually fine since most queries are short lived, except for
        CREATE INDEX background updates which won't be cancelled once started.
        Args:
            enabled: sets whether the background updates are enabled or disabled.

        Returns: The new status of the background updates.
        """
        url = self.url("background_updates/enabled")
        data = {"enabled": enabled}
        result = await self.request(RequestMethods.POST, url, json=data)
        res: EnabledModel = EnabledModel.from_dict(result)
        return res

    async def run(self, job_name: str) -> None:
        """
        This API schedules a specific background update to run.
        The job starts immediately after calling the API.

        Args:
            job_name: A string which job to run. Valid values are:
                - "populate_stats_process_rooms": Recalculate the stats for all rooms.
                - "regenerate_directory":Recalculate the user directory if it is stale or out of sync.

        """
        url = self.url("background_updates/start_job")
        data = {"job_name": job_name}
        await self.request(RequestMethods.POST, url, json=data)

`enabled(self, enabled)` `async` ¶

This API allows pausing background updates.

Background updates should not be paused for significant periods of time, as this can affect the performance of Synapse.

Note: This won't persist over restarts.

Note: This won't cancel any update query that is currently running. This is usually fine since most queries are short lived, except for CREATE INDEX background updates which won't be cancelled once started.

Parameters:

Name	Type	Description	Default
`enabled`	`bool`	sets whether the background updates are enabled or disabled.	required

Source code in matrix_admin_sdk/endpoints/v1/background_updates.py

async def enabled(self, enabled: bool) -> EnabledModel:
    """
    This API allows pausing background updates.

    Background updates should not be paused for significant periods of time,
    as this can affect the performance of Synapse.

    Note: This won't persist over restarts.

    Note: This won't cancel any update query that is currently running.
    This is usually fine since most queries are short lived, except for
    CREATE INDEX background updates which won't be cancelled once started.
    Args:
        enabled: sets whether the background updates are enabled or disabled.

    Returns: The new status of the background updates.
    """
    url = self.url("background_updates/enabled")
    data = {"enabled": enabled}
    result = await self.request(RequestMethods.POST, url, json=data)
    res: EnabledModel = EnabledModel.from_dict(result)
    return res

`run(self, job_name)` `async` ¶

This API schedules a specific background update to run. The job starts immediately after calling the API.

Parameters:

Name	Type	Description	Default
`job_name`	`str`	A string which job to run. Valid values are: - "populate_stats_process_rooms": Recalculate the stats for all rooms. - "regenerate_directory":Recalculate the user directory if it is stale or out of sync.	required

Source code in matrix_admin_sdk/endpoints/v1/background_updates.py

async def run(self, job_name: str) -> None:
    """
    This API schedules a specific background update to run.
    The job starts immediately after calling the API.

    Args:
        job_name: A string which job to run. Valid values are:
            - "populate_stats_process_rooms": Recalculate the stats for all rooms.
            - "regenerate_directory":Recalculate the user directory if it is stale or out of sync.

    """
    url = self.url("background_updates/start_job")
    data = {"job_name": job_name}
    await self.request(RequestMethods.POST, url, json=data)

`status(self)` `async` ¶

This API gets the current status of the background updates.

Source code in matrix_admin_sdk/endpoints/v1/background_updates.py

async def status(self) -> StatusModel:
    """
    This API gets the current status of the background updates.
    """
    url = self.url("background_updates/status")
    result = await self.request(RequestMethods.GET, url)
    return StatusModel.from_dict(result)

Models¶

CurrentUpdate¶

CurrentUpdate

Attributes:

Name	Type	Description
`db_name`	`str`	the database name (usually Synapse is configured with a single database named 'master')
`name`	`str`	the name of the update
`total_item_count`	`int`	total number of "items" processed (the meaning of 'items' depends on the update in question)
`total_duration_ms`	`float`	how long the background process has been running, not including time spent sleeping
`average_items_per_ms`	`float`	how many items are processed per millisecond based on an exponential average

Source code in matrix_admin_sdk/models/v1/background_updates.py

class CurrentUpdate(BaseModel):
    """
    CurrentUpdate

    Attributes:
        db_name: the database name (usually Synapse is configured with a single database named 'master')
        name (str):  the name of the update
        total_item_count (int):total number of "items" processed (the meaning of
            'items' depends on the update in question)
        total_duration_ms (float): how long the background process has been running,
            not including time spent sleeping
        average_items_per_ms (float): how many items are processed per millisecond
            based on an exponential average
    """

    db_name: str
    name: str
    total_item_count: int
    total_duration_ms: float
    average_items_per_ms: float

StatusModel¶

StatusModel

Attributes:

Name	Type	Description
`enabled`	`bool`	whether the background updates are enabled or disabled
`current_updates`	`List[matrix_admin_sdk.models.v1.background_updates.CurrentUpdate]`	a list of the current updates being processed

Source code in matrix_admin_sdk/models/v1/background_updates.py

class StatusModel(BaseModel):
    """
    StatusModel
    Attributes:
        enabled: whether the background updates are enabled or disabled
        current_updates: a list of the current updates being processed
    """

    enabled: bool
    current_updates: List[CurrentUpdate]

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "StatusModel":
        current_updates = []
        for k, v in data["current_updates"].items():
            v["db_name"] = k
            current_updates.append(CurrentUpdate.from_dict(v))
        return cls(enabled=data["enabled"], current_updates=current_updates)

EnabledModel¶

EnabledModel

Attributes:

Name	Type	Description
`enabled`	`bool`	whether the background updates are enabled or disabled

Source code in matrix_admin_sdk/models/v1/background_updates.py

class EnabledModel(BaseModel):
    """
    EnabledModel

    Attributes:
        enabled (bool): whether the background updates are enabled or disabled
    """

    enabled: bool

Background Updates¶

Endpoints¶