Upload field

f.upload() links a row to a file stored in a separate upload collection, by default the built-in "assets" collection. In its single form it's a typed varchar(36) foreign key holding one asset ID; the admin renders it as a file picker (upload + browse the media library), not a relation dropdown. Switch it to many-to-many or an inline array when a row needs several files. Reach for it whenever a row references uploaded bytes, a cover image, an attachment, a gallery.

Prerequisites: read Fields first, this page covers only the upload type. The f proxy, the chain-modifier model, and shared modifiers like .required() / .localized() / .label() are taught there.

What it does

• References an asset, stores a single asset ID as a varchar(36) FK to the target upload collection (default "assets"); the field data is a string.
• Targets any upload collection, to points at the collection that holds the bytes; defaults to the framework's "assets" collection.
• Renders a file picker, the field's metadata is flagged isUpload, so the admin shows an upload/browse-library control instead of a generic relation picker.
• Scales to many files, set through for a many-to-many gallery (via a junction collection), or chain .multiple() to store an inline array of asset IDs.
• Filters like a relation, a single upload uses the belongsTo operator set (eq, in, is, …); the many forms use quantifier / array operators.

Quick start

Use f.upload() inside a .fields() callback. The single optional argument is a config object; with no argument it targets "assets".

import { collection } from "#questpie/factories";

export const posts = collection("posts").fields(({ f }) => ({
  title: f.text().required(),
  coverImage: f.upload(),                          // FK to "assets", optional
  attachment: f.upload({ to: "documents" }),       // FK to a "documents" upload collection
}));

That gives posts a coverImage column typed string on read (the asset ID), nullable until you add .required(), rendered as a file picker in the admin form, and filterable with the belongsTo operators, no junction table or relation wiring written by hand.

Constructor argument

f.upload() takes a single optional config object. Every key is optional.

The single-upload field is always varchar(36), data string, schema z.string().uuid().

Variants, single, many-to-many, inline array

f.upload() has three storage shapes. Pick by how many files the row holds and how you want them stored.

Single (default)

One asset. Owns a varchar(36) FK column on this table; data is one asset ID string. Uses the belongsTo operator set.

coverImage: f.upload().required(),   // exactly one asset, NOT NULL

Many-to-many, through

Several assets, joined through a junction collection. Setting through makes the field virtual (no column on this table; the links live in the junction), with a runtime schema of z.array(z.string().uuid()), so the value you write/read back is string[]. Uses the toMany operator set.

gallery: f.upload({ through: "post_assets" }), // M2M gallery via a junction collection

Inline array, .multiple()

Several assets stored inline as a JSONB array of IDs on this row (no junction). .multiple() switches the field to a virtual JSONB column with a runtime schema of z.array(z.string().uuid()), the value you write/read back is string[]. Uses the multiple operator set.

images: f.upload().multiple(),   // string[] of asset IDs, stored inline as jsonb

Chained methods

This method is specific to upload (on top of the shared modifiers every field has). It returns a new immutable field.

attachments: f.upload({ to: "documents" }).multiple(), // inline list of document IDs

Filtering, operators

Which operators a where: { <field>: { … } } accepts depends on the variant. The operand is an asset ID string (or string[] / a related where for the many forms).

Single upload, the belongsTo operator set (belongsToOps).

// Posts whose cover image is a specific asset
const { docs } = await app.collections.posts.find({
  where: { coverImage: { eq: assetId } },
});

// Posts that have no cover image
const missing = await app.collections.posts.find({
  where: { coverImage: { isNull: true } },
});

Many-to-many (through), the toMany operator set (toManyOps): the relation quantifiers.

Inline array (.multiple()), the multiple operator set (multipleOps), querying the JSONB array.

// Posts whose inline image list includes a given asset
const { docs } = await app.collections.posts.find({
  where: { images: { contains: assetId } },
});

For the full query language, combining field filters with AND / OR / NOT, pagination, and orderBy, see Fields → filtering. Relation filters (some / none / every, is / isNot) and hydrating the linked asset with with: are covered in Relations.

When to use it

• f.upload(), any field that references an uploaded file: a cover image, an avatar, a downloadable attachment. You get a typed asset-ID FK and a file picker in the admin, instead of a free-form string.
• f.upload({ through }) / f.upload().multiple(), when a row holds several files: a gallery, a set of attachments. Choose through for a junction-backed relation, .multiple() for a simple inline list.
• For a relation to a non-upload collection (an author, a category), use f.relation() instead, same FK mechanics, but the admin renders a record picker, not an upload control.

TypeScript

An upload field contributes a string (the asset ID) to the generated row, insert, and where types. No annotation needed, after questpie generate, pull the shapes off the collection or the app types:

type Post = typeof posts.$infer.select;
//   ^? { id: string; title: string; coverImage: string | null; ... }

.required() makes the FK non-null and required on insert; without it the column is nullable and the insert field optional. See Fields → inferred types for how modifiers flow into the generated types.

Related

• Fields, the f proxy, the chain-modifier model, and the shared modifiers (.required(), .localized(), .label(), …).
• Storage adapters, where the bytes are persisted (local vs files-sdk), the resolved url, signed URLs, and visibility for the target upload collection.
• Relations, belongsTo / hasMany / manyToMany hydration and relation filters that the upload variants share.