Generic function for inserting a data frame of data into an object.
insert(x, vals, relations = names(x), all = FALSE, ...)An R object of the same class as x, containing the additional
new data.
a relational data object, into which to insert data, such as a
relation or database object.
a data frame, containing data to insert.
a character vector, containing names of elements of x
into which to insert data. By default, insert attempts to insert
data into every element.
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.
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.