Convex

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

ParameterTypeRequiredDescription
deploymentUrlstringYesConvex deployment URL (e.g., https://your-deployment.convex.cloud\)
deployKeystringYesConvex deploy key from the dashboard Settings page
functionPathstringYesPath to the query function (e.g., messages:list or folder/file:myQuery)
argsjsonNoNamed arguments to pass to the function as a JSON object

Output

ParameterTypeDescription
valuejsonResult returned by the query function
logLinesarrayLog lines printed during the function execution

convex_mutation

Run a Convex mutation function to write data and return its result

Input

ParameterTypeRequiredDescription
deploymentUrlstringYesConvex deployment URL (e.g., https://your-deployment.convex.cloud\)
deployKeystringYesConvex deploy key from the dashboard Settings page
functionPathstringYesPath to the mutation function (e.g., messages:send or folder/file:myMutation)
argsjsonNoNamed arguments to pass to the function as a JSON object

Output

ParameterTypeDescription
valuejsonResult returned by the mutation function
logLinesarrayLog lines printed during the function execution

convex_action

Run a Convex action function and return its result

Input

ParameterTypeRequiredDescription
deploymentUrlstringYesConvex deployment URL (e.g., https://your-deployment.convex.cloud\)
deployKeystringYesConvex deploy key from the dashboard Settings page
functionPathstringYesPath to the action function (e.g., emails:send or folder/file:myAction)
argsjsonNoNamed arguments to pass to the function as a JSON object

Output

ParameterTypeDescription
valuejsonResult returned by the action function
logLinesarrayLog lines printed during the function execution

convex_run_function

Run any Convex function (query, mutation, or action) by path without specifying its type

Input

ParameterTypeRequiredDescription
deploymentUrlstringYesConvex deployment URL (e.g., https://your-deployment.convex.cloud\)
deployKeystringYesConvex deploy key from the dashboard Settings page
functionPathstringYesPath to the function (e.g., messages:list or folder/file:myFunction)
argsjsonNoNamed arguments to pass to the function as a JSON object

Output

ParameterTypeDescription
valuejsonResult returned by the function
logLinesarrayLog 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

ParameterTypeRequiredDescription
deploymentUrlstringYesConvex deployment URL (e.g., https://your-deployment.convex.cloud\)
deployKeystringYesConvex deploy key from the dashboard Settings page

Output

ParameterTypeDescription
tablesarrayNames of the tables in the deployment
schemasjsonMap 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

ParameterTypeRequiredDescription
deploymentUrlstringYesConvex deployment URL (e.g., https://your-deployment.convex.cloud\)
deployKeystringYesConvex deploy key from the dashboard Settings page
tableNamestringNoTable to list documents from. Omit to list documents from all tables.
snapshotstringNoSnapshot timestamp from a previous page. Omit on the first request to start a new snapshot.
pageCursorstringNoPage cursor from a previous page of the same snapshot. Omit on the first request.

Output

ParameterTypeDescription
documentsarrayDocuments in this page of the snapshot
hasMorebooleanWhether more pages remain in the snapshot
snapshotstringSnapshot timestamp to pass back in when fetching the next page
pageCursorstringPage 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

ParameterTypeRequiredDescription
deploymentUrlstringYesConvex deployment URL (e.g., https://your-deployment.convex.cloud\)
deployKeystringYesConvex deploy key from the dashboard Settings page
cursorstringYesTimestamp cursor to read deltas after. Use the snapshot value from List Documents or the cursor from a previous Document Deltas page.
tableNamestringNoTable to read deltas from. Omit to read deltas from all tables.

Output

ParameterTypeDescription
documentsarrayChanged documents, each including _table and _ts fields
hasMorebooleanWhether more delta pages remain
cursorstringCursor to pass back in when fetching the next page of deltas

On this page