Connection Snippets

RStudio connections can be extended through two methods:

Snippet files

A Connection snippet file is an R code snippet with additional metadata which is intended to initialize a connection. This file can be as simple as:

library(readr)
data <- read_csv(readr_example("mtcars.csv"))

This snippet can be saved on a server-based version of RStudio under /etc/rstudio/connections/. For desktop versions of RStudio, Connection Snippets are distributed through R packages as detailed in the R packages section below.

For the above example on a server, it would be saved as:

# Linux server only
/etc/rstudio/connections/Motor Trend Cars.R

Once that file is created and RStudio is restarted, RStudio will make this connection available as Motor Trend Cars underneath Connect to Existing Data Sources:

A screenshot of the New Connection wizard displaying the example "Motor Trends Cars" existing data source

A screenshot of the New Connection wizard, displaying the snippet output.

Snippet test

The snippet can also be tested by pressing the Test button in the New Connection wizard. Testing will return either a success or failure based on the available code snippet.

A screenshot of the New Connections wizard, displaying the result of a successful connection test.

Snippet customization

The path is configurable through the connections-path environment variable and multiple connection files can be specified.

In order to parameterize this connection, one can create fields using using the ${Position:Label=Default} syntax:

  • Position: The row position starting at zero.

  • Label: The label assigned to this field.

  • Default: An optional default value.

For example, a filter interface for this dataframe can be added with the following connection snippet:

library(readr)
data <- read_csv(readr_example("mtcars.csv"))
data[data$mpg == ${0:Miles per Gallon=21.4} | data$cyl == ${1:Cylinders=6}, ]

A screenshot of the New Connection wizard, displaying the ability to add filters or other UI components to the connection/data

In order to create a ; separated list of values, use the syntax ${Position:Label=Default:Key}. Semicolon-separated list are common in database connections and therefore, natively supported in snippet files, for instance:

"${2:Letters=ABC:LettersKey}${3:Numbers=123:NumbersKey}"

A screenshot of the New Connection wizard, displaying the ability to add filters or other UI components to the connection/data

There are several escape characters supported: $colon$ to escape : and $equal to escape =.

R packages

R packages provide the New Connection integration to both server and desktop based versions of RStudio.

Package structure

A package supporting connections defines the following components:

  • Connections File: A DCF file must be created under inst/rstudio/connections.dcf to enumerate each connection supported in the package.

  • Snippet Files: Snippet files are stored under inst/rstudio/connections/.

As a quick start, the RStudio Connections Example GitHub repo contains a working example of this structure.

Connections contract

You can integrate with RStudio’s Connections pane to allow users to explore connections created with your R package by using the Connections Contract.

Snippet files

Snippet Files are specified under the /inst/rstudio/connections and follow the same syntax mentioned in the “Snippet Files” section.

Shiny application

For advanced connection interfaces, a shiny application can be specified. See sparklyr for a working application.