CatMapR Safe Upload Patterns

Why this vignette

CatMapR upload flows are usually asynchronous and can mutate production metadata. This vignette focuses on safe defaults and repeatable patterns.

Key requirements

• Upload calls use standard key expressions.
• Provide fully formed Key values such as Type == Adamana Brown.

Full action to Edit GUI mapping

This crosswalk maps CatMapR action values to the exact labels shown in the CatMapper Edit page (Advanced upload options).

CatMapR action value	Edit page GUI value	Typical purpose
add_node	Adding new node for every row	Create new category or dataset nodes from upload rows.
node_add	Updating existing Node properties--add or add to properties	Add one or more properties to existing nodes without replacing current values.
node_replace	Updating existing Node properties--replace one property	Replace one property value on existing nodes.
add_uses	Adding new uses ties (with old or new nodes)	Create dataset-to-category USES ties.
update_add	Updating existing USES only--add or add to properties	Add one or more properties to existing USES ties.
update_replace	Updating existing USES only--replace one property	Replace an existing property value on USES ties.
add_merging	Adding new merging ties for every row	Create new merging ties from upload rows.
merging_add	Updating existing Merging tie properties--add or add to properties	Add one or more properties to existing merging ties.
merging_replace	Updating existing Merging tie properties--replace one property	Replace one property value on existing merging ties.

Notes:

• Required columns vary by action and are validated before upload.

Key helper patterns

build_key("Type", "Adamana Brown")
build_key_from_columns(
  data.frame(Type = "Adamana Brown", Region = "Flagstaff", stringsAsFactors = FALSE),
  c("Type", "Region")
)
normalize_key("Key == Region == Flagstaff")
is_normalized_key("Region == Flagstaff")

Add USES ties safely

payload <- data.frame(
  CMName = "Yoruba",
  Name = "Yoruba",
  CMID = "",
  Key = "Type == Adamana Brown",
  datasetID = "SD1",
  label = "ETHNICITY",
  stringsAsFactors = FALSE
)

result <- upload_rows(
  df = payload,
  database = "SocioMap",
  form_data = list(
    domain = "ETHNICITY",
    subdomain = "ETHNICITY",
    datasetID = "SD1",
    cmNameColumn = "CMName",
    categoryNamesColumn = "Name",
    cmidColumn = "CMID",
    keyColumn = "Key"
  ),
  action = "add_uses",
  api_key = Sys.getenv("CATMAPR_API_KEY")
)

head(result)

Update existing USES properties

update_add_payload <- data.frame(
  CMID = "SM123",
  Key = "Type == Adamana Brown",
  datasetID = "SD1",
  variable = "CeramicType",
  stringsAsFactors = FALSE
)

upload_rows(
  df = update_add_payload,
  database = "SocioMap",
  form_data = list(
    domain = "ETHNICITY",
    subdomain = "ETHNICITY",
    datasetID = "SD1",
    cmNameColumn = "CMName",
    categoryNamesColumn = "Name",
    cmidColumn = "CMID",
    keyColumn = "Key"
  ),
  action = "update_add",
  properties = c("variable"),
  api_key = Sys.getenv("CATMAPR_API_KEY")
)

Replace USES key values

update_replace_payload <- data.frame(
  CMID = "SM123",
  Key = "Type == Adamana Brown",
  NewKey = "Type == Tusayan Gray",
  datasetID = "SD1",
  stringsAsFactors = FALSE
)

upload_rows(
  df = update_replace_payload,
  database = "SocioMap",
  form_data = list(
    domain = "ETHNICITY",
    subdomain = "ETHNICITY",
    datasetID = "SD1",
    cmNameColumn = "CMName",
    categoryNamesColumn = "Name",
    cmidColumn = "CMID",
    keyColumn = "Key"
  ),
  action = "update_replace",
  properties = c("NewKey"),
  api_key = Sys.getenv("CATMAPR_API_KEY")
)