Convert Paragraphs to a compound¶

Use this for fixed records. Keep Paragraphs for mixed component types, behavior plugins, or pieces that need their own URL, publication state or revision history. Compound values share the host's language, revision and publication state and have no paragraph ID.

Eligibility¶

The field must contain one paragraph type whose sub-fields have compatible field types and names and can take finite caps; the outer field may stay unlimited. Each host revision receives values from the paragraph revision it referenced. Unused paragraph revisions have no destination, and separate paragraph history is not preserved. Translations need a matching host language and a translatable field. Sharing, unpublished values and behavior plugins can block unattended conversion, and acknowledgment does not bypass a refusal.

Conversion rebuilds the field under its existing name across every bundle sharing its storage, and rebuilds display components. Widget settings, Views relationships and other dependent configuration need review afterwards.

Prepare and inspect¶

The example: unlimited field_sessions on Conference, allowing only Session paragraphs with single-value strings field_title and field_room, holding Opening keynote in Main hall.

drush en compound_field_paragraphs -y
drush compound-field:paragraphs-preflight node.field_sessions --strip-field-prefix --compound-id=conference_session
drush compound-field:paragraphs-convert node.field_sessions --strip-field-prefix --compound-id=conference_session --dry-run

Omit the field name from preflight to inspect every field, and add --yaml for machine-readable output. Preflight checks configuration; the dry run also checks stored values. --strip-field-prefix maps field_title to title. Keep options identical between checks and execution, and choose an unused compound ID.

Convert¶

Back up the database, export configuration, and stop content writers and cron. The field reads as empty during part of the rebuild. Choose an empty, private, writable capture directory outside the webroot and the configuration sync directory:

drush compound-field:paragraphs-convert node.field_sessions \
  --strip-field-prefix --compound-id=conference_session \
  --capture-dir=/private/backups/conference-paragraphs \
  --acknowledge -y

Option	Purpose
`--compound-id`	Unused compound ID; defaults to the field name without `field_`.
`--strip-field-prefix`	Convert `field_title` to `title`. Use consistently across checks and execution.
`--dry-run`	Check without writing.
`--acknowledge`	Accept the destructive rebuild; `-y` also answers the confirmation.
`--chunk-size`	Rows per batch.
`--capture-dir`	Export affected configuration; also works with `--status` and `--abandon`.
`--status`	Show progress and recovery information.
`--abandon --acknowledge`	Forget the conversion record after recovery; restores nothing.

Verify¶

Converted session fields.

Check Manage fields, values, order and rendering. The compound takes its label from the host field. Repair the dependent configuration the report lists. Source paragraphs remain loadable; keep them until verification is complete. Rehearse a translated or moderated site on a copy; see translation and moderation.

Recover¶

Inspect --status, fix the cause and rerun the original command; it resumes from the saved cursor. Only one process converts a field, including staging. A killed worker keeps its lease for up to ten minutes after its last progress; a rerun then discards unfinished chunk rows, and some copy stages restart. If verification fails repeatedly, restore the pre-conversion backup.

Retrieve captured configuration after an interruption:

drush compound-field:paragraphs-convert node.field_sessions --status \
  --capture-dir=/private/backups/conference-paragraphs

Adapt objects reported as deleted before restoring them, compare repaired objects with live configuration, and leave untouched objects alone. A name-only capture needs the earlier export. Captures contain old paragraph references, so never import the whole directory. --capture-dir-holds-other-config bypasses the directory checks, including for configuration sync, and risks obsolete settings on the next import.

Keep every table --status names until recovery finishes. Remaining source paragraphs do not restore host references; successful verification removes staging, and restoring host references may need the backup. After manual recovery, export the recovery information first; --abandon --acknowledge then forgets the conversion record and leaves content, configuration and recovery tables intact.

Remove old paragraphs¶

After verifying content, historical revisions and dependent configuration:

drush compound-field:paragraphs-cleanup node.field_sessions --dry-run
drush compound-field:paragraphs-cleanup node.field_sessions --acknowledge -y

Cleanup permanently deletes orphaned source paragraphs; --bundle restricts it to one paragraph type. Keep a backup.