r/man/Table.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/table.R
\docType{class}
\name{Table}
\alias{Table}
\alias{arrow_table}
\title{Table class}
\usage{
arrow_table(..., schema = NULL)
}
\arguments{
\item{...}{A \code{data.frame} or a named set of Arrays or vectors. If given a
mixture of data.frames and named vectors, the inputs will be autospliced together
(see examples). Alternatively, you can provide a single Arrow IPC
\code{InputStream}, \code{Message}, \code{Buffer}, or R \code{raw} object containing a \code{Buffer}.}

\item{schema}{a \link{Schema}, or \code{NULL} (the default) to infer the schema from
the data in \code{...}. When providing an Arrow IPC buffer, \code{schema} is required.}
}
\description{
A Table is a sequence of \link[=ChunkedArray]{chunked arrays}. They
have a similar interface to \link[=RecordBatch]{record batches}, but they can be
composed from multiple record batches or chunked arrays.
}
\section{S3 Methods and Usage}{

Tables are data-frame-like, and many methods you expect to work on
a \code{data.frame} are implemented for \code{Table}. This includes \code{[}, \code{[[},
\code{$}, \code{names}, \code{dim}, \code{nrow}, \code{ncol}, \code{head}, and \code{tail}. You can also pull
the data from an Arrow table into R with \code{as.data.frame()}. See the
examples.

A caveat about the \code{$} method: because \code{Table} is an \code{R6} object,
\code{$} is also used to access the object's methods (see below). Methods take
precedence over the table's columns. So, \code{tab$Slice} would return the
"Slice" method function even if there were a column in the table called
"Slice".
}

\section{R6 Methods}{

In addition to the more R-friendly S3 methods, a \code{Table} object has
the following R6 methods that map onto the underlying C++ methods:
\itemize{
\item \verb{$column(i)}: Extract a \code{ChunkedArray} by integer position from the table
\item \verb{$ColumnNames()}: Get all column names (called by \code{names(tab)})
\item \verb{$RenameColumns(value)}: Set all column names (called by \code{names(tab) <- value})
\item \verb{$GetColumnByName(name)}: Extract a \code{ChunkedArray} by string name
\item \verb{$field(i)}: Extract a \code{Field} from the table schema by integer position
\item \verb{$SelectColumns(indices)}: Return new \code{Table} with specified columns, expressed as 0-based integers.
\item \verb{$Slice(offset, length = NULL)}: Create a zero-copy view starting at the
indicated integer offset and going for the given length, or to the end
of the table if \code{NULL}, the default.
\item \verb{$Take(i)}: return an \code{Table} with rows at positions given by
integers \code{i}. If \code{i} is an Arrow \code{Array} or \code{ChunkedArray}, it will be
coerced to an R vector before taking.
\item \verb{$Filter(i, keep_na = TRUE)}: return an \code{Table} with rows at positions where logical
vector or Arrow boolean-type \verb{(Chunked)Array} \code{i} is \code{TRUE}.
\item \verb{$SortIndices(names, descending = FALSE)}: return an \code{Array} of integer row
positions that can be used to rearrange the \code{Table} in ascending or descending
order by the first named column, breaking ties with further named columns.
\code{descending} can be a logical vector of length one or of the same length as
\code{names}.
\item \verb{$serialize(output_stream, ...)}: Write the table to the given
\link{OutputStream}
\item \verb{$cast(target_schema, safe = TRUE, options = cast_options(safe))}: Alter
the schema of the record batch.
}

There are also some active bindings:
\itemize{
\item \verb{$num_columns}
\item \verb{$num_rows}
\item \verb{$schema}
\item \verb{$metadata}: Returns the key-value metadata of the \code{Schema} as a named list.
Modify or replace by assigning in (\code{tab$metadata <- new_metadata}).
All list elements are coerced to string. See \code{schema()} for more information.
\item \verb{$columns}: Returns a list of \code{ChunkedArray}s
}
}

\examples{
\dontshow{if (arrow_available()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
tbl <- arrow_table(name = rownames(mtcars), mtcars)
dim(tbl)
dim(head(tbl))
names(tbl)
tbl$mpg
tbl[["cyl"]]
as.data.frame(tbl[4:8, c("gear", "hp", "wt")])
\dontshow{\}) # examplesIf}
}