header_validations.md

Contents

• Introduction
• Migrating from Ruby CSV
• Ruby CSV Pitfalls
• Parsing Strategy
• The Basic Read API
• The Basic Write API
• Batch Processing
• Configuration Options
• Row and Column Separators
• Header Transformations
• Header Validations
• Column Selection
• Data Transformations
• Value Converters
• Bad Row Quarantine
• Instrumentation Hooks
• Examples
• Real-World CSV Files
• SmarterCSV over the Years
• Release Notes

---

Header Validations

When importing data it is important to verify that all required columns are present — catching a missing column upfront is far better than a cryptic error later when your code tries to access a key that was never populated.

required_keys

Use required_keys to specify an array of hash keys that must be present after header transformation. Validation runs once, after the header row is parsed and all header transformations (downcase, symbolize, key_mapping) have been applied — so use the transformed key names, not the raw CSV header strings.

If any required key is absent, SmarterCSV::MissingKeys is raised before any data rows are processed.

options = {
  required_keys: [:source_account, :destination_account, :amount]
}
data = SmarterCSV.process('/tmp/transactions.csv', options)
# => raises SmarterCSV::MissingKeys if any of the three columns are missing

Accessing the missing keys

SmarterCSV::MissingKeys exposes the missing keys via the keys accessor:

begin
  data = SmarterCSV.process('/tmp/transactions.csv',
    required_keys: [:source_account, :destination_account, :amount])
rescue SmarterCSV::MissingKeys => e
  puts "Missing columns: #{e.keys.join(', ')}"
  # => "Missing columns: amount"
end

Interaction with key_mapping

required_keys uses the post-mapping key names. If you remap CSV headers, reference the mapped names:

options = {
  key_mapping:   { acct_from: :source_account, acct_to: :destination_account },
  required_keys: [:source_account, :destination_account, :amount],
}

---

silence_missing_keys

When using key_mapping, SmarterCSV raises SmarterCSV::KeyMappingError if a mapped key is not found in the CSV header. Use silence_missing_keys to make some or all mapped keys optional:

# All mapped keys are optional — no error if any are absent
options = {
  key_mapping:          { optional_field: :my_field, required_field: :other_field },
  silence_missing_keys: true,
}

# Only specific mapped keys are optional
options = {
  key_mapping:          { optional_field: :my_field, required_field: :other_field },
  silence_missing_keys: [:optional_field],
}

---

PREVIOUS: Header Transformations | NEXT: Column Selection | UP: README