Dataset Filtering

Modified on Tue, 5 Aug at 1:40 PM

Dataset Filtering in Droplet Forms

Overview

Dataset filtering in Droplet allows you to dynamically filter data within your forms using the filterDataset() expression. This powerful feature enables you to show only relevant data to users based on their attributes, form inputs, or other criteria.

Filtering datasets allows you to accomplish the following goals:

focus the data used on the form to information relevant to the active user
filter out sensitive values when necessary (SSN's, DOB's, etc)
reduce the amount of information pulled from the server to help performance

Configuring the Dataset in the Code Editor

Go into the form builder
Switch to the code editor
Go to the Datasets tab

To set up the filtering you will modify the dataset JSON so it roughly matches this:

{
  "local": {},
  "global": {
    "staff": {
      "datasetId": "Yrobox",
      "filters": [
        {
          "steps": [
            "step1"
          ],
          "filter": "filterDataset( matches: [ { fields: ['school_id'], value: ['a' } ] "
        },
        {
          "steps": [
            "start"
          ],
          "filter": "all"
        }
      ]
    },
    "school": {
      "datasetId": "4DKbpM",
      "filters": [
        {
          "steps": [
            "start",
            "step1"
          ],
          "filter": "filterDataset({ matches: [ { fields: ['school_type'], value: 'High School' } ] })"
        }
      ]
    }
  }
}

Remember, the datasetId values will be specific to your datasets. You can get them from the Datasets display.

Basic Syntax

filterDataset({
  search: [path1, path2, ...],      // Optional: Navigate to specific parts of nested data
  matches: [                        // Optional: match conditions
    {
      fields: ["fieldName"],        // Field(s) to match against
      value: "valueToMatch",        // Value to compare (can be array for multiple values)
      operator: "eq"                // Optional: Comparison operator (default: "eq")
    }
  ],
  matchType: "all",                 // Optional: "all" (AND) or "any" (OR) - default: "all"
  include: ["field1", "field2"],    // Optional: Only include these fields in results
  exclude: ["field3", "field4"]     // Optional: Exclude these fields from results
})

Parameter Details

Parameter	Type	Description	Required	Default
`search`	Array of Strings	Path(s) to navigate nested data structures. Filters only within these paths.	No	`[]`
`matches`	Array of Objects	List of filter conditions. Each object specifies fields, value(s), and optional operator.	No	`[]`
`matchType`	String (`all`/`any`)	Determines if all (`AND`) or any (`OR`) match conditions must be met.	No	`"all"`
`include`	Array of Strings	Only include these fields in the filtered results.	No	`undefined`
`exclude`	Array of Strings	Exclude these fields from the filtered results.	No	`undefined`
`all`	String	Using this as the filter will instruct the filtering process to exclude this dataset from the given step(s). See the examples above to see how to use it.

When setting up filters you can use any of the parameters listed above independently or in combination, except for the matchType parameter, which only applies when using multiple match filters.

Match Object Details

Name	Description
`fields`	This is an array of field names to match against. If multiple names are provided it indicates a path to the field. For example, if you have a field Admin with a Name and Email underneath and you want to filter specifically on admin->email you would add both values: ["admin", "email"]
`value`	The value to match against. This value can be a user attribute identifier, the id for any element of the parent form, or a static value. This can also be an array of matches, so you can set up multiple matches. If you do that the match type for the array will be "any". Example: { fields: 'email', value: ["email1", "email2"] will return all dataset records where the email is either email1 or email2 }
`operator`	This is an optional match type indicator. The default value is 'eq" (equals), but you can use any of the values listed in the Comparison Operators list below

Common Use Cases

1. Filter by User Attributes

Filter data based on the current user's attributes using dropletAttributes:

filterDataset({
  matches: [{ fields: ['department'], value: dropletAttributes.department }],
});

2. Filter by Form Input Values

Filter data based on what users have entered in form fields:

filterDataset({
  matches: [
    { fields: ['department'], value: targetDepartment }, // References form field with ID "targetDepartment"
    { fields: ['active'], value: showActiveOnly }, // References form field with ID "showActiveOnly"
  ],
});

3. Filter Nested Data with Search Paths

Navigate to specific parts of nested datasets using the search parameter:

filterDataset({
  search: ['Metro School District', 'Elementary'],
  matches: [{ fields: ['enrollment'], value: 450 }],
});

4. Filter with Multiple Values

Use arrays to match against multiple possible values (OR logic within a single field):

filterDataset({
  matches: [{ fields: ['department'], value: ['Engineering', 'Marketing'] }],
});

5. Exclude Dataset from Step

You can use the filters to exclude specific datasets from being pulled at different stages of the submission workflow. Be careful using this with some steps as the display values may require having the dataset in place to display the values.

{
  "steps": [
    "start"
  ],
  "filter": "all"
}

Comparison Operators

The operator field supports various comparison types:

"eq" - Equals (default)
"ne" - Not equals
"gt" - Greater than
"gte" - Greater than or equal
"lt" - Less than
"lte" - Less than or equal

filterDataset({
  matches: [
    { fields: ['age'], value: 30, operator: 'gte' },
    { fields: ['salary'], value: 100000, operator: 'lt' },
  ],
});

Match Types

Control how multiple filter conditions are combined:

AND Logic (Default)

All conditions must be true:

filterDataset({
  matches: [
    { fields: ['department'], value: 'Engineering' },
    { fields: ['active'], value: true },
  ],
  matchType: 'all', // This is the default
});

OR Logic

Any condition can be true:

filterDataset({
  matches: [
    { fields: ['age'], value: 25 },
    { fields: ['age'], value: 35 },
  ],
  matchType: 'any',
});

Field Selection

Include Only Specific Fields

filterDataset({
  matches: [{ fields: ['active'], value: true }],
  include: ['name', 'department', 'salary'],
});

Exclude Specific Fields

filterDataset({
  search: ['Metro School District'],
  exclude: ['contacts', 'students'],
});

Working with Different Data Types

Form Element Types

The filter can reference various form element types:

Text Input: targetDepartment
Dropdown: selectedDepartment
Multi-select Dropdown: selectedDepartments (returns array)
Checkbox: requiredSkills (returns array of checked values)
Boolean/Toggle: showActiveOnly
Date/Time: filterDate
Computed Fields: computedDepartment

Array Fields

Filter by values within array fields:

filterDataset({
  matches: [
    { fields: ['skills'], value: 'JavaScript' }, // Matches if "JavaScript" exists in skills array
  ],
});

Filter by multiple array values:

filterDataset({
  matches: [
    { fields: ['skills'], value: ['JavaScript', 'Python'] }, // Matches if ANY of these skills exist
  ],
});

Advanced Examples

1. Combining User Attributes with Form Data

filterDataset({
  search: [dropletAttributes.district, levelSelect],
  matches: [{ fields: ['enrollment'], value: minEnrollment, operator: 'gte' }],
});

2. Complex Nested Filtering

filterDataset({
  search: ['Metro School District'],
  matches: [{ fields: ['contacts', 'title'], value: 'Principal' }],
  include: ['address', 'phone', 'enrollment'],
});

3. Multi-condition Filtering with Different Operators

filterDataset({
  matches: [
    { fields: ['department'], value: selectedDepartment },
    { fields: ['salary'], value: minSalary, operator: 'gte' },
    { fields: ['active'], value: true },
  ],
});

Troubleshooting

Debug Tips

Test filters with simple conditions first, then add complexity
Use browser developer tools to inspect the actual data structure
Verify user attributes are available and contain expected values
Check that form elements have values before referencing them