R/db_alldocs.R

In ropensci/sofa: Connector to 'CouchDB'

#' List all docs in a given database.
#'
#' @export
#' @template all
#' @template return
#' @param dbname Database name. (character)
#' @param descending Return in descending order? (logical)
#' @param startkey Document ID to start at. (character)
#' @param endkey Document ID to end at. (character)
#' @param limit Number document IDs to return. (numeric)
#' @param include_docs (logical) If `TRUE`, returns docs themselves,
#' in addition to IDs. Default: `FALSE`
#' @param disk write to disk or not. By default, data is in the R session;
#' if you give a file path, we'll write data to disk and you'll get back
#' the file path. by default, we save in the R session
#' @examples \dontrun{
#' user <- Sys.getenv("COUCHDB_TEST_USER")
#' pwd <- Sys.getenv("COUCHDB_TEST_PWD")
#' (x <- Cushion$new(user = user, pwd = pwd))
#'
#' if ("leothelion" %in% db_list(x)) {
#'   invisible(db_delete(x, dbname = "leothelion"))
#' }
#' db_create(x, dbname = "leothelion")
#' db_bulk_create(x, mtcars, dbname = "leothelion")
#'
#' db_alldocs(x, dbname = "leothelion")
#' db_alldocs(x, dbname = "leothelion", as = "json")
#' db_alldocs(x, dbname = "leothelion", limit = 2)
#' db_alldocs(x, dbname = "leothelion", limit = 2, include_docs = TRUE)
#'
#' # curl options
#' res <- db_alldocs(x, dbname = "leothelion", verbose = TRUE)
#'
#' # write data to disk - useful when data is very large
#' ## create omdb dataset first
#' file <- system.file("examples/omdb.json", package = "sofa")
#' strs <- readLines(file)
#' if ("omdb" %in% db_list(x)) {
#'   invisible(db_delete(x, dbname = "omdb"))
#' }
#' db_create(x, dbname = "omdb")
#' invisible(db_bulk_create(x, "omdb", strs))
#'
#' ## get all docs, writing them to disk
#' res <- db_alldocs(x, dbname = "omdb", disk = (f <- tempfile(fileext = ".json")))
#' res
#' readLines(res, n = 10)
#' }
db_alldocs <- function(
    cushion, dbname, descending = NULL, startkey = NULL,
    endkey = NULL, limit = NULL, include_docs = FALSE, as = "list",
    disk = NULL, ...) {
  check_cushion(cushion)
  check_if(include_docs, "logical")
  args <- sc(list(
    descending = descending, startkey = startkey, endkey = endkey,
    limit = limit, include_docs = asl(include_docs)
  ))
  call_ <- sprintf("%s/%s/_all_docs", cushion$make_url(), dbname)
  if (is.null(disk)) {
    sofa_GET(call_, as,
      query = args, cushion$get_headers(),
      cushion$get_auth(), ...
    )
  } else {
    sofa_GET_disk(call_, as,
      query = args, cushion$get_headers(),
      cushion$get_auth(), disk, ...
    )
  }
}