---
title: "ClikaRT::tables::Table"
sidebar_label: "Table"
description: "A columnar dataframe: an ordered set of named, typed columns sharing one row count (see the file overview for the model)."
---

<!-- Generated by tools/doxygen2mdx from Doxygen XML. Do not edit. -->

<span class="api-kind api-kind--class">class</span>

**Header:** `ClikaRT/tables/table.h`

A columnar dataframe: an ordered set of named, typed columns sharing one row count (see the file overview for the model). Build with [`create()`](./Table.md#create) + [`add_column`](./Table.md#add_column) / [`read_csv`](./Table.md#read_csv), read columns back as tensors, iterate rows with [`rows()`](./Table.md#rows), transform with the verb methods, and mutate columns in place via `frame[name]`.

## Nested types

| Name | Description |
| --- | --- |
| [`AggSpec`](./Table.AggSpec.md) | One aggregation of a [`group_by`](./Table.md#group_by): the column, the reduction, and the output name. |
| [`ColumnRef`](./Table.ColumnRef.md) | The handle returned by `frame[name]`. Compound ops mutate the live column (the scalar broadcasts); `= tensor` creates or replaces the column. On a failure (missing column, non-numeric, length mismatch) the op raises [`ClikaRT::Error`](../Error.md) in your translation unit, in BOTH library modes: a chaining operator returns `*this` and cannot carry a [`Result`](../Result.md), so this block is the documented mode-invariant throwing surface. [`pow`](./Table.ColumnRef.md#pow-2) / [`floordiv`](./Table.ColumnRef.md#floordiv-2) are methods (C++ has no `**` / `//`). |
| [`Row`](./Table.Row.md) | A lightweight read cursor over one row: just `{table, `[`row`](./Table.md#row)` `[`index`](./Table.Row.md#index)`}`, no copy of the row's data. Typed getters WIDEN to the requested type: any integer (or Bool) column reads through [`get_int`](./Table.Row.md#get_int), any float column through [`get_double`](./Table.Row.md#get_double), a String column through [`get_string`](./Table.Row.md#get_string). Each raises [`ClikaRT::Error`](../Error.md) on a missing column, a null cell, or a column whose dtype the getter can't produce (e.g. [`get_int`](./Table.Row.md#get_int) on a float column). Obtain a [Row](./Table.Row.md) from [`rows()`](./Table.md#rows) or `row(i)`; the frame must outlive it. |
| [`RowRange`](./Table.RowRange.md) | A range over every row, in order, range-for compatible: `for (`[`Table::Row`](./Table.Row.md)` `[`row`](./Table.md#row)` : frame.rows()) { ... }`. Yields [`Row`](./Table.Row.md) by value (the cheap cursor; no per-row allocation). The frame must outlive the range. |
| [`SortKey`](./Table.SortKey.md) | One key of a multi-key sort (most significant first), with its own direction and null placement. |

## Types

### enum SortOrder {#SortOrder}

<div class="api-signature">

`enum class` **`SortOrder`**

</div>

Sort direction for [`sort_by`](./Table.md#sort_by).

| Enumerator | Description |
| --- | --- |
| `Ascending` |  |
| `Descending` |  |

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 200

</div>

### enum NullOrder {#NullOrder}

<div class="api-signature">

`enum class` **`NullOrder`**

</div>

Null placement for a multi-key sort.

| Enumerator | Description |
| --- | --- |
| `First` |  |
| `Last` |  |

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 202

</div>

### enum JoinKind {#JoinKind}

<div class="api-signature">

`enum class` **`JoinKind`**

</div>

Join flavor for [`join`](./Table.md#join): `Inner` keeps matched rows only; `Left` / `Right` additionally keep that side's unmatched rows (nulls fill the other side); `Outer` keeps both sides' unmatched rows.

| Enumerator | Description |
| --- | --- |
| `Inner` |  |
| `Left` |  |
| `Right` |  |
| `Outer` |  |

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 206

</div>

### enum Agg {#Agg}

<div class="api-signature">

`enum class` **`Agg`**

</div>

Group-by aggregations, each over a group's non-null values: `Count` (the non-null count), `Sum`, `Mean`, `Min`, `Max`, `Prod`.

| Enumerator | Description |
| --- | --- |
| `Count` |  |
| `Sum` |  |
| `Mean` |  |
| `Min` |  |
| `Max` |  |
| `Prod` |  |

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 209

</div>

## Static member functions

### create() {#create}

<div class="api-signature">

`static` [`Table`](./Table.md) **`create`**()

</div>

An empty frame; add columns with [`add_column`](./Table.md#add_column) / [`add_string_column`](./Table.md#add_string_column).

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 56

</div>

### read\_csv() {#read_csv}

<div class="api-signature">

`static` [`Table`](./Table.md) **`read_csv`**(`std::string_view` `path`, `const` [`CsvReadOptions`](./CsvReadOptions.md)`&` `options` `=` `{}`)

</div>

Read an RFC-4180 CSV file / string into a frame (dtypes inferred). `path` / `text` is copied, not retained.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 82

</div>

### read\_csv\_string() {#read_csv_string}

<div class="api-signature">

`static` [`Table`](./Table.md) **`read_csv_string`**(`std::string_view` `text`, `const` [`CsvReadOptions`](./CsvReadOptions.md)`&` `options` `=` `{}`)

</div>

The string form of [`read_csv`](./Table.md#read_csv): parse `text` as CSV (dtypes inferred).

**Throws**

- `ClikaRT::Error`: on malformed CSV.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 85

</div>

## Member functions

### Table(Table) {#Table}

<div class="api-signature">

**`Table`**(`const Table&` `other`)

</div>

Deep copy: the new frame owns independent columns.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 59

</div>

### operator=(Table) {#operator-assign}

<div class="api-signature">

[`Table`](./Table.md)`&` **`operator=`**(`const` [`Table`](./Table.md)`&` `other`)

</div>

Deep-copy assignment: this frame's columns are replaced by copies of `other`'s.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 61

</div>

### Table(Table) {#Table-2}

<div class="api-signature">

**`Table`**(`Table&&` `other`) `noexcept`

</div>

Move: takes `other`'s columns; `other` is left empty.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 63

</div>

### operator=(Table) {#operator-assign-2}

<div class="api-signature">

[`Table`](./Table.md)`&` **`operator=`**([`Table`](./Table.md)`&&` `other`) `noexcept`

</div>

Move assignment: takes `other`'s columns.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 65

</div>

### \~Table() {#Table-3}

<div class="api-signature">

**`~Table`**()

</div>

Releases the frame's columns.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 67

</div>

### add\_column() {#add_column}

<div class="api-signature">

`void` **`add_column`**(`std::string_view` `name`, `const` [`Tensor`](../Tensor.md)`&` `values`)

</div>

Append a numeric column from a 1-D CPU tensor (its data is copied in). The first column fixes the row count; later columns must match it. The dtype follows the tensor's. Errors on a non-1-D / non-numeric tensor, a duplicate name, or a length mismatch.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 74

</div>

### add\_string\_column() {#add_string_column}

<div class="api-signature">

`void` **`add_string_column`**(`std::string_view` `name`, [`ClikaRT::Span`](../Span.md)`<const std::string_view>` `values`)

</div>

Append a string column (one value per row; the strings are copied in).

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 76

</div>

### write\_csv() {#write_csv}

<div class="api-signature">

`void` **`write_csv`**(`std::string_view` `path`) `const`

</div>

Write the frame as CSV to `path`, or render it to a string.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 87

</div>

### to\_csv\_string() {#to_csv_string}

<div class="api-signature">

`std::string` **`to_csv_string`**() `const`

</div>

Render the frame as CSV text, the write half of the round trip: a frame rendered here reads back with [`read_csv_string`](./Table.md#read_csv_string) (dtypes re-inferred).

**Throws**

- `ClikaRT::Error`: when rendering fails.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 91

</div>

### num\_rows() {#num_rows}

<div class="api-signature">

`std::int64_t` **`num_rows`**() `const`

</div>

Number of rows (0 for an empty frame).

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 95

</div>

### num\_columns() {#num_columns}

<div class="api-signature">

`std::int64_t` **`num_columns`**() `const`

</div>

Number of columns.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 97

</div>

### column\_names() {#column_names}

<div class="api-signature">

`std::vector<std::string>` **`column_names`**() `const`

</div>

The column names, in column order.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 99

</div>

### contains() {#contains}

<div class="api-signature">

`bool` **`contains`**(`std::string_view` `name`) `const`

</div>

True when a column named `name` exists.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 101

</div>

### column() {#column}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`column`**(`std::string_view` `name`) `const`

</div>

Materialize a numeric column as a 1-D owning tensor (a copy, safe to keep past the table's lifetime). Errors on a missing or non-numeric column.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 106

</div>

### null\_count() {#null_count}

<div class="api-signature">

`std::int64_t` **`null_count`**(`std::string_view` `name`) `const`

</div>

Per-column null inspection. Nulls arise from a CSV empty field / a `null_tokens` match, or a null-producing op. Errors on a missing column.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 110

</div>

### has\_nulls() {#has_nulls}

<div class="api-signature">

`bool` **`has_nulls`**(`std::string_view` `name`) `const`

</div>

True when the column carries at least one null.

**Throws**

- `ClikaRT::Error`: on a missing column (as [`null_count`](./Table.md#null_count)).

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 113

</div>

### to\_string() {#to_string}

<div class="api-signature">

`std::string` **`to_string`**() `const`

</div>

Render the frame pandas-style (a large frame elides to its head + tail).

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 116

</div>

### rows() {#rows}

<div class="api-signature">

[`RowRange`](./Table.RowRange.md) **`rows`**() `const`

</div>

Every row as a range, for `for (`[`Table::Row`](./Table.Row.md)` `[`row`](./Table.md#row)` : frame.rows())`.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 190

</div>

### row() {#row}

<div class="api-signature">

[`Row`](./Table.Row.md) **`row`**(`std::int64_t` `i`) `const`

</div>

The row at `i` (0-based). Raises [`ClikaRT::Error`](../Error.md) if `i` is out of range.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 192

</div>

### select() {#select}

<div class="api-signature">

[`Table`](./Table.md) **`select`**([`ClikaRT::Span`](../Span.md)`<const std::string_view>` `names`) `const`

</div>

Keep only `names`, in that order (a projection).

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 225

</div>

### head() {#head}

<div class="api-signature">

[`Table`](./Table.md) **`head`**(`std::int64_t` `n` `=` `5`) `const`

</div>

The first / last `n` rows.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 227

</div>

### tail() {#tail}

<div class="api-signature">

[`Table`](./Table.md) **`tail`**(`std::int64_t` `n` `=` `5`) `const`

</div>

The last `n` rows (default 5), [`head`](./Table.md#head)'s tail-end sibling.

**Throws**

- `ClikaRT::Error`: as [`head`](./Table.md#head).

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 230

</div>

### slice() {#slice}

<div class="api-signature">

[`Table`](./Table.md) **`slice`**(`std::int64_t` `offset`, `std::int64_t` `count`) `const`

</div>

`count` rows starting at `offset`.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 232

</div>

### sort\_by(string\_view, SortOrder) {#sort_by}

<div class="api-signature">

[`Table`](./Table.md) **`sort_by`**(`std::string_view` `column`, [`SortOrder`](./Table.md#SortOrder) `order` `=` [`SortOrder::Ascending`](./Table.md#SortOrder)) `const`

</div>

Stable sort by one column.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 234

</div>

### sort\_by(Span\< SortKey\>) {#sort_by-2}

<div class="api-signature">

[`Table`](./Table.md) **`sort_by`**([`ClikaRT::Span`](../Span.md)`<const` [`SortKey`](./Table.SortKey.md)`>` `keys`) `const`

</div>

Stable multi-key sort (keys most-significant-first; per-key direction + null placement).

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 237

</div>

### unique() {#unique}

<div class="api-signature">

[`Table`](./Table.md) **`unique`**(`std::string_view` `column`) `const`

</div>

Distinct values of a column (first-seen order), as a 1-column frame.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 239

</div>

### value\_counts() {#value_counts}

<div class="api-signature">

[`Table`](./Table.md) **`value_counts`**(`std::string_view` `column`) `const`

</div>

Frequency of each distinct non-null value, as a `value`+`count` frame sorted by count descending.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 242

</div>

### filter() {#filter}

<div class="api-signature">

[`Table`](./Table.md) **`filter`**(`const` [`Tensor`](../Tensor.md)`&` `mask`) `const`

</div>

Keep the rows where the Bool `mask` (one element per row) is true.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 244

</div>

### group\_by() {#group_by}

<div class="api-signature">

[`Table`](./Table.md) **`group_by`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const std::string_view>` `keys`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const` [`AggSpec`](./Table.AggSpec.md)`>` `aggs`<br />
) `const`

</div>

Group by `keys` and apply `aggs`, one row per group: the key columns then one column per aggregation.

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 247

</div>

### join() {#join}

<div class="api-signature">

[`Table`](./Table.md) **`join`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`const` [`Table`](./Table.md)`&` `other`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`ClikaRT::Span`](../Span.md)`<const std::string_view>` `on`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`JoinKind`](./Table.md#JoinKind) `kind` `=` [`JoinKind::Inner`](./Table.md#JoinKind)<br />
) `const`

</div>

Equi-join with `other` on the `on` columns (present in both, same dtype).

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 250

</div>

### operator\[\]() {#operator-subscript}

<div class="api-signature">

[`ColumnRef`](./Table.ColumnRef.md) **`operator[]`**(`std::string_view` `name`)

</div>

<div class="api-declared">

Declared in `ClikaRT/tables/table.h`, line 318

</div>