spec {unnest}

Unnest spec

Description

Unnest spec is a nested list with the same structure as the nested json. It specifies how the deeply nested lists ought to be unnested. spec() is a handy constructor for spec lists. s() is a shorthand alias for spec().

Usage

spec(
  selector = NULL,
  ...,
  as = NULL,
  children = NULL,
  groups = NULL,
  include = NULL,
  exclude = NULL,
  stack = NULL,
  process = NULL,
  default = NULL
)

s(
  selector = NULL,
  ...,
  as = NULL,
  children = NULL,
  groups = NULL,
  include = NULL,
  exclude = NULL,
  stack = NULL,
  process = NULL,
  default = NULL
)

Arguments

selector

A shorthand syntax for an include parameter. Can be a list or a character vector.

1. When selector is a list or a character vector with length greater than 1, each element is an include parameter at the corresponding level. For example s(c("a", "b"), ...) is equivalent to s(include = "a", s(include = "b", ...))

2. When selector is a character of length 1 and contains "/" characters it is split with "/" first. For instance s(c("a", "b"), ...), s("a/b", ...) and s("a", s("b", ...)) are all equivalent to the canonical s(include = "a", s(include = "b", ...)). Components consisting entirely of digits are converted to integers. For example ⁠s("a/2/b" ...)⁠ is equivalent to s("a", s(2, s("b", ...)))

3. Multiple include fields can be separated with ⁠,⁠. For example s("a/b,c/d") is equivalent to s("a", s(include = c("b", "c"), s("d", ...)))

as

name for this field in the extracted data.frame

children, ...

Unnamed list of children spec. ... is merged into children. children is part of the canonical spec.

groups

Named list of specs to be processed in parallel. The return value is a named list of unnested data.frames. The results is the same as when each spec is unnested separately except that dedupe parameter of unnest() will work across groups and execution is faster because the nested list is traversed once regardless of the number of groups.

include, exclude

A list, a numeric vector or a character vector specifying components to include or exclude. A list can combine numeric indexes and character elements to extract.

stack

Whether to stack this node (TRUE) or to spread it (FALSE). When stack is a string an index column is created with that name.

process

Extra processing step for this element. Either NULL for no processing (the default), "as_is" to return the entire element in a list column, "paste" to paste elements together into a character column.

default

Default value to insert if the include specification hasn't matched.

Value

s(): a canonical spec - a list consumed by C++ unnesting routines.

Examples

s("a")
s("a//c2")
s("a/2/c2,cid")