Select from file

select_one_from_file and select_multiple_from_file work like select_one and select_multiple, but instead of defining choices in the choices worksheet, the choices are loaded from an external CSV or XML file attached to the form. This is useful when your choice list is very long, changes frequently, or needs to be updated without rebuilding the entire form.

Basic XLSForm Specification link

The filename after the type name must match the name of the file you attach when uploading the form.

CSV file format link

Your CSV file must have at least two columns: name (the stored value) and label (the displayed text). You can add any number of extra columns for filtering.

health_facilities.csv:

  name,label,district,type
HF001,Nairobi Central Clinic,Nairobi,clinic
HF002,Westlands Health Centre,Nairobi,health_centre
HF003,Kisumu District Hospital,Kisumu,hospital
  

Filtering choices link

Use the choice_filter column to show only the choices that match the current context. Reference CSV columns with their column name directly (no ${}):

In this example, only facilities in the selected district are shown. The district in choice_filter refers to the district column in the CSV file; ${district} refers to the form field named district.

Uses link

Select-from-file questions are commonly used for:

1. Long choice lists — health facilities, schools, villages, species lists (hundreds or thousands of items)
2. Frequently updated lists — when the master list changes between survey rounds, update only the CSV without rebuilding the form
3. Shared reference data — one CSV file used across multiple forms
4. Filtered cascading selects — load all regions/districts/villages in one file, then filter by the parent selection

Attaching the file link

When you upload your form to rtSurvey, attach the CSV file as a media attachment. The filename in the form definition must exactly match the filename of the attachment.

Using choice-label() with from-file link

To display the label of a selected choice in a note or calculate field:

Best Practices link

1. Keep your CSV files under 5,000 rows for good performance on mobile devices.
2. Always include a name and label column — additional columns are optional.
3. For cascading selects, use a single CSV with a parent column and filter with choice_filter.
4. Version your CSV filenames (e.g., facilities_v3.csv) when making breaking changes to the column structure.
5. Test filtering expressions carefully — a typo in choice_filter will silently show no choices.

Limitations link

• Very large CSV files (10,000+ rows) can slow down form loading, especially on low-end devices.
• CSV files must be uploaded together with the form — they cannot be fetched from a URL at runtime (use search() or pulldata() for dynamic lookups).
• select_multiple_from_file is less commonly supported across clients — verify compatibility before using it.

Comparison with search() link

For large, frequently changing, or server-side datasets, see Dynamic search.