is there a way to set a default value to a field when defining a schema with "defineTable" ?
#default values in a schema (define table)
charred ridge
near lotusBOT
Hi @charred ridge. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Convex's standard schema definition using defineTable does not support specifying default values for fields directly in the schema. When you add a new field to your schema, the recommended approach is to make it optional (using v.optional(...)) so that existing documents without the field remain valid. You can then handle default values in your application logic when reading or writing documents, or use a migration to populate the field for existing documents.
For example, to add an optional field:
posts: defineTable({
// ... other fields
contentType: v.optional(v.union(v.literal("text"), v.literal("video")))
}),
And then provide a default in your code when reading:
return (await ctx.db.query("posts")).map((post) => ({
...post,
contentType: post.contentType ?? "text",
}));
Convex Ents: Default field values
If you want to make the field required and ensure all documents have a value, you should first add it as optional, backfill existing documents (using a migration), and then update the schema to make it required. There is no built-in way in defineTable to specify a default value that is automatically applied by Convex for new documents—this must be handled in your application or with a migration process Stateful Online Migrations using Mutations.
Exception: If you are using Convex Ents (an experimental library), it does allow you to specify default values in the schema, but this is not part of the standard Convex API.
In summary:
- Standard Convex (
defineTable): No direct support for default values in the schema. - Workaround: Use optional fields and handle defaults in your code or via migrations.
- Convex Ents: Supports default values, but this is a separate library and not standard Convex.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
charred ridge
@near lotus is that a deliberate choice not to have the ability to set a default value at the schema level ?
near lotusBOT
Let me check the knowledge base for you again. One moment! :books:
Yes, it is a deliberate choice in Convex's design not to support default values at the schema level with defineTable. The knowledge sources explain that when you evolve your schema and add new fields, the recommended approach is to make the field optional and handle default values in your application logic or through migrations. The built-in schema validation does not automatically require or set default values for new fields—you must ensure this in your code or by backfilling data yourself. This approach gives you flexibility but requires you to manage defaults outside the schema definition itself Convex Ents: Default field values.
The rationale is that Convex aims to balance ease of use and flexibility, allowing you to incrementally add rigor to your data model as your application matures, rather than enforcing strict schema constraints or behaviors like default values at the database level from the start How Convex Works: Tables and schema.
If you need default values at the schema level, Convex Ents (an experimental library) provides this feature, but it is not part of the standard Convex API.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
charred ridge
is ent supposed to become the default schema tool in the long run ? @near lotus
near lotusBOT
Let me check the knowledge base for you again. One moment! :books:
Based on the available knowledge sources, Convex Ents is not intended to become the default schema tool for Convex. Ents is currently in maintenance mode, meaning there will be no active feature development from the Convex team, though they will ensure it doesn't break and are open to community contributions. The Convex team has stated that they are considering incorporating some of the ideas and ergonomics from Ents (such as join ergonomics) into the core Convex API in the future, but Ents itself will remain a separate, optional library and not the default schema tool.