---
url: "https://vueda.dev/v3/reference/api/py/vueda.history.queries.md"
title: "history.queries"
---

# history.queries

## Overview

The queries behind the action-grouped history response.

A page is a page of actions, not of events, so grouping happens in the database before the
paginator sees anything. That takes two reads: one for the page of groups, and one for the events
belonging to those groups. Neither grows with the number of events on the page.

Both reads run over the same union. Its parts are pghistory's events that reference the object,
which are the object's own events and the events of rows with a foreign key to it, and the
object's workflow state events.

## `action_groups_for` {#action_groups_for}

One row per action, newest first, ready to paginate.

``state_events`` names the object's workflow state events, as
:func:`vueda.history.sources.state_events_for` returns them.

Django cannot group a union, so the union runs as a common table expression and the grouping
selects from it. Each part selects only the columns that grouping reads. That lets the database
skip building every event's data and difference, which is most of the cost of a long history.

Actions that share a recorded time break the tie on their earliest event's identifier parts,
the tracked model label and then the numeric event id, which is the published rule. That keeps
a page boundary in the same place between requests without comparing identifiers as strings,
where ``:9`` would sort after ``:10``.

### Signature {#action_groups_for-signature}

`action_groups_for(instance, user, state_events)`

#### Parameters {#action_groups_for-parameters}

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <span id="action_groups_for-param-instance">instance</span> |  | yes |  |  |
| <span id="action_groups_for-param-user">user</span> |  | yes |  |  |
| <span id="action_groups_for-param-state_events">state_events</span> |  | yes |  |  |

### Source {#action_groups_for-source}

`server/vueda/history/queries.py:89`

## `events_in_groups` {#events_in_groups}

Every visible event of the named groups, in the order they were written.

Each part is narrowed to the named groups before the union, so the database builds the data and
difference of the page's events only. Each event carries the moment of its own write, so the
recorded time orders a group faithfully. The tracked model label and the event id break a tie,
which keeps a rendered group from reshuffling between requests. Each event is annotated with
its ``group_key`` and its published ``relation``.

### Signature {#events_in_groups-signature}

`events_in_groups(instance, user, state_events, group_keys)`

#### Parameters {#events_in_groups-parameters}

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <span id="events_in_groups-param-instance">instance</span> |  | yes |  |  |
| <span id="events_in_groups-param-user">user</span> |  | yes |  |  |
| <span id="events_in_groups-param-state_events">state_events</span> |  | yes |  |  |
| <span id="events_in_groups-param-group_keys">group_keys</span> |  | yes |  |  |

### Source {#events_in_groups-source}

`server/vueda/history/queries.py:119`

## Source

`server/vueda/history/queries.py`