sm_data: Retrieve Data from the Database

In samadb: South Africa Macroeconomic Database API

Retrieve Data from the Database

Description

This is the main function of the package to retrieve data from the database.

Usage

sm_data(
  dsid = NULL,
  series = NULL,
  from = NULL,
  to = NULL,
  freq = NULL,
  labels = TRUE,
  wide = TRUE,
  expand.date = FALSE,
  ordered = TRUE,
  return.query = FALSE,
  ...
)

Arguments

dsid	character. (Optional) id's of datasets matching the 'dsid' column of the 'DATASET' table (retrieved using sm_datasets()). If used, all series from the dataset are returned, in addition to any other series selected with series.
series	character. (Optional) codes of series matching the 'series' column of the 'SERIES' table (retrieved using sm_series()). If 'dsid' is also specificed, the two are combined using SQL 'OR' i.e. these series are retrieved in addition to all series matched through 'dsid'.
from	set the start time of the data retrieved by either supplying a start date, a date-string of the form "YYYY-MM-DD" or "YYYY-MM", year-quarters of the form "YYYYQN" or "YYYY-QN", or a numeric year YYYY (numeric or character). These expressions are converted to a regular date by sm_as_date.
to	same as from: to set the time period until which data is retrieved. For expressions that are not full "YYYY-MM-DD" dates, the last day of the period is chosen.
freq	character. Return only series at a certain frequency. Allowed are values "D" (Daily), "W" (Weekly), "M" (Monthly), "Q" (Quarterly), "A" (Annual), "AF" (Fiscal Years), matching the 'freq' column in the 'SERIES' table (retrieved using sm_series()).
labels	logical. TRUE will also return labels (series descriptions) along with the series codes.
wide	logical. TRUE calls sm_pivot_wider on the result. FALSE returns the data in a long format without missing values (suitable for ggplot2).
expand.date	logical. TRUE will call sm_expand_date on the result.
ordered	logical. TRUE orders the result by 'date' and, if !is.null(dsid), labels = TRUE or !is.null(freq), by series, maintaining a fixed order of series. FALSE does not explicitly order the result, to the benefit of faster query execution.
return.query	logical. TRUE will not query the database but instead return the constructed SQL query as a character string (for debugging purposes).
...	further arguments passed to sm_pivot_wider (if wide = TRUE) or sm_expand_date (if expand.date = TRUE), no conflicts between these two.

Details

Series from datasets at different frequencies can be queried, but, if wide = TRUE, this will result in missing values in the lower frequency series.

Value

A data.table with the result of the query.

See Also

sm_pivot_wider, sm_expand_date, samadb

Examples

# Return all electricity indicators from 2000
sm_data("ELECTRICITY", from = 2000)

samadb documentation built on Aug. 21, 2025, 5:54 p.m.