diff --git a/404.html b/404.html index cbda3281..38d3b507 100644 --- a/404.html +++ b/404.html @@ -30,7 +30,7 @@ FreesearchR - 26.3.4 + 26.3.5 + + + + + +
+
+
+

Validate a REDCap server-side filter string against a data dictionary

+ Source: R/redcap_read_shiny_module.R +
validate_redcap_filter.Rd
+
+ +
+

Checks that a REDCap filter expression is syntactically correct and +consistent with the field types defined in the project data dictionary. +Plain text without field references is always rejected. Multi-clause +filters joined by AND or OR are supported.

+
+ +
+

Usage

+ 
validate_redcap_filter(filter, dictionary)
+
+ +
+

Arguments

+ + +
filter
+

A single character string containing the filter expression, +e.g. "[age] > 18" or "[cohabitation] = '1' AND [age] > 18".

+ + +
dictionary
+

A data frame representing the REDCap data dictionary in +API export format, as returned by e.g. REDCapCAST::get_redcap_metadata(). +Must contain at least the columns field_name and field_type. +The columns text_validation_type_or_show_slider_number and +select_choices_or_calculations are used when present for stricter +type and choice validation.

+ +
+
+

Value

+

A named list with two elements:

valid
+

Logical. TRUE if the filter passes all checks.

+ +
message
+

Character. "Filter is valid." on success, or +a newline-separated string of error messages describing every problem +found.

+ + +
+
+

Details

+

Validation rules by field type:

calc
+

Numeric fields. Value must be an unquoted number. +All comparison operators (=, !=, <, >, +<=, >=) are accepted.

+ +
text with date validation
+

Fields with validation type +date_ymd, date_dmy, datetime_*, etc. Value must be +a quoted date/datetime string in 'YYYY-MM-DD' format. All +comparison operators are accepted.

+ +
text with time validation
+

Fields with validation type +time_hh_mm_ss or time_mm_ss. Value must be a quoted time +string, e.g. '14:30:00'. All comparison operators are accepted.

+ +
radio / dropdown
+

Categorical fields. Value must be a +quoted choice code (e.g. '1') that exists in the field's choice +list. Only = and != are accepted.

+ +
text (plain)
+

Free-text fields. Value must be a quoted string. +Only = and != are accepted.

+ + +
+ +
+

Examples

+ 
if (FALSE) { # \dontrun{
+dict <- REDCapCAST::get_redcap_metadata(
+  uri    = "https://redcap.example.com/api/",
+  token  = Sys.getenv("REDCAP_TOKEN")
+)
+
+validate_redcap_filter("[age] > 18", dict)
+#> list(valid = TRUE, message = "Filter is valid.")
+
+validate_redcap_filter("only plain text", dict)
+#> list(valid = FALSE, message = "Filter must contain at least one field ...")
+
+validate_redcap_filter("[cohabitation] = '1' AND [age] > 18", dict)
+#> list(valid = TRUE, message = "Filter is valid.")
+} # }
+
+
+
+
+ + +
+ + + + + + + diff --git a/reference/validate_redcap_filter.md b/reference/validate_redcap_filter.md new file mode 100644 index 00000000..f9f9201d --- /dev/null +++ b/reference/validate_redcap_filter.md @@ -0,0 +1,93 @@ +# Validate a REDCap server-side filter string against a data dictionary + +Checks that a REDCap filter expression is syntactically correct and +consistent with the field types defined in the project data dictionary. +Plain text without field references is always rejected. Multi-clause +filters joined by `AND` or `OR` are supported. + +## Usage + +``` r +validate_redcap_filter(filter, dictionary) +``` + +## Arguments + +- filter: + + A single character string containing the filter expression, e.g. + `"[age] > 18"` or `"[cohabitation] = '1' AND [age] > 18"`. + +- dictionary: + + A data frame representing the REDCap data dictionary in API export + format, as returned by e.g. `REDCapCAST::get_redcap_metadata()`. Must + contain at least the columns `field_name` and `field_type`. The + columns `text_validation_type_or_show_slider_number` and + `select_choices_or_calculations` are used when present for stricter + type and choice validation. + +## Value + +A named list with two elements: + +- `valid`: + + Logical. `TRUE` if the filter passes all checks. + +- `message`: + + Character. `"Filter is valid."` on success, or a newline-separated + string of error messages describing every problem found. + +## Details + +Validation rules by field type: + +- `calc`: + + Numeric fields. Value must be an unquoted number. All comparison + operators (`=`, `!=`, `<`, `>`, `<=`, `>=`) are accepted. + +- `text` with date validation: + + Fields with validation type `date_ymd`, `date_dmy`, `datetime_*`, etc. + Value must be a quoted date/datetime string in `'YYYY-MM-DD'` format. + All comparison operators are accepted. + +- `text` with time validation: + + Fields with validation type `time_hh_mm_ss` or `time_mm_ss`. Value + must be a quoted time string, e.g. `'14:30:00'`. All comparison + operators are accepted. + +- `radio` / `dropdown`: + + Categorical fields. Value must be a quoted choice code (e.g. `'1'`) + that exists in the field's choice list. Only `=` and `!=` are + accepted. + +- `text` (plain): + + Free-text fields. Value must be a quoted string. Only `=` and `!=` are + accepted. + +## Examples + +``` r +if (FALSE) { # \dontrun{ +dict <- REDCapCAST::get_redcap_metadata( + uri = "https://redcap.example.com/api/", + token = Sys.getenv("REDCAP_TOKEN") +) + +validate_redcap_filter("[age] > 18", dict) +#> list(valid = TRUE, message = "Filter is valid.") + +validate_redcap_filter("only plain text", dict) +#> list(valid = FALSE, message = "Filter must contain at least one field ...") + +validate_redcap_filter("[cohabitation] = '1' AND [age] > 18", dict) +#> list(valid = TRUE, message = "Filter is valid.") +} # } +``` diff --git a/reference/validation.html b/reference/validation.html index 266899db..79d096db 100644 --- a/reference/validation.html +++ b/reference/validation.html @@ -7,7 +7,7 @@ FreesearchR - 26.3.4 + 26.3.5