Convex é uma plataforma de backend reativo open-source que combina um banco de dados de documentos, funções serverless e sincronização em tempo real em um pacote amigável para desenvolvedores. Em vez de escrever SQL, você define queries, mutations e actions em TypeScript que rodam junto aos seus dados, e todo cliente inscrito em uma query é atualizado automaticamente quando os dados subjacentes mudam.
Por que Convex?
- Funções como a API: Queries (leituras), mutations (escritas transacionais) e actions (efeitos colaterais como chamar APIs externas) são os blocos de construção do seu backend — tipados, versionados e implantados juntos.
- Reativo por padrão: Os resultados das queries atualizam ao vivo conforme os dados mudam, sem invalidação de cache ou lógica de polling para manter.
- Escritas transacionais: Mutations rodam como transações ACID com isolamento serializável, então seus dados permanecem consistentes sem locking manual.
- Consciência de schema integrada: O Convex rastreia o formato de cada tabela, para que as ferramentas possam introspectar seu modelo de dados sem um sistema de migração separado.
Usando Convex no Zoen
A integração Convex do Zoen conecta seus fluxos de trabalho a qualquer deployment Convex com dois campos: a URL do deployment e uma deploy key da página Settings do dashboard. A partir daí você pode:
- Executar funções: Chamar funções de query, mutation e action com argumentos JSON nomeados — ou usar Run Function quando não quiser especificar o tipo da função.
- Inspecionar seu modelo de dados: List Tables retorna cada tabela no deployment com o schema JSON dos seus documentos.
- Exportar e sincronizar dados: List Documents pagina um snapshot consistente de uma tabela, e Document Deltas retorna apenas os documentos que mudaram desde um snapshot — incluindo exclusões — tornando syncs incrementais para warehouses, índices de busca ou outras ferramentas diretos.
As operações Run Query, Run Mutation, Run Action e Run Function funcionam em todo plano Convex. List Tables, List Documents e Document Deltas usam a API de streaming export do Convex, disponível nos planos pagos do Convex.
Padrões típicos incluem agentes que leem e escrevem dados da aplicação por meio das suas funções Convex existentes, exports agendados para destinos de analytics e automações orientadas a mudanças que reagem a documentos novos ou atualizados.
Usage Instructions
Integrate Convex into the workflow. Run query, mutation, and action functions on your deployment, list tables with their schemas, and export documents with snapshot pagination and change deltas.
Actions
convex_query
Run a Convex query function and return its result
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
deploymentUrl | string | Yes | Convex deployment URL (e.g., https://your-deployment.convex.cloud\) |
deployKey | string | Yes | Convex deploy key from the dashboard Settings page |
functionPath | string | Yes | Path to the query function (e.g., messages:list or folder/file:myQuery) |
args | json | No | Named arguments to pass to the function as a JSON object |
Output
| Parameter | Type | Description |
|---|---|---|
value | json | Result returned by the query function |
logLines | array | Log lines printed during the function execution |
convex_mutation
Run a Convex mutation function to write data and return its result
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
deploymentUrl | string | Yes | Convex deployment URL (e.g., https://your-deployment.convex.cloud\) |
deployKey | string | Yes | Convex deploy key from the dashboard Settings page |
functionPath | string | Yes | Path to the mutation function (e.g., messages:send or folder/file:myMutation) |
args | json | No | Named arguments to pass to the function as a JSON object |
Output
| Parameter | Type | Description |
|---|---|---|
value | json | Result returned by the mutation function |
logLines | array | Log lines printed during the function execution |
convex_action
Run a Convex action function and return its result
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
deploymentUrl | string | Yes | Convex deployment URL (e.g., https://your-deployment.convex.cloud\) |
deployKey | string | Yes | Convex deploy key from the dashboard Settings page |
functionPath | string | Yes | Path to the action function (e.g., emails:send or folder/file:myAction) |
args | json | No | Named arguments to pass to the function as a JSON object |
Output
| Parameter | Type | Description |
|---|---|---|
value | json | Result returned by the action function |
logLines | array | Log lines printed during the function execution |
convex_run_function
Run any Convex function (query, mutation, or action) by path without specifying its type
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
deploymentUrl | string | Yes | Convex deployment URL (e.g., https://your-deployment.convex.cloud\) |
deployKey | string | Yes | Convex deploy key from the dashboard Settings page |
functionPath | string | Yes | Path to the function (e.g., messages:list or folder/file:myFunction) |
args | json | No | Named arguments to pass to the function as a JSON object |
Output
| Parameter | Type | Description |
|---|---|---|
value | json | Result returned by the function |
logLines | array | Log lines printed during the function execution |
convex_list_tables
List all tables in a Convex deployment along with their JSON schemas. Requires streaming export, available on Convex paid plans.
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
deploymentUrl | string | Yes | Convex deployment URL (e.g., https://your-deployment.convex.cloud\) |
deployKey | string | Yes | Convex deploy key from the dashboard Settings page |
Output
| Parameter | Type | Description |
|---|---|---|
tables | array | Names of the tables in the deployment |
schemas | json | Map of table name to the JSON schema of its documents |
convex_list_documents
List documents from a Convex table via a paginated snapshot. Pass the returned snapshot and page cursor back in to fetch the next page. Requires streaming export, available on Convex paid plans.
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
deploymentUrl | string | Yes | Convex deployment URL (e.g., https://your-deployment.convex.cloud\) |
deployKey | string | Yes | Convex deploy key from the dashboard Settings page |
tableName | string | No | Table to list documents from. Omit to list documents from all tables. |
snapshot | string | No | Snapshot timestamp from a previous page. Omit on the first request to start a new snapshot. |
pageCursor | string | No | Page cursor from a previous page of the same snapshot. Omit on the first request. |
Output
| Parameter | Type | Description |
|---|---|---|
documents | array | Documents in this page of the snapshot |
hasMore | boolean | Whether more pages remain in the snapshot |
snapshot | string | Snapshot timestamp to pass back in when fetching the next page |
pageCursor | string | Page cursor to pass back in when fetching the next page |
convex_document_deltas
List documents that changed after a snapshot or previous delta cursor. Deleted documents are returned with a _deleted flag. Requires streaming export, available on Convex paid plans.
Input
| Parameter | Type | Required | Description |
|---|---|---|---|
deploymentUrl | string | Yes | Convex deployment URL (e.g., https://your-deployment.convex.cloud\) |
deployKey | string | Yes | Convex deploy key from the dashboard Settings page |
cursor | string | Yes | Timestamp cursor to read deltas after. Use the snapshot value from List Documents or the cursor from a previous Document Deltas page. |
tableName | string | No | Table to read deltas from. Omit to read deltas from all tables. |
Output
| Parameter | Type | Description |
|---|---|---|
documents | array | Changed documents, each including _table and _ts fields |
hasMore | boolean | Whether more delta pages remain |
cursor | string | Cursor to pass back in when fetching the next page of deltas |