% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/classes.R, R/dbMatrix.R
\name{dbMatrix}
\alias{dbMatrix}
\alias{dbMatrix-class}
\title{S4 virtual class for dbMatrix}
\usage{
dbMatrix(
  value,
  class = NULL,
  con = NULL,
  overwrite = FALSE,
  name = "dbMatrix",
  dims = NULL,
  dim_names = NULL,
  mtx_rowname_file_path,
  mtx_rowname_col_idx = 1,
  mtx_colname_file_path,
  mtx_colname_col_idx = 1,
  ...
)

dbMatrix(
  value,
  class = NULL,
  con = NULL,
  overwrite = FALSE,
  name = "dbMatrix",
  dims = NULL,
  dim_names = NULL,
  mtx_rowname_file_path,
  mtx_rowname_col_idx = 1,
  mtx_colname_file_path,
  mtx_colname_col_idx = 1,
  ...
)
}
\arguments{
\item{value}{data to be added to the database. See details for supported data types \code{(required)}}

\item{class}{class of the dbMatrix: \code{dbDenseMatrix} or \code{dbSparseMatrix} \code{(required)}}

\item{con}{DBI or duckdb connection object \code{(required)}}

\item{overwrite}{whether to overwrite if table already exists in database \code{(required)}}

\item{name}{table name to assign within database \code{(required, default: "dbMatrix")}}

\item{dims}{dimensions of the matrix \code{(optional: [int, int])}}

\item{dim_names}{dimension names of the matrix \code{(optional: list(enum, enum))}}

\item{mtx_rowname_file_path}{path to .mtx rowname file to be read into \code{(optional)}
database. by default, no header is assumed.}

\item{mtx_rowname_col_idx}{column index of row name file \code{(optional)}}

\item{mtx_colname_file_path}{path to .mtx colname file to be read into
database. by default, no header is assumed. \code{(optional)}}

\item{mtx_colname_col_idx}{column index of column name file \code{(optional)}}

\item{...}{additional params to pass to \code{dplyr::copy_to}}
}
\value{
\code{dbMatrix()} returns an initialized \code{\link{dbDenseMatrix}} or
\code{\link{dbSparseMatrix}} S4 object that points to matrix data stored in DuckDB.

A \code{\link{dbDenseMatrix}} or \code{\link{dbSparseMatrix}} object, depending on
\code{class}, pointing to matrix data stored in DuckDB. The object records the
matrix dimensions and dimension names.
}
\description{
Representation of sparse and dense matrices in a database. Each object
is used as a connection to a single table that exists within the database.
Inherits from \code{dbData}.

Create an S4 \code{dbMatrix} object in sparse or dense triplet vector format.
}
\details{
This function reads in data into a pre-existing DuckDB database.
Supported \code{value} data types:
\itemize{
\item \code{\link[Matrix:dgCMatrix-class]{Matrix::dgCMatrix}} In-memory sparse matrix from the \code{\link[Matrix:Matrix]{Matrix::Matrix}} package
\item \code{\link[Matrix:dgTMatrix-class]{Matrix::dgTMatrix}} In-memory triplet vector or COO matrix
\item \code{\link[Matrix:Matrix]{matrix}} In-memory dense matrix from base R
\item \code{.mtx} Path to \href{https://math.nist.gov/MatrixMarket/formats.html}{.mtx} file
\item \code{.csv} Path to .csv file
\item \code{tbl_duckdb_connection} Table in \code{\link[duckdb:duckdb]{duckdb::duckdb}} database in ijx format from
existing \code{\link{dbMatrix}} object. \code{dims} and \code{dim_names} must be
specified if \code{value} is \code{tbl_duckdb_connection}.
}
}
\section{Slots}{

\describe{
\item{\code{dim_names}}{row (1) and col (2) names}

\item{\code{dims}}{dimensions of the matrix}

\item{\code{init}}{logical. Whether the object is fully initialized}
}}

\examples{
dgc <- readRDS(system.file("extdata", "dgc.rds", package = "dbMatrix"))
con <- DBI::dbConnect(duckdb::duckdb(), ":memory:")
dbSparse <- dbMatrix(
  value = dgc,
  con = con,
  name = "sparse_matrix",
  class = "dbSparseMatrix",
  overwrite = TRUE
)
dbSparse
}
\concept{dbMatrix}
\keyword{internal}
