sofa.Rmd.og

---
title: "sofa introduction"
author: "Scott Chamberlain"
date: "`r Sys.Date()`"
output:
  html_document:
    toc: true
    toc_float: true
    theme: readable
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{sofa introduction}
  %\VignetteEncoding{UTF-8}
---

```{r echo=FALSE}
knitr::opts_chunk$set(
	comment = "#>",
	collapse = TRUE,
	warning = FALSE,
	message = FALSE
)
```

Make sure your CouchDB installation is running.

## Install sofa

Stable version

```{r eval=FALSE}
install.packages("sofa")
```

Development version

```{r eval=FALSE}
remotes::install_github("ropensci/sofa")
```

Load library

```{r}
library(sofa)
```

## sofa package API

The following is a breakdown of the major groups of functions - note that not all are included.

__create a CouchDB client connection__

* `Cushion`

__work with databases__

* `db_alldocs`
* `db_changes`
* `db_compact`
* `db_create`
* `db_delete`
* `db_explain`
* `db_info`
* `db_list`
* `db_query`
* `db_replicate`
* `db_revisions`
* `db_index`
* `db_index_create`
* `db_index_delete`

__work with views/design documents__

* `design_create`
* `design_create_`
* `design_delete`
* `design_get`
* `design_head`
* `design_info`
* `design_search`
* `design_search_many`

__work with documents__

* `doc_create`
* `doc_delete`
* `doc_get`
* `doc_head`
* `doc_update`
* `db_bulk_create`
* `db_bulk_update`
* `doc_attach_create`
* `doc_attach_delete`
* `doc_attach_get`
* `doc_attach_info`

## Create a connection client

If your CouchDB instance requires username and password make sure to pass those to `Cushion$new`

```{r}
(x <- Cushion$new(user="admin", pwd="password"))
```

## Ping your server

```{r}
x$ping()
```

## Create a new database

```{r echo=FALSE}
if ("cats" %in% db_list(x)) {
  invisible(db_delete(x, dbname = "cats"))
}
```

```{r}
db_create(x, 'cats')
```

## List databases

```{r}
db_list(x)
```

## Create a document

```{r}
doc1 <- '{"name": "leo", "color": "blue", "furry": true, "size": 1}'
doc_create(x, dbname = "cats", doc1, docid = "bluecat")
```

and another!

```{r}
doc2 <- '{"name": "samson", "color": "red", "furry": false, "size": 3}'
doc_create(x, dbname = "cats", doc2)
```

and one more, cause 3's company

```{r}
doc3 <- '{"name": "matilda", "color": "green", "furry": false, "size": 5, "age": 2}'
doc_create(x, dbname = "cats", doc3)
```

Note how we used a document id in the first document creation, but
not in the second and third. Using a document id is optional.

Also note that the third document has an additional field "age".

## Changes feed

```{r}
db_changes(x, "cats")
```

## Search

The simplest search just returns the documents.

```{r}
db_query(x, dbname = "cats", selector = list(`_id` = list(`$gt` = NULL)))$docs
```

Search for cats that are red

```{r}
db_query(x, dbname = "cats", selector = list(color = "red"))$docs
```

Search for cats that are furry

```{r}
db_query(x, dbname = "cats", selector = list(furry = TRUE))$docs
```

Return only certain fields

```{r}
db_query(x, dbname = "cats",
         selector = list(size = list(`$gt` = 2)),
         fields = c("name", "color"))$docs
```

Convert the result of a query into a data.frame using `jsonlite`

```{r}
library('jsonlite')
res <- db_query(x, dbname = "cats",
                 selector = list(`_id` = list(`$gt` = NULL)),
                 fields = c("name", "color", "furry", "size", "age"),
                 as = "json")

fromJSON(res)$docs
```