pub struct TablePath { /* private fields */ }Expand description
A table to read from or write to, and which part of it.
Built from a &str wherever a plain path will do:
let replace = TablePath::from("//tmp/log");
let add = TablePath::new("//tmp/log").append();
let head = TablePath::new("//tmp/log").columns(["host", "status"]).range(0..100);Append is a write-side attribute; columns and ranges are read-side ones,
the same split the C++ TRichYPath and the Go ypath.Rich carry. The
write methods refuse a path with a read selection rather than sending
it — the cluster ignores a selection on a write and replaces the whole
table with a 200, which is silent data loss. Measured on a local cluster,
in both spellings: write_table_rows("//tmp/t[#0:#2]", rows) replaced
everything and reported success, and a write_table whose path carried
<ranges=[{lower_limit={row_index=0};upper_limit={row_index=2}}]> as an
attribute did exactly the same — 200, three rows replaced by one.
The path string is never parsed. Rich YPath syntax spelled into it —
<append=%true>//tmp/t, //tmp/t[#0:#2], //tmp/t{a,b} — goes to the
cluster verbatim on a read, where the cluster honours it, and is refused on
a write, where the cluster would not: the attribute form of a selection is
ignored there, and this type exists so that cannot happen by accident.
Implementations§
Source§impl TablePath
impl TablePath
Sourcepub fn new(path: impl Into<String>) -> Self
pub fn new(path: impl Into<String>) -> Self
A path that names the whole table: a write replaces its contents, a read returns every row of every column — the defaults everywhere in YTsaurus.
Sourcepub fn append(self) -> Self
pub fn append(self) -> Self
Adds rows to the table instead of replacing it.
The table has to exist: appending to a path that does not is refused
with Error getting basic attributes of user objects, which is the
cluster’s way of saying there was nothing to append to.
A sorted table stays sorted, and the cluster checks. Rows appended
after a larger key are refused — Sort order violation: [0#9] > [0#1]
— so an append to a sorted table is a continuation of it rather than an
addition to it.
Sourcepub fn columns(
self,
columns: impl IntoIterator<Item = impl Into<String>>,
) -> Self
pub fn columns( self, columns: impl IntoIterator<Item = impl Into<String>>, ) -> Self
Reads only the named columns.
Three columns out of a forty-column table cost three columns’ worth of
wire and decode, which is what makes a laptop-side read of a wide table
reasonable. The names travel as the columns attribute on the path,
which the
rich YPath reference
says is “recognized by the table data read command (read_table)” —
and by read commands only, which is why the write methods refuse a
path carrying one rather than letting the cluster ignore it.
A column the table does not have is not an error — measured on a
local cluster: columns(["a", "nosuch"]) against a table with no
nosuch answered 200, every row carrying only a. Rows simply come
back without the key, exactly as they do for a row with no value in a
named column, so a typo here reads clean and decodes short. A struct
decoded from such a read fails loudly on the missing field, which is
where the typo surfaces; a map decodes to fewer keys and does not.
The empty selection is that same shape taken to its end, and it is
sent. Measured: <columns=[]> answers 200 with one empty map per
row, and it composes with a range —
<columns=[];ranges=[{lower_limit={row_index=0};upper_limit={row_index=2}}]>
came back as two empty maps, and the same range spelled with key
bounds came back as three. That is how many rows a range holds, or
whether a key range holds any, with no column bytes on the wire —
a question Client::row_count cannot
answer, since it reads the @row_count attribute and so speaks only
for a whole static table. It decodes to a map with no keys and to a
struct missing every field, so name the columns when the rows are
what is wanted.
Calling this again replaces the selection rather than adding to it.
Sourcepub fn range(self, range: impl Into<RowRange>) -> Self
pub fn range(self, range: impl Into<RowRange>) -> Self
Reads only the rows a RowRange selects. May be called several
times: the ranges are read one after another, in the order given —
the documented meaning of the ranges attribute.
Plain Rust ranges convert, so row windows read as they would on a slice:
let first_two = TablePath::new("//tmp/t").range(0..2);
let from_key = TablePath::new("//tmp/t")
.range(RowRange::keys(Key::from("alice")..Key::from("bob")));Sourcepub fn is_append(&self) -> bool
pub fn is_append(&self) -> bool
Whether TablePath::append was called on this path.
Not “whether the cluster will append”: the cluster parses attributes out
of the path string too, so a path built from the text
<append=%true>//tmp/t appends while this answers false. Spelling the
attribute into the string is not a supported way to ask for it, and a
write to such a string is refused outright — see TablePath.
Sourcepub fn selected_columns(&self) -> Option<&[String]>
pub fn selected_columns(&self) -> Option<&[String]>
The columns TablePath::columns selected, if any.
Sourcepub fn selected_ranges(&self) -> &[RowRange]
pub fn selected_ranges(&self) -> &[RowRange]
The ranges TablePath::range added, in the order they will be read.