Back
Relational Data
Represent & navigate relationships between db tables
The vast majority of apps need some kind of relational data model, connecting the dots between different entities represented as documents in a different db tables. In Convex, relational data can easily be modeled by means of document IDs, which enable references between documents stored anywhere in Convex, regardless of whether those relationships are 1:1, 1:many, or many:many. When it comes time to traverse those relationships while querying data, in Convex you just write code, instead of JOIN statements. Open-source helper functions written by the Convex team make it even easier to quickly define & navigate relational data with Convex.Resources
💡BLOG
Walkthrough: Modeling data relationships in Convex schemas
stack.convex.dev/relationship-structures-let-s-talk-about-schemas
💡BLOG
Walkthrough: Helper functions for traversing data relationships
stack.convex.dev/functional-relationships-helpers
🚀DEMO
Sample code demonstrating relational data in Convex
github.com/convex/convex-demos/tree/main/relational-data-modeling
💻CODE
Import relationship helper functions from 'convex-helpers'
www.npmjs.com/package/convex-helpers#relationship-helpers
💡BLOG
Read up on how & why Convex differs from traditional relational DBs
stack.convex.dev/convex-vs-relational-databases
📄DOCS
Learn how to use document IDs to link data across Convex tables
docs.convex.dev/database/document-ids#references-and-relationships
🎞️VIDEO
Watch a short about why & how to model data relationships
www.youtube.com/shorts/ALW6_y79HU0
Build a production app this afternoon
Scale it for decades.
Set up Convex with your agentWorks great with any model, any agent, any editor
Set up Convex with your agent:
# Convex setup
Set up Convex in the current folder. Run the commands yourself, without asking the user.
- Empty folder: `npm create convex@latest . -- -t bare`
- Convex project (`convex` in `package.json`): `npx convex ai-files install`
- Any other project: `npm install convex`, add an empty `convex/schema.ts` and a `convex dev` script, then `npx convex ai-files install`. Never `npm create convex` here, it replaces the folder.
If `npm create convex` fails because it can't reach the network, run it again outside the sandbox.
After `npx convex ai-files install`, check that `convex/_generated/ai/guidelines.md` and `.agents/skills` exist. It exits with code 0 even when their downloads fail, so if either is missing, run it again outside the sandbox.
Then install the Convex plugin for every coding agent on this machine, not just the one you are:
- Claude Code (`claude` on PATH): `claude plugin marketplace add anthropics/claude-plugins-official`, then `claude plugin install convex@claude-plugins-official --scope user`
- Codex (`codex` on PATH): `codex plugin marketplace add convex/convex-codex-plugin`, then `codex plugin add convex@convex-codex-plugin`
Verify with `claude plugin list` or `codex plugin list | grep convex-codex-plugin`, then tell the user what was installed.Start a new Convex project
Build anything with Convex
Build a multiplayer YouTube appStart a new Convex project: npm create convex@latest
