|
| 1 | +# Welcome to your Convex functions directory! |
| 2 | + |
| 3 | +Write your Convex functions here. |
| 4 | +See https://docs.convex.dev/functions for more. |
| 5 | + |
| 6 | +A query function that takes two arguments looks like: |
| 7 | + |
| 8 | +```ts |
| 9 | +import { v } from 'convex/values' |
| 10 | +// functions.js |
| 11 | +import { query } from './_generated/server' |
| 12 | + |
| 13 | +export const myQueryFunction = query({ |
| 14 | + // Validators for arguments. |
| 15 | + args: { |
| 16 | + first: v.number(), |
| 17 | + second: v.string(), |
| 18 | + }, |
| 19 | + |
| 20 | + // Function implementation. |
| 21 | + handler: async (ctx, args) => { |
| 22 | + // Read the database as many times as you need here. |
| 23 | + // See https://docs.convex.dev/database/reading-data. |
| 24 | + const documents = await ctx.db.query('tablename').collect() |
| 25 | + |
| 26 | + // Arguments passed from the client are properties of the args object. |
| 27 | + console.log(args.first, args.second) |
| 28 | + |
| 29 | + // Write arbitrary JavaScript here: filter, aggregate, build derived data, |
| 30 | + // remove non-public properties, or create new objects. |
| 31 | + return documents |
| 32 | + }, |
| 33 | +}) |
| 34 | +``` |
| 35 | + |
| 36 | +Using this query function in a React component looks like: |
| 37 | + |
| 38 | +```ts |
| 39 | +const data = useQuery(api.functions.myQueryFunction, { |
| 40 | + first: 10, |
| 41 | + second: 'hello', |
| 42 | +}) |
| 43 | +``` |
| 44 | + |
| 45 | +A mutation function looks like: |
| 46 | + |
| 47 | +```ts |
| 48 | +import { v } from 'convex/values' |
| 49 | +// functions.js |
| 50 | +import { mutation } from './_generated/server' |
| 51 | + |
| 52 | +export const myMutationFunction = mutation({ |
| 53 | + // Validators for arguments. |
| 54 | + args: { |
| 55 | + first: v.string(), |
| 56 | + second: v.string(), |
| 57 | + }, |
| 58 | + |
| 59 | + // Function implementation. |
| 60 | + handler: async (ctx, args) => { |
| 61 | + // Insert or modify documents in the database here. |
| 62 | + // Mutations can also read from the database like queries. |
| 63 | + // See https://docs.convex.dev/database/writing-data. |
| 64 | + const message = { body: args.first, author: args.second } |
| 65 | + const id = await ctx.db.insert('messages', message) |
| 66 | + |
| 67 | + // Optionally, return a value from your mutation. |
| 68 | + return await ctx.db.get(id) |
| 69 | + }, |
| 70 | +}) |
| 71 | +``` |
| 72 | + |
| 73 | +Using this mutation function in a React component looks like: |
| 74 | + |
| 75 | +```ts |
| 76 | +const mutation = useMutation(api.functions.myMutationFunction) |
| 77 | +function handleButtonPress() { |
| 78 | + // fire and forget, the most common way to use mutations |
| 79 | + mutation({ first: 'Hello!', second: 'me' }) |
| 80 | + // OR |
| 81 | + // use the result once the mutation has completed |
| 82 | + mutation({ first: 'Hello!', second: 'me' }).then(result => |
| 83 | + console.log(result), |
| 84 | + ) |
| 85 | +} |
| 86 | +``` |
| 87 | + |
| 88 | +Use the Convex CLI to push your functions to a deployment. See everything |
| 89 | +the Convex CLI can do by running `npx convex -h` in your project root |
| 90 | +directory. To learn more, launch the docs with `npx convex docs`. |
0 commit comments