`civex.extract_from_filename`

Apply a regex to a file field's filename (or a plain string field) and optionally convert the captured value to a typed output. Reach for this when the data you need — a timestamp, a selection number, a session ID — is embedded in a filename rather than stored as its own field. Works with file, file_list, and string fields.

Plugin ID: civex.extract_from_filename
Category: data-access
Capabilities: none

Config

Field	Type	Required	Default	Description
`field`	string	yes		Field on the trigger record holding the filename to match (a `file`/`file_list` field, or a plain string field).
`pattern`	string	no	(.+)	Regex applied to the filename. The first capture group (or the whole match if there is none) is extracted.
`output_type`	string	no	string	Type to convert the captured text to: string \| integer \| float \| date \| datetime.
`date_format`	string \| null	no	null	Token format for parsing the captured text when `output_type` is date/datetime, e.g. 'YYYYMMDD-HHmmSS'. Tokens are YYYY MM DD HH mm SS; non-token characters are treated as raw regex, so e.g. 'YYYYMMDD[-_]HHmmSS' matches both dashes and underscores. Required when output_type is date or datetime.

Outputs

Name	Type	Required	Description
`value`	any	yes	The captured text converted to `output_type`.
`filename`	string	yes	The filename the pattern was applied to.
`extracted`	string	yes	The raw captured text, before conversion.

date_format tokens

Token	Matches	Example
`YYYY`	4-digit year	`2024`
`MM`	2-digit month	`03`
`DD`	2-digit day	`15`
`HH`	2-digit hour (24h)	`09`
`mm`	2-digit minute	`30`
`SS`	2-digit second	`00`

All other characters in the format string are treated as raw regex fragments — not strftime codes. This lets you use [-_] to match either a dash or underscore as a separator:

YYYYMMDD[-_]HHmmSS   →  matches  20240315-093000  and  20240315_093000

Extracted datetimes carry no UTC offset: a timestamp in a filename is wall time where the file was recorded. When the value is saved it is read in the datetime field's timezone restriction, else the collection's timezone, else UTC, and stored as a UTC ISO 8601 string. Set the collection's timezone (civex collection update NAME --timezone America/Chicago) so extracted times land on the right instant.

Examples

Extract a datetime from 20210218_075000_recording.wav:

- id: extract_time
  plugin: civex.extract_from_filename
  config:
    field: audio_file
    pattern: '(\d{8}[-_]\d{6})'
    output_type: datetime
    date_format: 'YYYYMMDD[-_]HHmmSS'

Extract a selection number from sel_042_contour.csv:

- id: extract_num
  plugin: civex.extract_from_filename
  config:
    field: contour_file
    pattern: 'sel_(\d+)'
    output_type: integer