export() as S3 generic for tbl_kusto and kusto_database_endpoint

NAMESPACE

@@ -19,6 +19,7 @@ S3method(escape,integer64)
 S3method(escape,kql)
 S3method(escape,list)
 S3method(escape,logical)
+S3method(export,kusto_database_endpoint)
 S3method(export,tbl_kusto)
 S3method(filter,tbl_kusto_abstract)
 S3method(full_join,tbl_kusto_abstract)
@@ -101,7 +102,6 @@ export(build_kql)
 export(delete_kusto_token)
 export(escape)
 export(export)
-export(export_storage)
 export(filter)
 export(flatten_query)
 export(get_kusto_token)

NEWS.md

@@ -1,7 +1,6 @@
 # AzureKusto 1.1.0
 
-* New function `export_storage()` and dplyr-style `export()` verb function to
-  export query results to Azure Storage.
+* New function `export()` to export query results to Azure Storage.
 * `server` argument of `kusto_database_endpoint` can be just cluster name and no
   longer needs to be the fully qualified URI. E.g. can pass either
   `server = "help"` or `server = "https://help.kusto.windows.net"`

R/tbl.R

@@ -441,7 +441,26 @@ distributed=%s
 }
 
 #' Execute the Kusto query and export the result to Azure Storage.
-#' @param database A Kusto database endpoint object, as returned by `kusto_database_endpoint`.
+#' @param tbl An object representing a table or database.
+#' @param storage_uri The Azure Storage URI to export files to.
+#' @param query A Kusto query string
+#' @param name_prefix The filename prefix to use for exported files.
+#' @param key default "impersonate" which uses the account signed into Kusto to
+#' authenticate to Azure Storage. An Azure Storage account key.
+#' @param format Options are "parquet", "csv", "tsv", "json"
+#' @param distributed logical, indicates whether Kusto should distributed the
+#' export job to multiple nodes, in which case multiple files will be written
+#' to storage concurrently.
+#' @param ... needed for agreement with generic. Not otherwise used.
+#' @rdname export
+#' @export
+export <- function(tbl, storage_uri, query = NULL, name_prefix = "export",
+    key = "impersonate", format = "parquet", distributed = FALSE, ...) {
+    UseMethod("export")
+}
+
+#' Execute the Kusto query and export the result to Azure Storage.
+#' @param tbl A Kusto database endpoint object, as returned by `kusto_database_endpoint`.
 #' @param query A Kusto query string
 #' @param storage_uri The Azure Storage URI to export files to.
 #' @param name_prefix The filename prefix to use for exported files.
@@ -452,47 +471,32 @@ distributed=%s
 #' export job to multiple nodes, in which case multiple files will be written
 #' to storage concurrently.
 #' @param ... needed for agreement with generic. Not otherwise used.
+#' @rdname export
 #' @export
-export_storage <- function(database, query, storage_uri, name_prefix = "export",
+export.kusto_database_endpoint <- function(tbl, storage_uri, query = NULL, name_prefix = "export",
     key = "impersonate", format = "parquet", distributed = FALSE, ...) {
+    if (missing(query)) stop("query parameter is required.")
     is_cmd <- substr(query, 1, 1) == "."
     if (is_cmd) stop("Management commands cannot be used with export()")
     q_str <- kusto_export_cmd(query = query, storage_uri = storage_uri,
         name_prefix = name_prefix, key = key, format = format,
         distributed = distributed)
-    run_query(database, q_str, ...)
-    # TODO: write an integration test for this
+    run_query(tbl, q_str, ...)
 }
 
-#' Execute the Kusto query and export the result to Azure Storage.
-#' @param tbl An instance of class tbl_kusto representing a Kusto table
-#' @param storage_uri The Azure Storage URI to export files to.
-#' @param name_prefix The filename prefix to use for exported files.
-#' @param key default "impersonate" which uses the account signed into Kusto to
-#' authenticate to Azure Storage. An Azure Storage account key.
-#' @param format Options are "parquet", "csv", "tsv", "json"
-#' @param distributed logical, indicates whether Kusto should distributed the
-#' export job to multiple nodes, in which case multiple files will be written
-#' to storage concurrently.
-#' @param ... needed for agreement with generic. Not otherwise used.
+#' @rdname export
 #' @export
-export.tbl_kusto <- function(tbl, storage_uri, name_prefix = "export",
+export.tbl_kusto <- function(tbl, storage_uri, query = NULL, name_prefix = "export",
     key = "impersonate", format = "parquet", distributed = FALSE, ...) {
     database <- tbl$src
-    query <- kql_render(kql_build(tbl))
-    res <- export_storage(database = database, query = query,
-        storage_uri = storage_uri, name_prefix = name_prefix, key = key,
-        format = format, distributed = distributed)
+    q <- kql_render(kql_build(tbl))
+    q_str <- kusto_export_cmd(query = q, storage_uri = storage_uri,
+        name_prefix = name_prefix, key = key, format = format,
+        distributed = distributed)
+    res <- run_query(database, q_str, ...)
     tibble::as_tibble(res)
 }
 
-#' @export
-export <- function(object, ...) {
-    UseMethod("export")
-}
-
-.S3method("export", "tbl_kusto", export.tbl_kusto)
-
 #' @keywords internal
 #' @export
 print.tbl_kusto_abstract <- function(x, ...)

README.md

@@ -188,14 +188,14 @@ MyFunctionDate %>%
 
 ### Exporting to storage
 
-(New in 1.1.0) The function `export_storage()` and dplyr-style verb `export()`
-enable you to export a query result to Azure Storage in one step.
+(New in 1.1.0) The function `export()` enables you to export a query result to
+Azure Storage in one step.
 
 ```r
-export_storage(
+export(
     database = Samples,
-    query = "StormEvents | summarize EventCount = count() by State | order by State",
     storage_uri = "https://mystorage.blob.core.windows.net/StormEvents",
+    query = "StormEvents | summarize EventCount = count() by State | order by State",
     name_prefix = "events",
     format = "parquet"
 )

man/export.Rd

@@ -1,12 +1,37 @@
 % Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/tbl.R
-\name{export.tbl_kusto}
+\name{export}
+\alias{export}
+\alias{export.kusto_database_endpoint}
 \alias{export.tbl_kusto}
 \title{Execute the Kusto query and export the result to Azure Storage.}
 \usage{
+export(
+  tbl,
+  storage_uri,
+  query = NULL,
+  name_prefix = "export",
+  key = "impersonate",
+  format = "parquet",
+  distributed = FALSE,
+  ...
+)
+
+\method{export}{kusto_database_endpoint}(
+  tbl,
+  storage_uri,
+  query = NULL,
+  name_prefix = "export",
+  key = "impersonate",
+  format = "parquet",
+  distributed = FALSE,
+  ...
+)
+
 \method{export}{tbl_kusto}(
   tbl,
   storage_uri,
+  query = NULL,
   name_prefix = "export",
   key = "impersonate",
   format = "parquet",
@@ -15,10 +40,12 @@
 )
 }
 \arguments{
-\item{tbl}{An instance of class tbl_kusto representing a Kusto table}
+\item{tbl}{A Kusto database endpoint object, as returned by \code{kusto_database_endpoint}.}
 
 \item{storage_uri}{The Azure Storage URI to export files to.}
 
+\item{query}{A Kusto query string}
+
 \item{name_prefix}{The filename prefix to use for exported files.}
 
 \item{key}{default "impersonate" which uses the account signed into Kusto to
@@ -33,5 +60,7 @@ to storage concurrently.}
 \item{...}{needed for agreement with generic. Not otherwise used.}
 }
 \description{
+Execute the Kusto query and export the result to Azure Storage.
+
 Execute the Kusto query and export the result to Azure Storage.
 }

man/export_storage.Rd

@@ -1,40 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/tbl.R
-\name{export_storage}
-\alias{export_storage}
-\title{Execute the Kusto query and export the result to Azure Storage.}
-\usage{
-export_storage(
-  database,
-  query,
-  storage_uri,
-  name_prefix = "export",
-  key = "impersonate",
-  format = "parquet",
-  distributed = FALSE,
-  ...
-)
-}
-\arguments{
-\item{database}{A Kusto database endpoint object, as returned by \code{kusto_database_endpoint}.}
-
-\item{query}{A Kusto query string}
-
-\item{storage_uri}{The Azure Storage URI to export files to.}
-
-\item{name_prefix}{The filename prefix to use for exported files.}
-
-\item{key}{default "impersonate" which uses the account signed into Kusto to
-authenticate to Azure Storage. An Azure Storage account key.}
-
-\item{format}{Options are "parquet", "csv", "tsv", "json"}
-
-\item{distributed}{logical, indicates whether Kusto should distributed the
-export job to multiple nodes, in which case multiple files will be written
-to storage concurrently.}
-
-\item{...}{needed for agreement with generic. Not otherwise used.}
-}
-\description{
-Execute the Kusto query and export the result to Azure Storage.
-}