haver.limits {Haver} | R Documentation

## Set or Query Limits for Haver Analytics Data Queries

### Description

`haver.limits` handles the settings with regards to the limits of data queries of `haver.data`. Note that these limits have no impact on the metadata queries of `haver.metadata`.

Limits on the size of queries are imposed to protect you from unintentionally conducting very large queries that are problematic in terms of execution time or memory consumption.

### Usage

    haver.limits()
    haver.limits(what)
    haver.limits(what, value)

### Arguments

`what` | a character string. One of ‘numcodes’, ‘numdatapoints’, and ‘default’, or any abbreviation thereof. `what="numcodes"` sets the maximum allowed number of codes in a query to `value`. `what="numdatapoints"` sets the maximum allowed number of data points in a query to `value`. `what="default"` ignores the value of `value`, if supplied, and restores default values for ‘numcodes’ and ‘numdatapoints’, which are 5000 and 15000000 (15 million), respectively.
`value` | a numeric non-negative scalar, specifying the limit for the ‘numcodes’ or ‘numdatapoints’ setting.

### Details

The values set by `haver.limits` are taken into account by `haver.data`. It will issue an error if a query is beyond what is allowed by query limits, unless you specify its option `limits=FALSE`.

`haver.limits()`, with an empty argument list, does nothing besides returning the current settings.

`haver.limits("default")` restores Haver default values.

Any values set by `haver.limits` will remain in effect until the package gets detached from the R search path, or until R is restarted. Restarting R or re-loading the Haver package will result in the restoration of default values.

The default values for query limits allow you to conduct queries which are fairly sizeable. The default for the maximum number of codes is 5000. The default for the maximum number of data points is 15 million, which is a little bit more than a daily data set with 1000 time series, covering 50 years of data. Such a data set requires more than 100 megabyte of memory, but the memory necessary for performing the retrieval is several times as high. Before you increase values for limits, make sure these are tenable for your system.

### Value

A list with named elements ‘numcodes’ and ‘numdatapoints’, containing numeric scalars, indicating the current settings of query limits.

### Query Speed and Memory consumption

Large data queries can become problematic with respect to execution time and memory consumption. Whether this is the case depends on the limits of your machine, and it may also depend the speed of your institution's network. The following paragraphs provide recommendations for managing speed and memory issues, in general terms.

#### Query Execution Time

Should a query take too long, you can interrupt execution as with other R commands. Still, after an interrupted query the memory claimed by R is likely to be larger than before the query. The `gc` command can help to free some or all of the memory up again.

#### Memory Consumption

When specifying large queries, assessing a tenable level of memory consumption by `haver.data` should not be geared towards the total free memory on your computer, for the following reason:

- The memory consumed by data query operations is likely to be a multiple of the memory consumed by the `HaverData` object returned.

- Commands issued after the query may also consume a large amount of memory. For example, if you follow the recommendation in section ‘Coercion to Other Types’ in `HaverData` to create an object for data analysis in addition to the `HaverData` object, you are requesting the amount of memory consumed by the Haver data set for a second object. As another example, `haver.setalias` requires a copy operation of an entire `HaverData` object.

On 32-bit systems, memory limits may pose more stringent restrictions on your queries than on 64-bit systems. See `Memory-limits`.

Should a data query consume a lot of memory, there is a good change that you can reclaim some or all of it by using the `gc` command.

### See Also

See Haver_package for all help entries related to the Haver package.

### Examples

    haver.path()
    haver.path("examples")

    ## haver.limits() returns a list with the current settings for limits. We use
    ## it here to record these settings in order to be able to restore them later.
    ex_storedlimits <- haver.limits()

    ## We reset the limit on the maximum number of codes allowed in a query:
    haver.limits(what="numcodes", value=10)

    ## 'HAVERW' has 21 codes. The limit we just set does not affect
    ## metadata retrievals:
    hmd <- haver.metadata(dat="haverw")

    ## Querying the data for 21 codes is not possible with the example settings
    ## for limits. The following generates an error:
    ## Not run:
    hd <- haver.data(codes=hmd)

    ## End(Not run)

    ## A query for 10 codes still works:
    hd <- haver.data(codes=hmd[1:10])

    ## We can also explicitly state that 'haver.data' should ignore limits:
    hd <- haver.data(codes=hmd, limits=FALSE)

    ## With default values, the full 21 code query goes through of course:
    haver.limits(what="default")
    hd <- haver.data(codes=hmd)

    ## We restore the limits that were in place before the above examples
    ## were executed:
    haver.limits(what="numcodes"      , value=ex_storedlimits[["numcodes"]])
    haver.limits(what="numdatapoints" , value=ex_storedlimits[["numdatapoints"]])

    haver.path("restore")

[Package Haver version 3.2 Index]