% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dbMatrix.R
\name{dbMatrix_from_tbl}
\alias{dbMatrix_from_tbl}
\title{dbMatrix_from_tbl}
\usage{
dbMatrix_from_tbl(
  tbl,
  rownames_colName,
  colnames_colName,
  value_colName = NULL,
  name = "dbMatrix",
  overwrite = FALSE,
  row_names = NULL,
  col_names = NULL,
  i_col = NULL,
  j_col = NULL
)
}
\arguments{
\item{tbl}{\code{tbl_duckdb_connection} table in DuckDB database in long format}

\item{rownames_colName}{\code{character} column name of rownames in tbl \code{(required)}}

\item{colnames_colName}{\code{character} column name of colnames in tbl \code{(required)}}

\item{value_colName}{\code{character} column name containing pre-aggregated integer counts.
If \code{NULL} (default), counts occurrences of each row-column pair. \code{(optional)}}

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

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

\item{row_names}{\code{character} vector of pre-computed row names (sorted). If \code{NULL}
(default), row names are extracted from the table. \code{(optional)}}

\item{col_names}{\code{character} vector of pre-computed column names (sorted). If \code{NULL}
(default), column names are extracted from the table. \code{(optional)}}

\item{i_col}{\code{character} column name containing pre-computed row indices (1-based integers).
If provided with \code{j_col}, skips index encoding for optimal performance. \code{(optional)}}

\item{j_col}{\code{character} column name containing pre-computed column indices (1-based integers).
If provided with \code{i_col}, skips index encoding for optimal performance. \code{(optional)}}
}
\value{
\code{dbMatrix} object
}
\description{
Constructs a \code{dbSparseMatrix} object from a \code{tbl_duckdb_connection} object.
}
\details{
The \code{tbl_duckdb_connection} object must contain dimension names as columns in long format.

If \code{value_colName} is provided, the function uses pre-aggregated counts from that column.
This is useful when the input table already contains aggregated counts (e.g., from a GROUP BY + SUM operation).
If \code{value_colName} is \code{NULL} (default), the function counts occurrences of each row-column pair.

When \code{row_names} and/or \code{col_names} are provided, the function uses these directly
instead of querying distinct values from the table. This can significantly improve performance
when the input table is a complex lazy query (e.g., result of spatial joins).

When \code{i_col} and \code{j_col} are provided, the function uses these pre-computed integer
indices directly, skipping expensive string-to-index encoding. This is the fastest path.
}
\concept{dbMatrix}
