relationship

relationship<TFieldMeta, TCollectionSlug, TComponent>(options): RelationshipField<TFieldMeta, TCollectionSlug, TComponent>

Defined in: packages/core/src/fields/relationship/config.ts:46

Creates a relationship field with all defaults applied.

Stores Convex Id references pointing to documents in another registered collection. The generated Convex schema always emits v.array(v.id("collection")) regardless of hasMany — hasMany is a UI-only hint that controls whether the admin picker allows one or multiple selections; it does not change the stored Convex type. A .index("by_<fieldKey>", ["<fieldKey>"]) is auto-generated for every relationship field — no explicit index property needed.

TCollectionSlug is inferred from options.collection. After running vex generate, passing an unregistered slug is a compile-time error.

Defaults applied:

• label — "" (inferred from field key by defineCollection)
• required — false
• hasMany — false
• admin.hidden — false
• admin.readOnly — false
• admin.position — "main"
• admin.width — "full"
• admin.cellAlignment — "left"

Type Parameters

TFieldMeta

TFieldMeta extends BaseFieldMeta = BaseFieldMeta

TCollectionSlug

TCollectionSlug extends string = string

Inferred from options.collection.

TComponent

TComponent extends ComponentHKT = ComponentHKT

Parameters

options

RelationshipFieldInput<TFieldMeta, TCollectionSlug, TComponent>

Relationship field config. collection is required.

Returns

RelationshipField<TFieldMeta, TCollectionSlug, TComponent>

Resolved relationship field definition with all defaults applied.

Example

// Single reference — stores Id<"authors">
author: relationship({ collection: { slug: "authors" } })

// Multi-reference — stores Id<"tags">[]
tags: relationship({ collection: { slug: "tags" }, hasMany: true, required: false })

See

• RelationshipFieldInput for the full input type
• RelationshipField for the resolved output type