README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r knitr-options, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-",
  message = FALSE,
  warning = TRUE
)
```

# quasardb

:warning:**WARNING**: Early-stage development version. Use at your own risk.

:information_source:**NOTE**: Supported systems: FreeBSD, Linux, :apple:macOS, Windows.

The quasardb package is the official R API for [quasardb](https://www.quasardb.net) timeseries database.

## Installation

<!-- TODO:
You can install the released version from CRAN with:
```{r installation, eval = FALSE}
install.packages("quasardb")
```
-->

<!-- For development:
```{r dev-installation, eval = FALSE}
install.packages(c("devtools", "knitr", "lintr", "roxygen2"))
```
-->

On Unix-like systems, if you have quasardb C API installed system-wide,
you can install quasardb R API directly from [GitHub](https://github.com/bureau14/qdb-api-r)
as follows:
```{r gh-installation, eval = FALSE}
if (!requireNamespace("devtools", quietly = TRUE)) {
  install.packages("devtools")
}
if (!requireNamespace("nanotime", quietly = TRUE)) {
  install.packages("nanotime")
}
devtools::install_github("bureau14/qdb-api-r")
```

### quasardb C API

To build the R API, you will need the C API.
You can get the C API as well as other tools from [our download page](https://www.quasardb.net/-Get-).

It can either be installed on the machine system-wide
(e.g. on Unix in `/usr/lib` or `/usr/local/lib`)
or you can unpack the C API archive in `inst` subdirectory of this R API source.
On Windows, you need to verify additionally that the `qdb_api.dll` is in the
`PATH` environment variable.

### Building the extension from source

To perform a clean build:
```{r build-extension, eval = FALSE}
devtools::build(binary = TRUE)
```

To update documentation and auto-generated files:
```{r document-extension, eval = FALSE}
devtools::document()
```

Only update the documentation in man, but don't regenerate R files:
```{r roxygenize-extension, eval = FALSE}
roxygen2::roxygenize()
```

To check the extension:
```{r check-extension, eval = FALSE}
devtools::check()
```

You may wish to skip tests using:
```{r check-extension-without-tests, eval = FALSE}
devtools::check(args = "--no-tests")
```

To test the extension:
```{r test-extension, eval = FALSE}
devtools::test()
```

## Usage

:warning:**WARNING**: Most of these snippets require a running `qdbd` cluster running.
You can get it from [our download page](https://www.quasardb.net/-Get-).

Load library:
```{r load-quasardb-extension}
library(quasardb)
```

Get underlying C API version:

```{r example-version}
version()
```

Get underlying C API build id and date:
```{r example-build,}
build()
```

```{r example-run-qdbd, include = FALSE}
qdbd <- run_database(root = getwd())
```

Connect to a quasardb cluster at a default URI `qdb://127.0.0.1:2836`:
```{r example-connect-default}
handle <- connect()
```

Connect to a quasardb cluster at a user-provided URI:
```{r example-connect}
handle <- connect("qdb://127.0.0.1:2836")
```

```{r example-entry_remove-if-exists, include = FALSE}
# Remove the example entry, but ignore any error.
handle <- connect("qdb://127.0.0.1:2836")

skip_alias_not_found <- function (e) {
  if (!grepl(pattern = "b1000008", x = e, fixed = TRUE)) {
    stop("Unexpected error: ", e)
  }
}

tryCatch(
  entry_remove(handle, name = "timeseries1"),
  error = skip_alias_not_found,
  warning = skip_alias_not_found
)
tryCatch(
  entry_remove(handle, name = "timeseries2"),
  error = skip_alias_not_found,
  warning = skip_alias_not_found
)
```

Create a timeseries:
```{r example-ts_create}
ts_create(handle, name = "timeseries1",
     columns = c("column1" = column_type$blob, "column2" = column_type$double))
```

```{r example-ts_create2, include = FALSE}
ts_create(handle, name = "timeseries2",
     columns = c("column1" = column_type$blob, "column2" = column_type$double))
```

Show information about the columns of a timeseries:
```{r example-ts_show}
columns <- ts_show(handle, name = "timeseries1")
columns
sapply(columns, function(ct) {
  names(which(ct == column_type))
})
```

Add a tag to an entry:
```{r example-attach_tags-single}
attach_tags(handle, entry = "timeseries1", tags = "my_tag")
```

```{r example-attach_tags-single2, include = FALSE}
attach_tags(handle, entry = "timeseries2", tags = "my_tag")
```

Add many tags at once:
```{r example-attach_tags-many}
attach_tags(handle,
                entry = "timeseries1",
                tags = c("my_tag1", "my_tag2", "my_tag3"))
```

Get tags of an entry:
```{r example-get_tags}
tags <- get_tags(handle, name = "timeseries1")
tags
```

Get all entries marked with a tag:
```{r example-get_tagged}
entries <- get_tagged(handle, tag = "my_tag")
entries
```


Get all entry keys matching given find query:
```{r example-query_find}
# Get all entries (precisely: their keys) tagged with 'my-tag' being timeseries.
keys <- query_find(handle, "find(tag='my_tag' and type=ts)")
keys
```

Untag an entry:
```{r example-detach_tags}
detach_tags(handle, entry = "timeseries2", tag = "my_tag")
# Now, timeseries2 is no more on the list.
keys <- query_find(handle, "find(tag='my_tag' and type=ts)")
keys
```

Execute a select query:
```{r example-query}
# Get number of elements in each column of the timeseries in year 2017.
result <-
  query(handle, "select count(*) from timeseries1 in range(2017, +1y)")
result$scanned_point_count
result$tables[["timeseries1"]]$data
```

Remove an entry:
```{r example-entry_remove}
entry_remove(handle, name = "timeseries1")
```

## TODO

 - Add `ts_insert` (only stub is currently implemented), `has_tag`.
 - Make a quasardb driver compliant with [DBI package](https://www.rdocumentation.org/packages/DBI/).