WorkingRecord¶
WorkingRecord
¶
WorkingRecord(base: RecordLike)
Bases: Record
A Record whose last source is a staging area, plus the edit surface.
A Record in the type as well as in the fold: what it reads is the data
with its pending edits applied, and it reads it by being one layer deeper
than its base rather than by overlaying anything of its own. Every read
member is inherited unchanged, so an edit reads back through the same code
path a committed layer would.
Staged rows live in connection-scoped DuckDB tables, the only place a staged row exists: the reads fold them rather than holding a copy, so what is staged is asked of the reads themselves.
The source list is fixed at construction and never changes; a set
changes what the last source's tables hold, not which sources there are.
That is what lets the inherited members stay correct - they cache a key
set only where the fold is stable, which a staged source makes it not.
Raises:
| Type | Description |
|---|---|
ValueError
|
On a read, an edit or |
Stage edits over base, which must be a Record.
Raises:
| Type | Description |
|---|---|
TypeError
|
For any other |
TransactionException
|
Where the cursor holds an open transaction, whose staging tables no other cursor could see to drop. |
Notes
Source code in src/datarecord/mutable.py
edits
property
¶
The staged layer alone: the delta against the base, as a LayerData.
What store.commit(w) writes, as a child of the revision this record
was built over - only the edits, the fold resolving the rest from the
parent. The record itself is the flattened whole, base plus edits,
which is what a standalone ws.write(w, uri) wants.
Writing clears nothing: rollback() does, called or not.
set
¶
Stage values of one attribute.
Every coordinate is a keyword - entity=, snapshot=, a multi-dim's
coordinate such as bus= or a corridor's from= - since which exist is declared
rather than fixed. A keyword holds one label, fixing that coordinate, or
a list of labels the value is staged at each of. A coordinate no keyword
names is NULL, which by the broadcast rule is every label of it. The
call replaces every row of attribute staged earlier that its own
rows cover.
value takes five forms:
- a scalar, staged at every combination of the listed labels;
- a sequence, aligned positionally to the one list keyword;
- a mapping or a one-dimensional labelled series, keyed by labels of
the series'
index.namewhere that names a coordinate, else of the one coordinate no keyword names; - a long frame supplying its own keys, which keywords may complete with single labels.
An attribute's values are long rows, whatever its dims. A property -
a category included - patches one column of existing axis rows: a
mapping or series from label to value, a dim= keyword naming the
labels, or a scalar for every label the axis has. A multi-dim's
property takes a scalar, its coordinates as keywords selecting the
tuples, none selecting every tuple. A coordinate is part of the key,
which add and remove change, and is refused here.
A property is named subject.name - set("entity.carrier", ...) -
and a plain name is an attribute.
A keyword naming no coordinate of attribute is a property of a dim it
reaches - ctype="Generator", or a list of values - and selects
the labels of that dim matching it on the record as staged, the
keywords combining as an intersection; set writes one row per label,
and stores nothing of the filter, so a label added later is not reached.
A property of a multi-dim attribute is over - role="output" -
selects its tuples the same way, narrowed by any keyword naming one of
its coordinates. On a multi-dim's property, the keywords select its
tuples as on an attribute over it: set("connection.note", v,
role="output") patches the output connections, and ctype="Link"
the connections of links.
Raises:
| Type | Description |
|---|---|
KeyError
|
On an undeclared attribute or keyword, a label that its dim's axis, as staged, does not hold, a tuple that its multi-dim, as staged, does not hold, a property's label no layer wrote, or a value of a property that refers to a dim and is no label of it. |
ValueError
|
On a coordinate named as |
Source code in src/datarecord/mutable.py
881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 | |
add
¶
add(
dim: str,
labels: Sequence[Any]
| Sequence[Mapping[str, Any]]
| DuckDBPyRelation,
**columns: Any,
) -> None
Stage labels of dim, each as one whole row of its axis file.
columns are dim's properties, each a scalar for every label or a
sequence aligned to labels. A column no keyword names is NULL on
these rows: add restates a label's row whole, replacing any this
record staged for it. A label keeps its place in the axis, a label of
the base removed here takes its base place back, and a new one is
appended.
A multi-dim's labels are tuples, given as a frame holding the struct
column named for the multi-dim, as dims[dim] reads it, or one with a
column per coordinate instead, or as a list of mappings from
coordinate to label. A frame may carry property columns too and takes
a scalar keyword only.
Not a sequence of set calls: a label exists by virtue of its axis row,
so adding one with no columns at all is an edit. An attribute's value,
whatever its dims, goes through set.
Raises:
| Type | Description |
|---|---|
KeyError
|
If the schema declares no |
TypeError
|
On a frame for a dim that is no multi-dim, or a value that is no frame DuckDB rescans. |
ValueError
|
On a dim with |
Source code in src/datarecord/mutable.py
1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 | |
remove
¶
Stage dim's axis without labels.
Need not enumerate what it deletes: the fold drops every value keyed
by a removed label where dim is partial. No labels stage nothing.
And every multi-dim with a coordinate over dim without the tuples
naming one of labels, read from the record as it currently resolves:
a multi-dim attribute's value goes with its tuple.
A multi-dim's labels are tuples, given as add takes them.
Raises:
| Type | Description |
|---|---|
TypeError
|
As |
ValueError
|
On a dim with |
Notes
Source code in src/datarecord/mutable.py
1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 | |
rollback
¶
Clear every staged row without writing.