Add optional Extract guides alongside the grouped Registry reference

[ebhills]

Add optional how-to guides that complement the existing Registry reference. The customer-facing Extract page must continue to list all wrangles with their descriptions, parameter metadata, and examples together. A guide must not replace that page or require readers to navigate elsewhere for the reference.

This is a deferred enhancement related to #30. The current Extract revision is limited to better industrial examples, corrected parameter information, and moderate prose expansion within the existing reference layout. No guide rollout or wider navigation redesign is part of that revision.

Proposed guide scope

• A separate Extract selection guide comparing regex, brackets, built-in code/attribute/property extraction, AI, saved custom models, HTML, address and date capabilities.
• Optional individual how-to material for advanced topics: AI field definitions, evidence selection, output formats, missing values, saved definitions, web evidence, execution controls and troubleshooting.
• Cross-cutting explanations of row filtering and recipe composition, linked from the relevant references.
• Concise links between reference and guide pages, with the Registry remaining the canonical source for parameter contracts and executable examples.
• Consider human and agent retrieval separately; publishing a guide must not silently change Rai's bundle, eligibility or runtime support.

Acceptance criteria

• Agree on one separate guide prototype before implementing a wider guide system.
• Retain the grouped Extract reference, metadata, examples, anchors and familiar navigation.
• Make guides optional and clearly separate from the reference; avoid duplicating executable contracts and fixtures.
• Recheck saved draft prose against the current WranglesPY implementation, docstrings and embedded schemas before publication.
• Label illustrative service outputs separately from executed examples.
• Do not include WranglesXL functionality.

Preserved draft material

The drafts below preserve the earlier guide prototype for later editing. They are working material, not approved publication copy. References to an “Extract guide” currently point to the existing reference route; a future implementation must assign a separate guide route. The parameter metadata and fixture examples remain in the active Registry sources rather than being duplicated here.

Extract group guide

Extract wrangles turn information inside a value into fields you can filter, compare and reuse. Start with the structure of your source: a predictable part-code pattern needs a different approach from a supplier description whose wording changes on every row.

Each reference below includes industrial sample data, recipes that compare key options, and the resulting columns. Your input columns usually remain available when you write to a new output column; check the individual wrangle's output rules before overwriting data.

Choose an extraction method

What you have	Start with	Why it fits
A known part-code, dimension or label pattern	extract.regex	You can describe the exact text to match and control capture groups.
Values enclosed in brackets	extract.brackets	Pull out bracketed specifications or annotations without writing a pattern.
Alphanumeric part codes mixed into descriptions	extract.codes	Find candidate codes and adjust how aggressively false positives are filtered.
Measurements such as voltage, length or weight	extract.attributes	Use predefined measurement types, labels and output formats.
Product properties such as material or color	extract.properties	Use the supported property categories rather than defining your own extraction model.
Inconsistent descriptions that need interpretation	extract.ai	Define the fields and evidence rules, including structured or nested output.
A saved custom extraction model	extract.custom	Reuse the model's trained extraction behavior. For a saved extract.ai definition, use extract.ai with model_id.
Product specifications embedded in HTML	extract.html	Extract readable text or collect links from the supplied markup.
Supplier or warehouse addresses inside text	extract.address	Extract address information with the address service.
A date column that needs calendar fields	extract.date_properties	Derive fields such as year, month or weekday from datetime values.
Start and end dates for a maintenance or delivery window	extract.date_range	Count scheduled calendar points between dates using a selected frequency.

Compare options on the same product data

Keep the original part description and write each variation into a different output column. That makes the effect of the parameter visible and avoids accidentally applying the next variation to an already transformed value.

For example, the regex examples compare whole matches with captured values, while the AI examples compare input evidence and result formats. Read the note above each example: local results are checked offline; service results are clearly identified when they are illustrative.

When a wrangle returns several matches, decide whether the next recipe step needs a list, separate columns or joined text. Supported formats and the interaction with first_element vary by wrangle, so use its parameter guidance rather than assuming every Extract wrangle accepts the same options.

Apply extraction to selected rows

Use where to select which rows an eligible Extract wrangle processes, and where_params to bind changing values. For an ordinary extraction, matching rows receive the extracted result and the other rows remain in the dataframe. Use if when the entire step should run only under a condition.

The parameter reference on each page lists the controls that wrangle supports. A wrangle that derives dates or returns structured objects may have different input requirements from a text extractor; converting a column's type and filtering rows are separate decisions.

Build a reliable recipe

Start with the smallest extraction rule that matches your data. Review missing matches and multiple matches, preserve the source description, and check the resulting value types before passing them to a later wrangle.

For agent-authored recipes, choose the exact key from the reference, use its supported parameter shapes, and retrieve the relevant example and its prerequisites. A documented capability may still require a service account, an external API key or access to a saved model; documentation availability does not grant that access.

Individual guide: address.md

Address

When to use

Use extract.address when supplier records combine street, city, region, and country in one shipping label or free-text field. A Wrangles account and access to the address service are required. Extracted components support review and grouping; finding an address does not establish that it is complete or deliverable.

Behavior and output

Each call selects one component with dataType. Keep the source column and use distinct outputs when collecting several components from the same label. A single destination normally contains a list of matches for each row, including an empty list when nothing is recognized.

Multiple inputs with one output are combined before extraction. Equal input and output counts process each pair separately. For one input, output_format: columns and a scalar destination such as city create names such as city 1 and city 2. Explicit destination names cap retained matches, fill missing positions with empty strings, and may create fewer columns if no row supplies that many matches.

Parameter choices

• Select streets, cities, regions, or countries; this contract has no postal-code option.
• Keep output_format: list for downstream processing. Use concatenate with char for display, or columns for positional fields. Dictionary output is unsupported.
• Use where when only some rows need enrichment. Nonmatching rows remain in the dataset; a newly created destination is blank on those rows.
• Recognition and normalized spellings depend on the supplied text. These examples use fictional addresses and illustrative outputs.

Related capabilities

Use extract.regex for a precisely specified pattern in an address, or extract.custom for an approved location vocabulary. Use merge.concatenate to combine structured address fields for display.

Individual guide: ai.md

AI

When to use it

Use extract.ai to turn varied catalog descriptions, supplier notes, and specification columns into named attributes. It can distinguish a valve's electrical supply from its port size, normalize material abbreviations, and return related measurements as structured values. Each row is interpreted separately using the selected input columns and a definition of the requested outputs.

For a predictable text pattern, start with extract.regex. For built-in numeric attribute extraction, compare extract.attributes; for supported text properties, compare extract.properties. The Extract guide helps select an approach. Choose AI when context or variation makes those rules insufficient; define what counts as evidence and how the result should be normalized.

Before you run

Supply api_key through an existing recipe variable such as ${OPENAI_API_KEY}. Inline definitions require an OpenAI key and a compatible configured model; using model_id also requires access to that saved definition through your Wrangles account.

Choose input explicitly. A string selects one column; a list combines those columns into one record for each row. Omitting input sends every current dataframe column, including columns added by earlier steps. The examples use explicit inputs so each comparison receives the intended source evidence.

Provide either an inline output definition or model_id. Existing input columns are retained, and a result written to an existing column replaces that column's values. Use distinct destinations when comparing variants.

Define the fields you need

For an inline definition, output is normally an object whose keys become destination column names. Give each field a description that explains which value to select, what to ignore, the required units, and what to return when evidence is absent. Set type for reliable downstream handling: for example, use number for a voltage in volts and string for the source notation.

Definition choice	What it controls	Industrial example
description	Meaning, evidence, selection, and normalization rules	Extract supply voltage, ignoring pressure and dimensions
type	Value shape and data type	A number for voltage_v, or an array of material strings
enum	A finite set of allowed values	NPT, BSPP, or BSPT for a thread standard
nullable	Whether an unsupported value may be null	Allow null when the thread is unstated
properties, required	Fixed child fields in an object	A measurement with a value and a unit
items	The schema for each array member	Every extracted material is a string
additionalProperties	Whether an object accepts keys beyond its named fields	Permit supplier-specific attribute names only when needed

A field may instead contain a description string, or output may be a field name or list of field names/definitions. Those shortcuts provide less control than an explicit typed definition. In a recipe, a bare output string is the field name; place detailed extraction instructions in the field's description.

Missing values, defaults, and nested objects

Top-level field keys remain required, but their values allow null by default. An enum also permits null unless nullable: false is set. default is a schema annotation: it does not insert a fallback when the source is missing. If a fallback is necessary, describe it explicitly and consider a separate deterministic step after extraction.

Named nested properties are required and non-null by default. Declare nullable: true on a child when its value may be unknown, and set required deliberately when using a fixed object. The port example demonstrates a stable object whose individual values can be null.

The recipe wrapper represents a top-level null as an empty string in columns output. Nulls remain null inside dictionary output or nested objects. This distinction matters when testing for missing data or writing a later filter.

An object with no named properties is a dynamic dictionary. Dynamic dictionaries switch off strict provider mode automatically and retain local result validation. For a stable catalog schema, prefer named properties with additionalProperties: false; use dynamic keys when the attributes themselves vary by product.

Guide interpretation with instructions and examples

Use instructions for rules that apply across all requested fields: evidence precedence, whether to preserve source units, and how to handle conflicting supplier columns. Field descriptions define individual attributes; instructions define shared behavior.

There are two model-visible example scopes:

• Field examples show one field's values. A scalar or list supplies typical output values; a paired {input: ..., output: ...} example explains how source evidence maps to that field alone.
• record_examples show the complete expected output record. Use them when multiple fields must stay consistent, when a measurement contains related value/unit fields, or when a missing fact changes several outputs.

Both paired forms accept optional name and notes. Use an object for example input when your selected columns form a structured record; a multiline string stays plain text. Example output must match the declared schema. Omitted nullable fields in record examples are filled with null, while required non-null nested values must be supplied. Examples teach a rule or format; they do not force the model to copy an example value into unrelated rows.

Choose an output shape

output_format	Result in the dataframe	Destination rule
columns (default)	One column for each field; arrays and nested objects remain values	Inline field names, or the saved field names when output is omitted
dictionary	The complete result object in one column	The sole output name, or the column output when an inline definition has multiple fields
concatenate	One string, with list members or saved result field values joined by char	Requires a single output destination; separator defaults to comma-space

The output-format comparison runs three calls in the same recipe to show the difference. dictionary retains field names as keys; it is not JSON text. concatenate discards that structure and is useful when a later export needs a flat display value.

Saved definitions and output destinations

model_id reuses saved fields and their extraction guidance. In the recipe wrapper, combining model_id with output makes output a destination selector; it does not override the saved field schema. This differs from the lower-level Python API, so recipe authors should follow the recipe behavior described here.

Omit output to create the saved field columns. To store a complete multi-field result under a new name, provide one output name with output_format: dictionary. If you supply a list, its length must match the saved field count, and the current wrapper matches those destinations by saved field name. Use the saved names instead of relying on positional renaming.

A saved definition can supply its model and shared guidance. Check the actual saved definition before reproducing it in a recipe; its identifier alone does not explain the fields, examples, or model settings. Use extract.ai directly for saved AI extraction definitions; extract.custom documents the other saved extraction-model workflow.

Web evidence and source links

web_search: true lets the Responses model decide whether web evidence helps. Set protocol: responses when specifying a protocol; web search is not supported with chat_completions. Include enough product identity in input, such as manufacturer and part code, and use instructions to state the acceptable evidence and how to resolve conflicts with the supplied product data.

A web-enabled call automatically adds web_search_sources, a list of {title, url} objects for each row. The list is empty if no source was used; enabling search does not guarantee a search or a complete answer. The source column is reserved: do not use that name in the input dataframe or as a requested output. It records sources for the row, without mapping each link to an individual extracted field.

Use cache: false when the purpose of the call requires fresh web results. Cached extracted values and their source links are reused together. The fixture examples below describe source-only extraction and do not claim to verify current web facts.

Execution and troubleshooting

threads limits concurrent row requests, timeout limits an individual HTTP attempt, and deadline bounds the whole call including queued rows, retries, and backoff. retries allows additional attempts after retryable failures; it does not extend the overall deadline. The bundled policy currently uses 32 threads, a 12-second request timeout, one retry, and a 15-second total deadline. Workload and deployed configuration can require different values.

The warm-instance result cache reuses identical successful requests by default, with a bundled maximum age of 3600 seconds. Changing the input, extraction definition, or relevant request options changes the request identity. The cache is bounded and is not durable storage. store: false is the default Responses setting; it is separate from this local result cache.

Invalid definitions or incompatible options can stop a call before requests are sent. Provider failures can appear as error text in individual output values, so a completed recipe is not sufficient evidence that every attribute was extracted successfully. Inspect results before treating them as validated product data. If the schema shape is correct but a value is wrong, improve the evidence, selection rule, or examples; strict output mode validates structure rather than factual accuracy.

The configured model is used when no model is supplied. reasoning and verbosity depend on model support; unsupported combinations can be ignored with a warning. Set the model and execution options explicitly when a controlled comparison depends on them, and keep those options fixed while comparing an extraction rule.

Guidance for recipe authors and agents

Select the source columns and state the missing-value rule before creating the schema. Prefer explicit field names, types, units, and allowed values; include a realistic edge case whenever a description alone leaves a decision ambiguous. Keep API keys in recipe variables, and use a saved definition only when its identity and field contract are known.

When chaining extractions, keep input selection explicit and avoid overwriting the source evidence unintentionally. Choose an output shape that the next step can consume, account for top-level empty strings versus nested nulls, and verify example outputs against the current runtime. Use the shared filtering guidance in the Extract guide when only some rows require AI processing.

These examples preserve the full input and output rows so readers and agents can see every column that survives or is added. Their AI values are illustrative expected results, with the execution requirements stated on each example.

Individual guide: attributes.md

Attributes

When to use

Use extract.attributes to recover dimensions, weights, pressures, electrical ratings, and other quantities from supplier descriptions. A Wrangles account and service access are required. Keep the original text alongside the extracted values when reviewers need to distinguish a product rating from a packaging measurement or an alternative part's specification.

Behavior and output

Without attribute_type, each output cell is a dictionary keyed by recognized measurement families. Selecting a family changes the result to a list of its matches. responseContent: span retains matched text; object provides records with span, standard, symbol, unit, and value.

Use desired_unit with a compatible attribute_type and object output to expose the converted number and unit. The source span remains available for comparison. For a recognized range, bound determines the representative numeric value; it does not choose among unrelated measurements elsewhere in the row.

Parameter choices

• Select a family before requesting first_element: true; without one, that combination raises an error. Leave output_format unset to use scalar selection. Explicit formatting, including columns mode, takes precedence.
• Use weight in new recipes. Existing mass recipes have legacy runtime coverage, but the current authoring contract lists weight.
• All-family results support dictionary and columns. A single family supports list, concatenate, and columns. Joining object records produces object text; use span results when preparing a readable measurement list.
• In all-family columns mode, a scalar destination expands actual dictionary keys into columns. An explicit output list selects exact keys. In typed columns mode, a scalar destination generates numbered names and an explicit list caps match positions.
• Multiple inputs with one output are searched together; matched input/output lists are processed separately. Use where for selected rows, which preserves other rows and leaves newly created output fields blank there.
• Missing measurements do not establish a zero value. Preserve empty collections or blanks until the business rule for missing specifications is known.

Related capabilities

Use extract.properties for categorical materials and colours, or extract.ai when context must distinguish several measurements by purpose. Use split.dictionary to unpack measurement objects, and select.list_element to select a later match explicitly.

Individual guide: brackets.md

Brackets

When to use

Use this when suppliers consistently put material grades, dimensions, approvals, or pack quantities inside brackets. It extracts the annotation text without interpreting what the annotation means; use Extract Attributes or Extract Properties for recognition of measurements or categorical properties.

Behavior and output

The default finds (), [], {}, and <> in source order. A scalar output stores a list of extracted values, with [] for no match. include_brackets: true retains the delimiters. Input values are converted to text before matching.

Matching stops at the first closing delimiter of the selected type. It does not parse nested bracket structures, and a bracket pair split across lines is not matched as one span. An unmatched opening or closing bracket alone yields no match. When delimiters are removed, all bracket characters in each matched span are removed.

Parameter choices

• Use find: all on its own, or select named types such as find: [round, square]. Mixing all with specific types does not expand the selection to every type; the explicitly named types determine the matches.
• Keep a scalar output name for lists. Use output_format: concatenate and char to create readable text, with an empty string for no match.
• Multiple output names with one input imply column output and cap the number of matches retained. A scalar name with output_format: columns creates numbered columns up to the largest match count; absent positions are empty strings and an all-empty result still creates the first column.
• Columns are created only up to the largest result count, with at least one column. If no row has enough matches to use every supplied destination name, unused names do not create extra columns.
• A one-element output list retains the scalar-output behavior. An explicit output_format takes precedence over inference from destination names.
• Several inputs with one output are joined with spaces and searched together. Equal-length input and output lists are searched separately. Other multi-column length combinations raise an error unless one source is expanding into explicit match columns.

Related capabilities

Use Extract Regex for other delimiters or precise patterns, Merge Concatenate to control how source columns are combined, and Split List to expand an extracted list in a later step.

Individual guide: codes.md

Codes

When to use

Use extract.codes to recover part-number candidates from supplier descriptions, replacement notes, or cross-reference text. It requires a Wrangles account and extraction-service access. Compare recognized candidates with your catalogue before treating them as approved identifiers.

Behavior and output

A scalar output normally contains a list per row; no match produces an empty list. Several inputs with one output are searched together. Equal input and output counts process each pair separately, which keeps the source of each candidate clear.

first_element: true selects the first returned match and uses an empty string if none exists. It does not select by confidence. Set sort_order deliberately and leave output_format unset: an explicit format takes precedence over first_element.

Parameter choices

• Start with balanced. lenient can retain measurement-like tokens. strict currently shares the balanced false-positive filter but uses a longer default minimum; explicit min_length removes that minimum-length distinction.
• Use min_length, max_length, and disallowed_patterns for known catalogue constraints. Patterns must be a regex string or a JSON-encoded array of regex strings, not a YAML array.
• Keep include_multi_part_tokens: true for identifiers with a spaced suffix. Disable it for catalogues restricted to individual tokens. extract_raw exposes attached characters for review.
• Use lists to retain candidates, concatenate with char for display, or columns for positions. Scalar destinations in columns mode generate numbered names. Explicit names cap matches and may create fewer columns if no row has that many results.
• Use where to process selected rows while preserving the rest. Newly created output fields remain blank on excluded rows.

Related capabilities

Use extract.regex for a known identifier pattern, extract.custom for a saved reference vocabulary, or extract.attributes for measurements. Use lookup to resolve candidates against a reference model.

Individual guide: custom.md

Custom

When to use

Use extract.custom when an approved reference model defines the terms, mapped values, or labels to recover from supplier descriptions. A Wrangles account, service access, and permission to use the selected extraction model are prerequisites. Inspect that model's reference content and matching rules before choosing options or promising particular results.

The examples require a model supplied through ${MODEL_ID} with these ordered mappings: PTFE to Material: PTFE, stainless steel to Material: Stainless Steel, and red to Colour: Red. Its labels are exactly Material and Colour. No model is created by these recipes.

Behavior and output

The model controls recognition and mapped values. Normal unlabelled output is a list of returned entities. use_labels: true changes it to a dictionary of label-to-value lists; label names preserve the model's spelling and case. Do not infer a label vocabulary from a model ID.

By default, unmatched known labels are included with empty lists. include_empty_labels: false omits them. With first_element: true, an unlabelled result becomes one value and labelled results keep one value per label; missing values become empty strings. An explicit output_format, including columns mode, takes precedence over this scalar selection.

Parameter choices

• Use sort: input_order for source sequence or keep training_order when model reference order matters. Choose ordering before reducing a result to its first element.
• case_sensitive, use_spellcheck, and extract_raw change how the saved model matches or represents terms. Raw output is model-dependent; validate it before relying on exact source spelling. Approximate matching should be evaluated with both intended corrections and plausible false matches.
• With one model and one output, multiple inputs are extracted separately and combined with duplicates removed. Equal input/output counts apply one model to each pair. Several model IDs are paired positionally with the input and output lists; supply matching list lengths and repeat an input explicitly when several models must inspect it.
• Unlabelled results support list, concatenate, and columns; labelled results support dictionary and columns. In labelled columns mode, a scalar output expands model label names, rather than creating that scalar-named column. Explicit destination names select exact labels and can overwrite existing columns.
• Always set a new output when preserving the original text matters; omitting it overwrites input columns. Use where for selected rows, leaving other rows intact and new outputs blank on excluded rows.

Related capabilities

Use extract.properties for built-in categorical vocabularies, extract.regex for an explicit pattern, or extract.ai for a contextual extraction definition. Use standardize.custom when the task is reference-based standardization rather than collecting matching entities.

Individual guide: date-properties.md

Date Properties

When to use

Use calendar properties to group inspections by month or quarter, build weekday schedules, or assign service records to ISO weeks. Use Format Dates when you want to change a date's display format, or Date Calculator to move a date forward or backward.

Behavior and output

Each source column is parsed as dates before the property is extracted. Supplying output preserves the source values; omitting it replaces each selected source column with the extracted values. Equal-length input and output lists process several date columns separately.

A null or empty date produces a missing result, shown as null in these examples. Invalid nonempty dates raise a parsing error. Use consistent, unambiguous input formats; this wrangle has no format or dayfirst parameter to resolve ambiguous date strings.

Parameter choices

Property	Result	Important detail
day	Day of month, 1–31	Different from weekday and day of year.
day_of_year	Day number, 1–365 or 366	Leap day changes later day numbers.
month	Month number, 1–12	Useful for sorting; the name is available separately.
month_name	Month name	The pinned runtime returns names such as February.
weekday	Weekday number, 0–6	Monday is 0; Sunday is 6.
week_day_name	Weekday name	The parameter spelling includes week_day.
week_year	ISO week number, 1–53	This is a week number, not a calendar or ISO year; late December can be week 1.
quarter	Calendar quarter, 1–4	Quarters begin in January, April, July, and October.

year is not an accepted property. Use separate calls to compare properties, keeping the original date available for every call.

:::caution Multiple inputs with one output
The current runtime's multiple-input/single-output path fails for a dataframe with more than one row. Use a separate destination for each input, as in the paired-column example, or run separate steps.
:::

Related capabilities

Use Extract Date Range to compare two dates using its documented frequency-counting rules, and Compute Case When to assign reporting labels from extracted values.

Individual guide: date-range.md

Date Range

When to use

Use this to reproduce a specified frequency count across product replenishment, inspection, or maintenance windows. The result depends on the generated schedule, so check the examples before treating it as elapsed days, months, years, or working hours.

:::caution Supply the range explicitly
The current signature defaults to day, but the implementation accepts days and rejects day. Every working example supplies range; omitting it currently raises an error.
:::

Behavior and output

For each row, the wrangle generates a pandas date range using the selected frequency, discards the first generated point, and counts the rest. Both endpoints can contribute points when they align with the schedule, but the first generated point is always discarded. The count is zero if the generated sequence has zero or one point, including same-date and reversed ranges.

This is particularly important for anchored and business frequencies: if the start is a Saturday, the first business-day point is Monday and is discarded. Saturday through Tuesday therefore returns 1 business day in the pinned runtime, whereas Friday through Tuesday returns 2. Likewise, months uses month ends and drops the first generated month end even when the range starts mid-month.

Both source date columns are converted to datetime values in the returned dataframe. Missing or invalid endpoints raise an error instead of producing a blank count. Timezone information is removed for counting without first converting the local times to a shared timezone; normalize timestamps beforehand when elapsed time across zones matters.

Parameter choices

Frequency	Generated schedule
days, hours, minutes, seconds, milliseconds	Fixed intervals beginning at the start timestamp; partial final intervals do not add a point.
business days	Weekdays, without a supplied holiday calendar.
weeks	Weekly points on Sundays.
months, month starts	Calendar month ends or starts.
semi months, semi month starts	The 15th and month end, or the 1st and 15th.
business month ends, business month starts	Last or first weekday of each month.
quarters, quarter starts	Calendar quarter ends or starts.
years	Calendar year ends.
business hours	The default weekday business-hour schedule, 09:00–17:00.

Each schedule is subject to the same first-generated-point removal. This wrangle does not accept a custom holiday calendar, a business-hour schedule, or an endpoint-inclusion option. Use consistent ISO date or timestamp strings; normalize missing values and timezones before running the step.

Related capabilities

Use Extract Date Properties for month, weekday, quarter, and ISO week labels; Date Calculator to add or subtract time; and Format Dates to control displayed date text.

Individual guide: html.md

HTML

When to use

Use this when you already have supplier HTML in your dataset and need its readable content or document links. A Wrangles account and the runtime's configured Wrangles authentication are required. To retrieve web content first, see Retrieve Link Content; this wrangle's input is the supplied markup.

Behavior and output

data_type: text requests readable text, while data_type: links requests link targets. The result shape depends on that choice: the documented service returns text as a string and links as a list. The default output preserves that service value rather than wrapping every result in a list.

The examples below contain synthetic HTML and illustrative expected service results. They have not been executed against the HTML service. Formatting examples show how the local recipe wrapper handles those expected results; exact parsing, text spacing, link handling, and empty responses still require controlled live verification.

Omitting output replaces the input column. For multiple independent HTML columns, supply matching input and output lists. The current runtime processes only the first selected input when several inputs share one output; combine the markup first if one call must search across columns.

Parameter choices

• Choose data_type for the information to extract, then output_format for its dataframe representation. A text extraction remains a string with the default or list format; list preserves the returned value and does not turn text into a list.
• Use output_format: concatenate and char to join a list of links. A scalar text response passes through unchanged. An empty returned list becomes an empty string.
• Multiple output names with one input imply column output and cap the number of values retained. output_format: columns with a scalar name creates numbered columns up to the largest result count. Positions missing from individual rows become empty strings.
• Column creation follows the largest result in the dataframe, with at least one column. If no row has enough results to use every supplied destination name, unused names do not create extra columns. A text response counts as one value.
• A one-element output list retains scalar-output behavior. An explicit output_format takes precedence over inference from destination names.

The Registry does not expose service-specific selector options, base-URL resolution rules, or a guarantee about malformed HTML. Validate those requirements with representative source markup before relying on them in a production recipe.

Related capabilities

Use Find Links to discover pages, Retrieve Link Content to obtain their content, Extract Regex to find a specific pattern in extracted text, and Split List to expand a stored link list.

Individual guide: properties.md

Properties

When to use

Use extract.properties when built-in colour, material, shape, and standards vocabularies are suitable for the attributes you need. A Wrangles account and property-service access are required. If you need a customer-specific vocabulary or mappings, use a saved custom extraction model instead.

Behavior and output

Omitting property_type returns a dictionary containing recognized property families, with a list of matches for each family. Selecting one family returns a list instead. No recognized match produces an empty list in typed mode; a dictionary need not contain every possible family.

first_element: true requires a selected family and returns one value, or an empty string when none exists. Leave output_format unset for that behavior: explicit formatting, including columns mode, takes precedence. The first value is the first returned match, not a confidence-based recommendation.

Parameter choices

• Use the schema spellings Colours, Materials, Shapes, and Standards in new recipes. These are the built-in families, not arbitrary output labels.
• Without a selected family, use dictionary or columns. In columns mode a scalar output expands the actual family keys; an explicit name list selects exact keys. Missing keys produce empty strings, while present keys retain their match lists.
• With a selected family, use list, concatenate, or positional columns. A scalar destination in columns mode creates numbered names; explicit output names cap retained matches and may create fewer columns when no row has enough matches.
• Prefer output_format to legacy return_data_type. Both concatenate and legacy string formatting need a selected family; they do not flatten an all-family dictionary.
• Multiple inputs with one output are searched together; matched input/output lists keep their results separate. Use where to limit extraction without removing other rows.
• A recognized standards term is text found in a description; it does not verify certification or compliance.

Related capabilities

Use extract.attributes for numeric quantities and unit conversion, extract.custom for an approved reference vocabulary, or extract.ai for contextual product attributes. Use split.dictionary to unpack grouped results in a later step.

Individual guide: regex.md

Regex

When to use

Use a known text pattern to extract flow ratings, manufacturer part numbers, or dimensions without a model or service call. Choose Extract Codes when you want the supplied code-detection rules, or Extract AI when the relevant value depends on meaning rather than a stable pattern.

Behavior and output

Matches remain in their original order. Parentheses define capture groups, but the default result still contains each complete match; output_pattern selects or rearranges groups. Numbers and other non-string inputs are converted to text, while a null input is treated as empty text.

A scalar output normally stores a list, including [] when no match is found. first_element: true instead returns one string, or '' for no match, only when output_format is omitted. Concatenation also returns '' for no match. Column output fills missing match positions with ''.

Parameter choices

• Set find to a Python regular expression; use (?i) for case-insensitive matching. Invalid patterns or group references raise an error. YAML single quotes preserve backslashes, so output_pattern: '\1 gal/min' refers to the first capture group.
• To retain every match, use a scalar output name with output_format: list. To join matches, use output_format: concatenate and char.
• For a known number of fields, supply multiple output names. These cap the number of retained matches. With output_format: columns and a scalar output name, columns are numbered from 1 and expand to the largest number of matches in the dataframe; even an all-empty result creates the first column.
• Columns are created only up to the largest result count, with at least one column. If no row has enough matches to use every supplied destination name, unused names do not create extra columns.
• A one-element output list follows the scalar-output behavior. An explicit format takes precedence over first_element and the inference from output names.
• For several independent inputs, use matching input and output lists. The current runtime processes only the first selected input when several inputs share one output; combine source text first with Merge Concatenate if one extraction should search across columns.

Related capabilities

Use Extract Brackets for bracket-delimited annotations, Replace to change matching text in place, and Split List to expand a previously extracted list.