зеркало из https://github.com/Azure/AzureCosmosR.git
doc polish, add readme
This commit is contained in:
Hong Ooi
Родитель
8d96479ff5
Коммит
82c525c228
|
|
@ -80,3 +80,4 @@ export(list_stored_procedures)
|
|||
export(process_cosmos_response)
|
||||
export(query_documents)
|
||||
export(replace_stored_procedure)
|
||||
import(AzureRMR)
|
||||
|
|
|
|||
|
|
@ -1,3 +1,6 @@
|
|||
#' @import AzureRMR
|
||||
NULL
|
||||
|
||||
utils::globalVariables(c("self", "private"))
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -51,17 +51,18 @@ NULL
|
|||
#'
|
||||
#' @rdname get_cosmosdb_account
|
||||
#' @name get_cosmosdb_account
|
||||
#' @aliases get_cosmosdb_account
|
||||
#' @aliases get_cosmosdb_account list_cosmosdb_accounts
|
||||
#' @section Usage:
|
||||
#' ```
|
||||
#' get_cosmosdb_account(name)
|
||||
#' list_cosmosdb_accounts()
|
||||
#' ```
|
||||
#' @section Arguments:
|
||||
#' - `name`: The name of the Cosmos DB account.
|
||||
#' @section Details:
|
||||
#' This method retrieves the details for an existing Azure Cosmos DB account.
|
||||
#' `get_cosmosdb_account` retrieves the details for an existing Azure Cosmos DB account. `list_cosmosdb_accounts` retrieves all the Cosmos DB accounts within the resource group.
|
||||
#' @section Value:
|
||||
#' An object of class `az_cosmosdb` representing the Cosmos DB account.
|
||||
#' For `get_cosmosdb_account`, an object of class `az_cosmosdb` representing the Cosmos DB account. For `list_cosmosdb_accounts`, a list of such objects.
|
||||
#' @seealso
|
||||
#' [create_cosmosdb_account], [delete_cosmosdb_account]
|
||||
#'
|
||||
|
|
@ -103,7 +104,7 @@ NULL
|
|||
|
||||
add_methods <- function()
|
||||
{
|
||||
AzureRMR::az_resource_group$set("public", "create_cosmosdb_account", overwrite=TRUE,
|
||||
az_resource_group$set("public", "create_cosmosdb_account", overwrite=TRUE,
|
||||
function(name, location=self$location,
|
||||
interface=c("sql", "cassandra", "mongo", "table", "graph"),
|
||||
serverless=FALSE, free_tier=FALSE,
|
||||
|
|
@ -146,14 +147,39 @@ add_methods <- function()
|
|||
kind=kind, properties=properties, wait=wait, ...)
|
||||
})
|
||||
|
||||
AzureRMR::az_resource_group$set("public", "get_cosmosdb_account", overwrite=TRUE,
|
||||
az_resource_group$set("public", "get_cosmosdb_account", overwrite=TRUE,
|
||||
function(name)
|
||||
{
|
||||
AzureCosmosR::az_cosmosdb$new(self$token, self$subscription, self$name,
|
||||
type="Microsoft.documentDB/databaseAccounts", name=name)
|
||||
})
|
||||
|
||||
AzureRMR::az_resource_group$set("public", "delete_cosmosdb_account", overwrite=TRUE,
|
||||
az_resource_group$set("public", "list_cosmosdb_accounts", overwrite=TRUE,
|
||||
function()
|
||||
{
|
||||
provider <- "Microsoft.documentDB"
|
||||
path <- "databaseAccounts"
|
||||
api_version <- az_subscription$
|
||||
new(self$token, self$subscription)$
|
||||
get_provider_api_version(provider, path)
|
||||
|
||||
op <- file.path("resourceGroups", self$name, "providers", provider, path)
|
||||
|
||||
cont <- call_azure_rm(self$token, self$subscription, op, api_version=api_version)
|
||||
lst <- lapply(cont$value,
|
||||
function(parms) AzureCosmosR::az_cosmosdb$new(self$token, self$subscription, deployed_properties=parms))
|
||||
|
||||
# keep going until paging is complete
|
||||
while(!is_empty(cont$nextLink))
|
||||
{
|
||||
cont <- call_azure_url(self$token, cont$nextLink)
|
||||
lst <- lapply(cont$value,
|
||||
function(parms) AzureCosmosR::az_cosmosdb$new(self$token, self$subscription, deployed_properties=parms))
|
||||
}
|
||||
named_list(lst)
|
||||
})
|
||||
|
||||
az_resource_group$set("public", "delete_cosmosdb_account", overwrite=TRUE,
|
||||
function(name, confirm=TRUE, wait=FALSE)
|
||||
{
|
||||
self$get_cosmosdb_account(name)$delete(confirm=confirm, wait=wait)
|
||||
|
|
|
|||
|
|
@ -25,14 +25,14 @@
|
|||
#'
|
||||
#' Note that AzureCosmosR provides a client framework only for the SQL API. To use the table storage API, you will also need the AzureTableStor package, and to use the MongoDB API, you will need the mongolite package. Currently, the Cassandra and Gremlin APIs are not supported.
|
||||
#'
|
||||
#' As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By instaling a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, which AzureCosmosR currently only partially supports. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
#' As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By installing a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, unlike the REST API that AzureCosmosR uses. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
#'
|
||||
#' @seealso
|
||||
#' [get_cosmosdb_account], [create_cosmosdb_account], [delete_cosmosdb_account]
|
||||
#'
|
||||
#' [cosmos_endpoint], [cosmos_database], [cosmos_container], [query_documents], [cosmos_mongo_endpoint], [AzureTableStor::table_endpoint], [mongolite::mongo]
|
||||
#' @export
|
||||
az_cosmosdb <- R6::R6Class("az_cosmosdb", inherit=AzureRMR::az_resource,
|
||||
az_cosmosdb <- R6::R6Class("az_cosmosdb", inherit=az_resource,
|
||||
|
||||
public=list(
|
||||
|
||||
|
|
|
|||
|
|
@ -141,7 +141,7 @@ list_cosmos_containers <- function(object, ...)
|
|||
list_cosmos_containers.cosmos_database <- function(object, ...)
|
||||
{
|
||||
res <- do_cosmos_op(object, "colls", "colls", "", ...)
|
||||
AzureRMR::named_list(lapply(process_cosmos_response(res)$DocumentCollections, function(obj)
|
||||
named_list(lapply(process_cosmos_response(res)$DocumentCollections, function(obj)
|
||||
{
|
||||
obj$database <- object
|
||||
structure(obj, class="cosmos_container")
|
||||
|
|
|
|||
|
|
@ -109,7 +109,7 @@ list_cosmos_databases <- function(object, ...)
|
|||
list_cosmos_databases.cosmos_endpoint <- function(object, ...)
|
||||
{
|
||||
res <- do_cosmos_op(object, "dbs", "dbs", "", ...)
|
||||
AzureRMR::named_list(lapply(process_cosmos_response(res)$Databases, function(obj)
|
||||
named_list(lapply(process_cosmos_response(res)$Databases, function(obj)
|
||||
{
|
||||
obj$endpoint <- object
|
||||
structure(obj, class="cosmos_database")
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@
|
|||
#'
|
||||
#' In most cases, you should not have to use `call_cosmos_endpoint` directly. Instead, use `do_cosmos_op` which provides a slightly higher-level interface to the API, by providing sensible defaults for the `resource_type` and`resource_link` arguments and partially filling in the request path.
|
||||
#'
|
||||
#' As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By instaling a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, which AzureCosmosR currently only partially supports. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
#' As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By installing a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, unlike the REST API that AzureCosmosR uses. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
#'
|
||||
#' Note that AzureCosmosR is a framework for communicating directly with the _core_ Cosmos DB client API, also known as the "SQL" API. Cosmos DB provides other APIs as options when creating an account, such as Cassandra, MongoDB, table storage and Gremlin. These APIs are not supported by AzureCosmosR, but you can use other R packages for working with them. For example, you can use AzureTableStor to work with the table storage API, or mongolite to work with the MongoDB API.
|
||||
#' @return
|
||||
|
|
@ -83,7 +83,7 @@ call_cosmos_endpoint <- function(endpoint, path, resource_type, resource_link,
|
|||
headers$`x-ms-version` <- endpoint$api_version
|
||||
url <- endpoint$host
|
||||
url$path <- gsub("/{2,}", "/", utils::URLencode(enc2utf8(path)))
|
||||
if(!AzureRMR::is_empty(options))
|
||||
if(!is_empty(options))
|
||||
url$query <- options
|
||||
|
||||
# repeat until no more continuations
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@
|
|||
#'
|
||||
#' The `by_physical_partition` argument allows running the query separately across all _physical_ partitions. Each physical partition corresponds to a partition key range, and contains the documents for one or more key values. You can set this to TRUE to run a query that fails when run across partitions; the returned object will be a list containing the individual query results from each physical partition.
|
||||
#'
|
||||
#' As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By instaling a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, which AzureCosmosR currently only partially supports. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
#' As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By installing a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, unlike the REST API. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
#' @seealso
|
||||
#' [cosmos_container], [cosmos_document], [list_partition_key_values], [list_partition_key_ranges]
|
||||
#' @examples
|
||||
|
|
@ -121,7 +121,7 @@ get_docs <- function(response, as_data_frame, metadata, container)
|
|||
docs$Documents
|
||||
else do.call(vctrs::vec_rbind, lapply(docs, `[[`, "Documents"))
|
||||
|
||||
if(AzureRMR::is_empty(docs))
|
||||
if(is_empty(docs))
|
||||
return(data.frame())
|
||||
|
||||
if(!metadata && is.data.frame(docs)) # a query can return scalars rather than documents
|
||||
|
|
|
|||
|
|
@ -131,7 +131,7 @@ delete_stored_procedure.cosmos_container <- function(object, procname, confirm=T
|
|||
return(invisible(NULL))
|
||||
|
||||
path <- file.path("sprocs", procname)
|
||||
res <- do_cosmos_op(object, path, "attachments", path, http_verb="DELETE", ...)
|
||||
res <- do_cosmos_op(object, path, "sprocs", path, http_verb="DELETE", ...)
|
||||
invisible(process_cosmos_response(res))
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,120 @@
|
|||
# AzureCosmosR
|
||||
|
||||
An interface to [Azure Cosmos DB](https://azure.microsoft.com/en-us/services/cosmos-db/), a NoSQL database service from Microsoft.
|
||||
|
||||
> Azure Cosmos DB is a fully managed NoSQL database for modern app development. Single-digit millisecond response times, and automatic and instant scalability, guarantee speed at any scale. Business continuity is assured with SLA-backed availability and enterprise-grade security. App development is faster and more productive thanks to turnkey multi region data distribution anywhere in the world, open source APIs and SDKs for popular languages. As a fully managed service, Azure Cosmos DB takes database administration off your hands with automatic management, updates and patching. It also handles capacity management with cost-effective serverless and automatic scaling options that respond to application needs to match capacity with demand.
|
||||
|
||||
On the Resource Manager side, AzureCosmosR extends the [AzureRMR](https://cran.r-project.org/package=AzureRMR) class framework to allow creating and managing Cosmos DB accounts. On the client side, it provides a comprehensive interface to the Cosmos DB SQL/core API as well as bridges to the MongoDB and table storage APIs.
|
||||
|
||||
## SQL interface
|
||||
|
||||
AzureCosmosR provides a suite of methods to work with databases, containers (tables) and documents (rows) using the SQL API.
|
||||
|
||||
```r
|
||||
library(dplyr)
|
||||
library(AzureCosmosR)
|
||||
|
||||
endp <- cosmos_endpoint("https://myaccount.documents.azure.com:443/", key="mykey")
|
||||
|
||||
list_cosmos_databases(endp)
|
||||
|
||||
get_cosmos_database(endp, "mydatabase")
|
||||
|
||||
# create a new container and upload the Star Wars dataset from dplyr
|
||||
cont <- create_cosmos_container(db, "mycontainer", partition_key="sex")
|
||||
bulk_import(cont, starwars)
|
||||
|
||||
query_documents(cont, "select * from mycontainer c")
|
||||
|
||||
# an array select: all characters who appear in ANH
|
||||
query_documents(cont1,
|
||||
"select c.name
|
||||
from mycontainer c
|
||||
where array_contains(c.films, 'A New Hope')")
|
||||
```
|
||||
|
||||
You can easily create and execute stored procedures:
|
||||
|
||||
```r
|
||||
proc <- create_stored_procedure(
|
||||
cont1,
|
||||
"helloworld",
|
||||
'function () {
|
||||
var context = getContext();
|
||||
var response = context.getResponse();
|
||||
response.setBody("Hello, World");
|
||||
}'
|
||||
)
|
||||
|
||||
exec_stored_procedure(proc)
|
||||
```
|
||||
|
||||
Aggregates take some extra work, as the Cosmos DB REST API only has limited support for cross-partition queries. Set `by_physical_partition=TRUE` in the `query_documents` call, which will run the query on each physical partition and return a list of data frames. You can then process the list to obtain an overall result.
|
||||
|
||||
```r
|
||||
# average height by sex, by physical partition
|
||||
df_lst <- query_documents(cont1,
|
||||
"select c.gender, count(1) n, avg(c.height) height
|
||||
from mycontainer c
|
||||
group by c.gender",
|
||||
by_physical_partition=TRUE
|
||||
)
|
||||
|
||||
# combine physical partition results
|
||||
df_lst %>%
|
||||
bind_rows(.id="pkrange") %>%
|
||||
group_by(gender) %>%
|
||||
summarise(height=weighted.mean(height, n))
|
||||
```
|
||||
|
||||
## Other interfaces
|
||||
|
||||
### MongoDB
|
||||
|
||||
You can query data in a MongoDB-enabled Cosmos DB instance using the mongolite package. AzureCosmosR provides a simple bridge to facilitate this.
|
||||
|
||||
```r
|
||||
endp <- cosmos_mongo_endpoint("https://myaccount.mongo.cosmos.azure.com:443/", key="mykey")
|
||||
|
||||
# a mongolite::mongo object
|
||||
conn <- cosmos_mongo_connection(mendp, "mycollection", "mydatabase")
|
||||
conn$find("{}")
|
||||
```
|
||||
|
||||
For more information on working with MongoDB, see the [mongolite](https://jeroen.github.io/mongolite/) documentation.
|
||||
|
||||
### Table storage
|
||||
|
||||
You can work with data in a table storage-enabled Cosmos DB instance using the AzureTableStor package.
|
||||
|
||||
```r
|
||||
endp <- AzureTableStor::table_endpoint("https://myaccount.table.cosmos.azure.com:443/", key="mykey")
|
||||
|
||||
tab <- AzureTableStor::get_storage_tables(endp, "mytable")
|
||||
AzureTableStor::list_table_entities(tab, filter="firstname eq 'Satya'")
|
||||
```
|
||||
|
||||
## Azure Resource Manager interface
|
||||
|
||||
AzureCosmosR extends the AzureRMR class framework with a new `az_cosmosdb` class representing a Cosmos DB account resource, and methods for the `az_resource_group` resource group class.
|
||||
|
||||
```r
|
||||
rg <- AzureRMR::get_azure_login()$
|
||||
get_subscription("sub_id")$
|
||||
get_resource_group("rgname")
|
||||
|
||||
rg$create_cosmosdb_account("mycosmosdb", interface="sql", free_tier=TRUE)
|
||||
rg$list_cosmos_accounts()
|
||||
cosmos <- rg$get_cosmos_account("mycosmosdb")
|
||||
|
||||
# access keys (passwords) for this account
|
||||
cosmos$list_keys()
|
||||
|
||||
# get an endpoint object -- detects which API this account uses
|
||||
endp <- cosmos$get_endpoint()
|
||||
|
||||
# API-specific endpoints
|
||||
cosmos$get_sql_endpoint()
|
||||
cosmos$get_mongo_endpoint()
|
||||
cosmos$get_table_endpoint()
|
||||
```
|
||||
|
|
@ -37,7 +37,7 @@ Azure Cosmos DB provides multiple APIs for accessing the data stored within the
|
|||
|
||||
Note that AzureCosmosR provides a client framework only for the SQL API. To use the table storage API, you will also need the AzureTableStor package, and to use the MongoDB API, you will need the mongolite package. Currently, the Cassandra and Gremlin APIs are not supported.
|
||||
|
||||
As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By instaling a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, which AzureCosmosR currently only partially supports. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By installing a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, unlike the REST API that AzureCosmosR uses. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
}
|
||||
|
||||
\seealso{
|
||||
|
|
|
|||
|
|
@ -106,7 +106,7 @@ These functions are the basis of the SQL API client framework provided by AzureC
|
|||
|
||||
In most cases, you should not have to use \code{call_cosmos_endpoint} directly. Instead, use \code{do_cosmos_op} which provides a slightly higher-level interface to the API, by providing sensible defaults for the \code{resource_type} and\code{resource_link} arguments and partially filling in the request path.
|
||||
|
||||
As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By instaling a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, which AzureCosmosR currently only partially supports. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By installing a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, unlike the REST API that AzureCosmosR uses. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
|
||||
Note that AzureCosmosR is a framework for communicating directly with the \emph{core} Cosmos DB client API, also known as the "SQL" API. Cosmos DB provides other APIs as options when creating an account, such as Cassandra, MongoDB, table storage and Gremlin. These APIs are not supported by AzureCosmosR, but you can use other R packages for working with them. For example, you can use AzureTableStor to work with the table storage API, or mongolite to work with the MongoDB API.
|
||||
}
|
||||
|
|
|
|||
|
|
@ -2,12 +2,14 @@
|
|||
% Please edit documentation in R/add_methods.R
|
||||
\name{get_cosmosdb_account}
|
||||
\alias{get_cosmosdb_account}
|
||||
\alias{list_cosmosdb_accounts}
|
||||
\title{Get Azure Cosmos DB account}
|
||||
\description{
|
||||
Method for the \link[AzureRMR:az_resource_group]{AzureRMR::az_resource_group} class.
|
||||
}
|
||||
\section{Usage}{
|
||||
\preformatted{get_cosmosdb_account(name)
|
||||
list_cosmosdb_accounts()
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -20,12 +22,12 @@ Method for the \link[AzureRMR:az_resource_group]{AzureRMR::az_resource_group} cl
|
|||
|
||||
\section{Details}{
|
||||
|
||||
This method retrieves the details for an existing Azure Cosmos DB account.
|
||||
\code{get_cosmosdb_account} retrieves the details for an existing Azure Cosmos DB account. \code{list_cosmosdb_accounts} retrieves all the Cosmos DB accounts within the resource group.
|
||||
}
|
||||
|
||||
\section{Value}{
|
||||
|
||||
An object of class \code{az_cosmosdb} representing the Cosmos DB account.
|
||||
For \code{get_cosmosdb_account}, an object of class \code{az_cosmosdb} representing the Cosmos DB account. For \code{list_cosmosdb_accounts}, a list of such objects.
|
||||
}
|
||||
|
||||
\seealso{
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ The default \code{cross_partition=TRUE} runs the query for all partition key val
|
|||
|
||||
The \code{by_physical_partition} argument allows running the query separately across all \emph{physical} partitions. Each physical partition corresponds to a partition key range, and contains the documents for one or more key values. You can set this to TRUE to run a query that fails when run across partitions; the returned object will be a list containing the individual query results from each physical partition.
|
||||
|
||||
As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By instaling a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, which AzureCosmosR currently only partially supports. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By installing a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to any SQL database. An advantage of the ODBC interface is that it fully supports cross-partition queries, unlike the REST API. A disadvantage is that it does not support nested document fields; such fields will be flattened into a string.
|
||||
}
|
||||
\examples{
|
||||
\dontrun{
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче