> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turntable.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Table Operations

## aggregate

Returns an aggregated table for cols, grouped by `by` and `sort`.

If fill is specified, the table will be interpolated using the specified fill strategy, taking into account direction from the `sort` argument. `fill` can either be a single value or a list of values, one for each column in `cols`.

<Accordion title="Parameters">
  <ParamField body="cols" type="column_type" required={true} />

  <ParamField body="by" type="column_type | None" required={false} />

  <ParamField body="sort" type="column_type | None" required={false} />

  <ParamField body="fill" type="fill_type" required={false} />
</Accordion>

***

## aggregate\_all

Aggregate\_all is a generalized form of `aggregate` that can apply apply the same operation (specified in *f*) to multiple columns. The col\_selector field can be a list of column fields, where each element  `select`, and *f* should be a list of functions of the same length.

If *f* is a single function, it will be applied to all columns. If *f* is a list of functions, the functions will be applied to the corresponding columns. If *f* is shorter than the number of columns, the last function will be applied to all remaining columns.

By, sort, and fill operate as in `aggregate`.

If rename is True, the columns will be renamed to the name of the function that was applied to them. If rename is False, the columns will names to the original column name.

<Accordion title="Parameters">
  <ParamField body="col_selector" type="column_type_all" required={true} />

  <ParamField body="f" type="Callable[[Any], Any] | list[Callable[[Any], Any] | None] | None" required={true} />

  <ParamField body="by" type="column_type | None" required={false} />

  <ParamField body="sort" type="column_type | None" required={false} />

  <ParamField body="fill" type="fill_type" required={false} />

  <ParamField body="rename" type="bool" required={false} />
</Accordion>

***

## chart

Visualize the table using a chart. The geoms argument should be a geom or a list of geoms. The x, y, color, fill, size, alpha, and facet arguments should be column expressions. If a list of columns is passed, the chart will be faceted by the columns in the list.

If coord\_flip is True, the x and y axes will be flipped.

<Accordion title="Parameters">
  <ParamField body="geoms" type="geom | list[Any]" required={true} />

  <ParamField body="x" type="ir.Value | None" required={true} />

  <ParamField body="y" type="ir.Value | None" required={false} />

  <ParamField body="color" type="ir.Value | None" required={false} />

  <ParamField body="fill" type="ir.Value | None" required={false} />

  <ParamField body="size" type="ir.Value | None" required={false} />

  <ParamField body="alpha" type="ir.Value | None" required={false} />

  <ParamField body="facet" type="ir.Value | list[ir.Value] | None" required={false} />

  <ParamField body="coord_flip" type="bool" required={false} />

  <ParamField body="interactive" type="bool" required={false} default="True" />
</Accordion>

***

## copy

None

<Accordion title="Parameters">
  <ParamField body="mutable" type="bool | None" required={false} />
</Accordion>

***

## count

Return the count of rows in the table.

<Accordion title="Parameters">
  <ParamField body="where" type="base_boolean_column_type | None" required={false} />

  <ParamField body="distinct" type="bool" required={false} />
</Accordion>

***

## define

Mutate is identical to `select`, except all current columns are included, and the new columns are added to the table. If a new column has the same name as an existing column, the existing column will be replaced.

<Accordion title="Parameters">
  <ParamField body="cols" type="column_type" required={true} />

  <ParamField body="by" type="column_type | None" required={false} />

  <ParamField body="sort" type="column_type | None" required={false} />

  <ParamField body="window_type" type="WindowType" required={false} default="WindowType.rows" />

  <ParamField body="window_bounds" type="tuple[int | None, int | None]" required={false} default="(None, None)" />

  <ParamField body="fill" type="fill_type" required={false} />
</Accordion>

***

## define\_all

Mutate\_all is identical to `select_all`, except all current columns are included, and the new columns are added to the table. If a new column has the same name as an existing column, the existing column will be replaced.

<Accordion title="Parameters">
  <ParamField body="col_selector" type="column_type_all" required={true} />

  <ParamField body="f" type="Callable[..., Any] | list[Callable[..., Any] | None] | None" required={true} />

  <ParamField body="by" type="column_type | None" required={false} />

  <ParamField body="sort" type="column_type | None" required={false} />

  <ParamField body="window_type" type="WindowType" required={false} default="WindowType.rows" />

  <ParamField body="window_bounds" type="tuple[int | None, int | None]" required={false} default="(None, None)" />

  <ParamField body="fill" type="fill_type" required={false} />

  <ParamField body="rename" type="bool" required={false} />
</Accordion>

***

## distinct

Return distinct rows from the table.

If `on` is specified, the distinct rows will be based on the columns in `on`. If it is not, the distinct rows will be based on all columns.

If `keep` is specified, the first or last row will be kept.

<Accordion title="Parameters">
  <ParamField body="on" type="column_type_without_dict | None" required={false} />

  <ParamField body="keep" type="Literal['first', 'last'] | None" required={false} default="first" />
</Accordion>

***

## drop

Remove columns from the table.

<Accordion title="Parameters">
  <ParamField body="cols" type="column_type_without_dict" required={true} />
</Accordion>

***

## dropna

Remove rows from the table with missing values.

If `on` is specified, the missing values will be checked for the columns in `on`. If it is not, the missing values will be checked for all columns.

If `how` is "any", the row will be removed if any of the values are missing. If it is "all", the row will be removed if all of the values are missing.

<Accordion title="Parameters">
  <ParamField body="on" type="column_type_without_dict | None" required={false} />

  <ParamField body="how" type="Literal['any', 'all']" required={false} default="any" />
</Accordion>

***

## eda

Return summary statistics for each column in the table.

If cols is specified, the summary statistics will be returned for the columns in cols. If it is not, the summary statistics will be returned for all columns.

<Accordion title="Parameters">
  <ParamField body="cols" type="column_type | None" required={false} />

  <ParamField body="topk" type="int" required={false} default="3" />
</Accordion>

***

## execute

Run the query and return the result in the specified format. If twin is True, the twin connection will be used.

<Accordion title="Parameters">
  <ParamField body="format" type="Literal['pandas', 'polars', 'pyarrow', 'torch', 'text']" required={false} default="pandas" />

  <ParamField body="twin" type="bool" required={false} />

  <ParamField body="limit" type="int | None" required={false} default="10000" />
</Accordion>

***

## filter

Filter the table based on the conditions specified. This function should be used in place of WHERE, HAVING, and QUALIFY clauses in SQL.

<Accordion title="Parameters">
  <ParamField body="conditions" type="boolean_column_type" required={true} />
</Accordion>

***

## filter\_all

Similar to other "\_all" variants, this is a generalized form of `filter` that can apply the same operation (specified in *condition\_f*) to multiple columns.

The col\_selector field can be a list of column fields, where each element  `select`, and *condition\_f* should be a list of functions of the same length.

Useful if you want to apply the same filter (e.g. value > 0) to multiple columns.

Conditions are evaluated together using the condition\_type argument. If condition\_type is "and", all conditions must be met. If condition\_type is "or", any condition can be met. If you'd like to use a mix of "and" and "or" conditions, call the `filter` function multiple times.

<Accordion title="Parameters">
  <ParamField body="col_selector" type="column_type_all" required={true} />

  <ParamField body="condition_f" type="Callable[..., Any] | list[Callable[..., Any] | None] | None" required={true} />

  <ParamField body="condition_type" type="Literal['and', 'or']" required={false} default="and" />
</Accordion>

***

## from\_file

Create a VinylTable from a csv, json, or parquet file

<Accordion title="Parameters">
  <ParamField body="path" type="str" required={true} />
</Accordion>

***

## from\_memory

Create a VinylTable from a pandas, polars, or pyarrow object

<Accordion title="Parameters">
  <ParamField body="data" type="pd.DataFrame | pl.DataFrame | pa.Table" required={true} />
</Accordion>

***

## get\_name

Return the name of the table.

***

## limit

Return the first `n` rows of the table, starting at the `offset` row.

Note that the result set may not be idempotent.

<Accordion title="Parameters">
  <ParamField body="n" type="int | None" required={true} />

  <ParamField body="offset" type="int" required={false} />
</Accordion>

***

## pickle

None

<Accordion title="Parameters">
  <ParamField body="path" type="str | Path" required={true} />

  <ParamField body="tbl_only" type="string" required={false} default="True" />
</Accordion>

***

## relocate

Relocate columns before or after other specified columns.

<Accordion title="Parameters">
  <ParamField body="cols" type="column_type_without_dict" required={true} />

  <ParamField body="before" type="base_column_type | s.Selector | None" required={false} />

  <ParamField body="after" type="base_column_type | s.Selector | None" required={false} />
</Accordion>

***

## rename

Rename columns in the table. The rename\_dict should be a dictionary with the new column name as the key and the original column name as the value.

<Accordion title="Parameters">
  <ParamField body="rename_dict" type="dict[str, str]" required={true} />
</Accordion>

***

## sample

Sample a fraction of rows from a table. Results may not be idempotent.

See specific note from Ibis below:

Sampling is by definition a random operation. Some backends support specifying a seed for repeatable results, but not all backends support that option. And some backends (duckdb, for example) do support specifying a seed but may still not have repeatable results in all cases.
In all cases, results are backend-specific. An execution against one backend is unlikely to sample the same rows when executed against a different backend, even with the same seed set.

<Accordion title="Parameters">
  <ParamField body="fraction" type="float" required={true} />

  <ParamField body="method" type="Literal['row', 'block']" required={true} />
</Accordion>

***

## save

Run the query and save the result to the specified path in the specified format.

<Accordion title="Parameters">
  <ParamField body="path" type="str | Path" required={true} />

  <ParamField body="format" type="Literal['csv', 'delta', 'json', 'parquet']" required={false} default="csv" />

  <ParamField body="limit" type="string" required={false} default="10000" />
</Accordion>

***

## schema

Return the schema of the table.

***

## select

Computes a new table with the columns in cols. Can be a single column, a list of columns, or a dictionary of columns with their new names as keys. The column values themselves can be specified as strings (the column name), table attributes, one-argument lambda functions, or selectors.

If an aggregated column is passed, this will be treated as a windowed column, using the by field for partitioning, the sort field for ordering, and the window\_type and window\_bounds fields for the actual window.

Fill can be used optionally to add interpolation to cols. You must either specify one value for each column or a list of values that is the same length as the column list

<Accordion title="Parameters">
  <ParamField body="cols" type="column_type" required={true} />

  <ParamField body="by" type="column_type | None" required={false} />

  <ParamField body="sort" type="column_type | None" required={false} />

  <ParamField body="window_type" type="WindowType" required={false} default="WindowType.rows" />

  <ParamField body="window_bounds" type="tuple[int | None, int | None]" required={false} default="(None, None)" />

  <ParamField body="fill" type="fill_type" required={false} />
</Accordion>

***

## select\_all

Select\_all is a generalized form of `select` that can apply apply the same operation (specified in *f*) to multiple columns. The col\_selector field can be a list of column fields, where each element  `select`, and *f* should be a list of functions of the same length.

If *f* is a single function, it will be applied to all columns. If *f* is a list of functions, the functions will be applied to the corresponding columns. If *f* is shorter than the number of columns, the last function will be applied to all remaining columns.

By, sort, window\_type, and window\_bounds operate as in `select`.

If rename is True, the columns will be renamed to the name of the function that was applied to them. If rename is False, the columns will names to the original column name.

<Accordion title="Parameters">
  <ParamField body="col_selector" type="column_type_all" required={true} />

  <ParamField body="f" type="Callable[[Any], Any] | list[Callable[[Any], Any] | None] | None" required={true} />

  <ParamField body="by" type="column_type | None" required={false} />

  <ParamField body="sort" type="column_type | None" required={false} />

  <ParamField body="window_type" type="WindowType" required={false} default="WindowType.rows" />

  <ParamField body="window_bounds" type="tuple[int | None, int | None]" required={false} default="(None, None)" />

  <ParamField body="fill" type="fill_type" required={false} />

  <ParamField body="rename" type="bool" required={false} />
</Accordion>

***

## sort

Sort the table by the columns in `by`.

If `by` is not specified, the table will be sorted by all columns.

To sort a column in descending order, place a `-` in front of the column.

<Accordion title="Parameters">
  <ParamField body="by" type="column_type | None" required={false} />
</Accordion>

***

## to\_sql

Output the table as a SQL string. The dialect argument can be used to specify the SQL dialect to use.

If optimized is True, the SQL will be optimized using the SQLglot optimizer. If formatted is True, the SQL will be formatted for readability.

<Accordion title="Parameters">
  <ParamField body="dialect" type="string" required={false} default="duckdb" />

  <ParamField body="optimized" type="string" required={false} />

  <ParamField body="formatted" type="string" required={false} default="True" />
</Accordion>

***

## visualize

Print a visualize representation of the query plan

***