EVOLUTION-MANAGER
Edit File: rows.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Manipulate individual rows</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for rows {dplyr}"><tr><td>rows {dplyr}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Manipulate individual rows</h2> <h3>Description</h3> <a href='https://www.tidyverse.org/lifecycle/#experimental'><img src='figures/lifecycle-experimental.svg' alt='Experimental lifecycle'></a> <p>These functions provide a framework for modifying rows in a table using a second table of data. The two tables are matched <code>by</code> a set of key variables whose values must uniquely identify each row. The functions are inspired by SQL's <code>INSERT</code>, <code>UPDATE</code>, and <code>DELETE</code>, and can optionally modify <code>in_place</code> for selected backends. </p> <ul> <li> <p><code>rows_insert()</code> adds new rows (like <code>INSERT</code>); key values in <code>y</code> must not occur in <code>x</code>. </p> </li> <li> <p><code>rows_update()</code> modifies existing rows (like <code>UPDATE</code>); key values in <code>y</code> must occur in <code>x</code>. </p> </li> <li> <p><code>rows_patch()</code> works like <code>rows_update()</code> but only overwrites <code>NA</code> values. </p> </li> <li> <p><code>rows_upsert()</code> inserts or updates depending on whether or not the key value in <code>y</code> already exists in <code>x</code>. </p> </li> <li> <p><code>rows_delete()</code> deletes rows (like <code>DELETE</code>); key values in <code>y</code> must exist in <code>x</code>. </p> </li></ul> <h3>Usage</h3> <pre> rows_insert(x, y, by = NULL, ..., copy = FALSE, in_place = FALSE) rows_update(x, y, by = NULL, ..., copy = FALSE, in_place = FALSE) rows_patch(x, y, by = NULL, ..., copy = FALSE, in_place = FALSE) rows_upsert(x, y, by = NULL, ..., copy = FALSE, in_place = FALSE) rows_delete(x, y, by = NULL, ..., copy = FALSE, in_place = FALSE) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>x, y</code></td> <td> <p>A pair of data frames or data frame extensions (e.g. a tibble). <code>y</code> must have the same columns of <code>x</code> or a subset.</p> </td></tr> <tr valign="top"><td><code>by</code></td> <td> <p>An unnamed character vector giving the key columns. The key values must uniquely identify each row (i.e. each combination of key values occurs at most once), and the key columns must exist in both <code>x</code> and <code>y</code>. </p> <p>By default, we use the first column in <code>y</code>, since the first column is a reasonable place to put an identifier variable.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>Other parameters passed onto methods.</p> </td></tr> <tr valign="top"><td><code>copy</code></td> <td> <p>If <code>x</code> and <code>y</code> are not from the same data source, and <code>copy</code> is <code>TRUE</code>, then <code>y</code> will be copied into the same src as <code>x</code>. This allows you to join tables across srcs, but it is a potentially expensive operation so you must opt into it.</p> </td></tr> <tr valign="top"><td><code>in_place</code></td> <td> <p>Should <code>x</code> be modified in place? This argument is only relevant for mutable backends (e.g. databases, data.tables). </p> <p>When <code>TRUE</code>, a modified version of <code>x</code> is returned invisibly; when <code>FALSE</code>, a new object representing the resulting changes is returned.</p> </td></tr> </table> <h3>Value</h3> <p>An object of the same type as <code>x</code>. The order of the rows and columns of <code>x</code> is preserved as much as possible. The output has the following properties: </p> <ul> <li> <p><code>rows_update()</code> preserves rows as is; <code>rows_insert()</code> and <code>rows_upsert()</code> return all existing rows and potentially new rows; <code>rows_delete()</code> returns a subset of the rows. </p> </li> <li><p> Columns are not added, removed, or relocated, though the data may be updated. </p> </li> <li><p> Groups are taken from <code>x</code>. </p> </li> <li><p> Data frame attributes are taken from <code>x</code>. </p> </li></ul> <p>If <code>in_place = TRUE</code>, the result will be returned invisibly. </p> <h3>Examples</h3> <pre> data <- tibble(a = 1:3, b = letters[c(1:2, NA)], c = 0.5 + 0:2) data # Insert rows_insert(data, tibble(a = 4, b = "z")) try(rows_insert(data, tibble(a = 3, b = "z"))) # Update rows_update(data, tibble(a = 2:3, b = "z")) rows_update(data, tibble(b = "z", a = 2:3), by = "a") # Variants: patch and upsert rows_patch(data, tibble(a = 2:3, b = "z")) rows_upsert(data, tibble(a = 2:4, b = "z")) # Delete and truncate rows_delete(data, tibble(a = 2:3)) rows_delete(data, tibble(a = 2:3, b = "b")) try(rows_delete(data, tibble(a = 2:3, b = "b"), by = c("a", "b"))) </pre> <hr /><div style="text-align: center;">[Package <em>dplyr</em> version 1.0.2 <a href="00Index.html">Index</a>]</div> </body></html>