R/dml.R

In tjpalanca/dbtools: Database Tools for R

#' @title
#' Data Manipulation Language (DML)
#'
#' @description
#' DML statements allow the user to modify  the data in the tables of the
#' database.
#'
#' @param object     (obj) object whose data will be manipulated; either
#'                         a [`tbl_db`] or a [`df_db`] that contains a
#'                         database connection.
#' @param records    (dfm) data frame of records; in the case of a database,
#'                         it is by default the collected data frame from the
#'                         previous operations.
#' @param manip_name (str) string identifier so that we can retrieve the
#'                         returned value after the transformation
#' @param commit     (flg) whether or not to commit the transaction after this
#'                         manipulation is completed
#' @param ...        (arg) extra arguments
#'
#' @family Database Operations
#' @name dml
NULL

#' @describeIn dml insert new rows into a table
#' @inheritParams dbx::dbxInsert
#' @export
insert <- function(object,
                   records,
                   batch_size = NULL,
                   returning  = NULL,
                   manip_name = "",
                   commit = FALSE,
                   ...) {

  UseMethod("insert")

}

#' @describeIn dml modify existing rows with new column values
#' @inheritParams dbx::dbxUpdate
#' @export
update <- function(object,
                   records,
                   where_cols = NULL,
                   batch_size = NULL,
                   manip_name = "",
                   commit = FALSE,
                   ...) {

  UseMethod("update")

}

#' @describeIn dml both modify (in case of same `where_cols`), and insert
#'                 new rows into the table
#' @inheritParams dbx::dbxUpsert
#' @export
upsert <- function(object,
                   records,
                   where_cols = NULL,
                   batch_size = NULL,
                   returning  = NULL,
                   skip_existing = NULL,
                   manip_name = "",
                   commit = FALSE,
                   ...) {

  UseMethod("upsert")

}

#' @describeIn dml delete the rows associated with the table
#' @inheritParams dbx::dbxDelete
#' @export
delete <- function(object,
                   records,
                   batch_size = NULL,
                   manip_name = "",
                   commit = FALSE,
                   ...) {

  UseMethod("delete")

}