Skip to contents

Create only the records that are not there yet

telem_create_missing.Rd

Reads what the API already holds, matches it against data on the columns you nominate, creates the rows that are absent, and returns every input row with its id — whether that id was just assigned or already existed.

Usage

telem_create_missing(data, resource, by, ..., dry_run = FALSE, verbosity = 0)

Arguments

data

A tibble of records to ensure exist, in the shape the matching telem_create_*() function takes.

resource

Character. One of telem_fields()'s resources.

by

Character vector of columns forming the natural key. Must be present in data and returned by the matching read function.

...

Passed to the create function, e.g. on_incomplete for deployments.

dry_run

Logical. If TRUE, reports what it would create without sending anything.

verbosity

Integer. How much to print (0 = silent, 1 = headers, 2 = headers + body, 3 = full).

Value

data with an id column. Row order is preserved.

Details

This is what makes a load script re-runnable. A load that half-succeeds — the API rejects row 200 of 265, or the session drops — leaves the first 199 written, and the fix should be to run the script again rather than to work out by hand which rows landed.

It never updates a record that already exists. A natural-key match means "this is already here, leave it alone", so re-running cannot overwrite a correction someone made in the UI between runs. Use telem_update_*() deliberately when a change is what you want.

Choosing by

The key has to be something the source data and the API agree on:

  • devices — serial_number, which the database holds a unique index on alongside blueprint_id.

  • blueprints — model, version and manufacturer together, matching the unique index.

  • individuals — usually nickname, though nothing enforces its uniqueness server-side, so this is a convention between you and the source data rather than a guarantee.

Values are compared as trimmed text, so 157658 matches "157658" — the API returns a serial as a number where a CSV gives a string, and they are the same collar.

A row whose key is missing is refused outright. It could be created, but not found again afterwards, so a second run would create it a second time — which would break the one promise this function makes.

Examples

if (FALSE) { # \dontrun{
# Re-runnable: creates 265 devices the first time, none the second.
devices <- telem_create_missing(
  collars, "devices", by = "serial_number"
)
devices$id   # populated for every row either way
} # }