Vignette refresh

[hfrick]

As discussed, I'm chipping away at a refresh of the vignettes. Overall, I'm aiming to have

• a vignette covering the core functionality of the various validation rules and how they can be combined into a validation plan/agent
• a vignette focused on schema validation aka "validating the fundamentals" of the shape of the data before validating the content of the data
• a vignette centered around "Taking action" covering getting notified, stopping automation, and inspecting results
• and possibly one around tailoring the validation report to stakeholders/people who understand the context of the data well but may not be data-focused themselves

I'm gonna keep this PR as a draft for now but your comments on the first two vignettes would be very welcome already!

[hfrick]

This one leans heavily on the user guide for the python version, but adapted for the R version

[hfrick]

Is there a way to check that a column exists but not bothering with the type? I wasn't expecting the NULL to allow the column to be missing.

[rich-iannone]

There is but it's hacky, not well-explained, and so should be improved in the future:

small_table %>%
  expect_col_schema_match(
    schema = col_schema(
      date_time = "POSIXct",
      date = "Date",
      a = NULL,        # Column exists but type is ignored
      b = NULL,        # Column exists but type is ignored  
      f = "character",
      e = "logical"
    ),
    complete = FALSE,
    in_order = FALSE,
    is_exact = FALSE  # Required for NULL to work
  )

This seems more like a side effect of exact type-matching and isn't very good API design.

[hfrick]

I think your example is passing more because complete = FALSE and your schema is missing columns c and d.

Only using is_exact = FALSE does not turn b = NULL into a check that b exists:

library(pointblank)

# baseline: passes
data.frame(a = 1:2) |>
  col_schema_match(col_schema(a = "integer"))
#>   a
#> 1 1
#> 2 2

# add b to data frame and to schema as NULL and strict check fails as it should
data.frame(a = 1:2, b = 1:2) |> 
  col_schema_match(col_schema(a = "integer", b = NULL))
#> Error: Failure to validate that column schemas match.
#> The `col_schema_match()` validation failed beyond the absolute threshold level (1).
#> * failure level (1) >= failure threshold (1)

# relaxing `is_exact` allows the check to pass
data.frame(a = 1:2, b = 1:2) |>
  col_schema_match(col_schema(a = "integer", b = NULL), is_exact = FALSE)
#>   a b
#> 1 1 1
#> 2 2 2

# but it still passes when b is missing from the data frame
# i.e. it's not a check for existence
data.frame(a = 1:2) |>
  col_schema_match(col_schema(a = "integer", b = NULL), is_exact = FALSE)
#>   a
#> 1 1
#> 2 2

^{Created on 2025-08-22 with reprex v2.1.1}

[rich-iannone]

Thanks for checking how these options interact. Definitely need to just make NULL ignore the column type check (but still check column existence), regardless of the options!

[rich-iannone]

I've just read through the vignettes more carefully and I think they are both well written!

[rich-iannone]

Everything looks good! I think we need to leave out the part about checking columns w/o column types/classes until we fix it in the codebase (I'll create an issue for that). Once that's implemented the vignette could be revised in a separate PR to put that example back in (it's a valuable usage example!).

[hfrick]

Sounds good! I've opened the issue: #645

[hfrick]

@kmasiello It would be great to have your eyes on this as well! 🙌

[kmasiello]

I don't expect the average user to know what a tbl_dbi object is. Better to refer to this as a "database table."

[kmasiello]

How can the user know the available types to choose from? Do we recommend using typeof(), class(), other?

[kmasiello]

How can the user know the list of available SQL types? is there a reference we can provide?

[kmasiello]

Suggested change

The default is to define the schema in R types like `"numeric"` or `"character"` and you can use it to validate any of the tables pointblank supports, so not just data frames in R but also tables in databases such as `tbl_dbi` objects. While it may be convienent to define the schema in R types, note that this requires the data to be pulled into R first, which may not be efficient for large datasets. Alternatively, you can define the schema in SQL types (like `BIGINT` and `VARCHAR`) and validate directly against the SQL table without pulling data into R.

The default is to define the schema in R types like `"numeric"` or `"character"` and you can use it to validate any of the tables pointblank supports, so not just data frames in R but also tables in databases such as `tbl_dbi` objects. While it may be convienent to define the schema in R types, note that this requires the data to be pulled into R first, which may not be efficient for large datasets. Alternatively, you can use the `.db_col_types` argument to define the schema in SQL types (like `BIGINT` and `VARCHAR`) and validate directly against the SQL table without pulling data into R.

[kmasiello]

I get an error creating this agent.

Error in `if (grepl("sql server|sqlserver", tbl_src_details)) ...`:
! argument is of length zero
Hide Traceback
    ▆
 1. └─pointblank::create_agent(sales_db)
 2.   └─pointblank:::get_tbl_information(tbl = tbl)
 3.     └─pointblank:::get_tbl_information_dbi(tbl)

[hfrick]

This is a weird one. When I render the vignette, it works. When I send the code chunk, it works. When I send the code line-by-line into the console, I also get that error. I've tried it in Positron and RStudio. @rich-iannone do you have any idea what might be going on here?

[hfrick]

I opened #658 for this

[kmasiello]

I would omit the action_levels here since this is about the type matching.

[hfrick]

I agree that they could be distracting. My challenge is that the default settings result in a table that does not make it very obvious when a step fails: the stripe on the left-hand side of the table is green-ish, not red. See #627 for an example (and Maëlle also getting confused by this).

Alternatively, I could use interrogate(progress = TRUE) so that we get the console output. Would that be better?

[kmasiello]

oh, I like the red line for illustrating the point. how about also explicitly including the is_exact = FALSE argument for added clarity. You could also just add a note that commonly action_levels are used to trigger downstream effects

[hfrick]

I also want to illustrate that is_exact = TRUE is the default, so I talk about that in the text and only set the argument when it differs from the default.

[kmasiello]

This is a surprise! When you defined the sales df, you specified the sale_date column with as.POSIXct so it's a big surprise that POSIXt shows up as one of the class types. And if you check the x_list$col_types from the agent, it says that the sale_date is only POSIXct. Without doing class(sales$sale_date), one would never discover this anomaly.

After reading through the examples, I think we should be more explicit about how to handle types of dates because pointblank can get very picky. I would like to see us call out explicitly that date handling can be tricky and here's how to work with it. If we set is_exact = FALSE to permit flexibility in dates, does this also allow other types that aren't exact to pass (e.g., can an expected numeric pass if it is an integer now?)

[hfrick]

I'll look into the date question some more but in the meantime: is_exact = FALSE does not allow integers to pass as numeric, it only loosens strictness for those columns which are defined as NULL in the schema.

[hfrick]

Maybe this is better placed in its own little piece of documentation? #659

[kmasiello]

Do you want to add a mention that you can access information about if certain thresholds were met by looking at the x_list $warn, $stop, and $notify values?

[hfrick]

I think the mention of the x-list fits better here than in the schema vignette, so adding it here!

[hfrick]

This actually fails 😳 I've opened #657 for it.

[rich-iannone]

Thanks for catching this bug and creating the issue!