Unions

A union combines source datasets with compatible, overlapping schemas into one queryable dataset under a catalog name you choose.

A union names a set of source datasets in fromDatasets and merges their rows into a single dataset the rest of the platform can read. Members do not need identical schemas. Fields shared by the members line up in the union's output, and fields present in only some members remain in the output. Rows from a member without one of those fields receive an always-null field in its place. This preserves source-specific fields without forcing every member into an identical shape first.

The sources are other datasets in the catalog, such as tables, views, and connectors, each referenced by name and by the Space that holds it. A union has no query. A deployed union is a virtual view over its members, resolved at query time, so it holds no rows of its own and always reads what its members currently hold. It feeds detections, views, and mappers downstream. It is prefixed ION_.

Materialization

A union is virtual only. Deploying one registers a view definition over its member datasets, and every read resolves that definition against whatever the members hold at that moment. A union has no refresh loop and no rows in storage, so it cannot fall behind its sources.

Perpetual accepts maxLatency, retentionDays, startsAt, and endsAt on a union and does nothing with them. They govern materialized rows, and a union has none. Set retention and time bounds on the tables or materialized views a union reads instead.

Inputs

Field	Type	Required	Description
name	string	Required	Dataset name in schema.name format, e.g. events.okta, or a single identifier.
fromDatasets	array<object>	Required	The source datasets combined into this union. Their schemas may overlap without matching; shared fields must be compatible, and absent fields become null for that member's rows. Each entry references a dataset by resourceName and the spaceId that holds it.
deploy	boolean	Required	Whether Perpetual registers the union as a queryable view. true stands up the view over its members. false leaves it as saved content.
maxLatency	enum	Optional	No effect on a union. See Materialization.
retentionDays	integer	Optional	No effect on a union. See Materialization.
archived	boolean	Optional	Whether the union is archived. Perpetual does not register an archived union as a view. Default false.
startsAt	timestamp	Optional	No effect on a union. See Materialization.
endsAt	timestamp	Optional	No effect on a union. See Materialization.

Outputs

Field	Type	Description
materialized	boolean	Always false for a union. See Materialization.
deploymentStatus	enum	Deployment state: UNDEPLOYED, DEPLOY_PENDING, DEPLOY_IN_PROGRESS, DEPLOYED, UPDATE_PENDING, UPDATE_IN_PROGRESS, REFRESH_IN_PROGRESS, FAILED, ARCHIVED, CLEANUP_PENDING, CLEANUP_IN_PROGRESS.
lastMaterializedAt	timestamp	When the union's view definition was last created or recreated. It does not record a data refresh. Absent if the union has never deployed.
detections	array<string>	The detections that read this union.
readOnly	boolean	true when you cannot edit the union in place.
isSystemCreated	boolean	true when the platform created the union rather than a user.

Plus the common resource fields.

Related

• Tables, Views, and Connectors, the datasets a union combines.
• Data dependencies, how a union tracks the sources it reads.
• Incremental queries, the refresh machinery behind the materialized datasets a union reads.
• Changesets, how union edits are staged and committed.