Skip to contents

Insert data

Source: R/shared_class_functions.r
insert.Rd

Generic function for inserting a data frame of data into an object.

Usage

insert(x, vals, relations = names(x), all = FALSE, ...)

Arguments

x

a relational data object, into which to insert data, such as a relation or database object.

vals

a data frame, containing data to insert.

relations

a character vector, containing names of elements of x into which to insert data. By default, insert attempts to insert data into every element.

all

a logical, indicating whether vals is required to contain all attributes of all elements of x[relations]. By default, it is not, and data is only inserted into elements of x[relations] whose attributes are all present in vals.

...

further arguments pass on to methods.

Value

An R object of the same class as x, containing the additional new data.

Details

This function is intended for inserting into an object that is itself comprised of data frames, such as a relation or a database. The given methods have the following behaviour:

  • If an empty set of data is inserted, into a non-empty object element, nothing happens.

  • If an empty set of data is inserted into an empty object element, the resulting element is also empty, but takes on the attribute/column classes of the inserted data. This is done to prevent having to know attribute classes during object creation.

  • Insertion can fail if inserting would violate object constraints. For example, databases cannot have data inserted that would violate candidate/foreign key constraints.

  • For other cases, the data is inserted in an object element in the same way as using rbind, followed by unique.

While key violations prevent insertion, re-insertion of existing records in an object element does not. This makes insertion equivalent to an INSERT OR IGNORE expression in SQL. In particular, it is somewhat like using this expression in SQLite, since that implementation uses dynamic typing.

If vals contains attributes not included in attrs_order(x), insert throws an error, since those attributes can't be inserted.

If a partial set of attributes is inserted, and all is FALSE, then data is only inserted into components of x[relations] whose required attributes are all present in vals. If all is TRUE, insert returns an error instead. This is useful when specifying relations: in that case, you often intend to insert into all of the specified elements, so not including all the required attributes is a mistake, and all = TRUE prevents it.

If all is TRUE, insert throws an error in this case: This ensures you insert into all members of a specified value of relations.