Queries

Queries are saved table operations in your workspace. You pick a type (select, insert, update, delete, archive, or aggregation), target a table, configure filters and values in the visual builder, and optionally declare inputs so callers pass validated arguments.

Use them to encapsulate table reads and writes behind a clear name — then attach the same operation as an agent tool, MCP tool, function resource, or widget resource. Queries are not raw SQL; the builder compiles your filters against table rows.

When to use

• Reuse the same table read or write from agents, functions, widgets, and workflows
• Keep filters and field mappings in one place instead of duplicating workflow table blocks
• Expose a typed tool surface with an input schema and a server-generated result schema

Prefer inline table blocks only for one-off ops that will not be reused.

Create a query

Open Build → Queries for a workspace-wide query, or open an agent’s builder and use the Queries panel for one scoped to that agent.

1. Click Create Query (or Build With AI to draft it in Studio).
2. Enter a Name, Type, Table, and optional Description.
3. Click Create — Vettero opens the query detail page.

Type and Table are fixed after create. The Result schema is generated on the server when you save — you do not edit it by hand.

Open the query builder

From the query detail page, click Edit to open the Query Builder. Use Save when the config is valid.

Anywhere a filter or field value can be set, pick a fixed value or bind an argument from the input schema.

Run a query

Open the query editor and click Run. Fill in the arguments from the input schema. Vettero saves that input on the query so the next run starts from the same values.

Run executes the saved query and shows the output. If you still have unsaved edits, Vettero saves them first. Insert, update, delete, and archive queries write real rows. Agents, functions, and widgets do not use this sample input — they pass their own arguments.

Configure by type

Select

Read rows from the table.

Returns — By Row ID or pagination One:

{ "row": { /* table fields */ }, "total": 1 }

Pagination All / Limit/Skip / Limit/Page:

{ "rows": [ { /* table fields */ } ], "total": 0 }

Insert

Add a new row.

Returns:

{ "row": { /* inserted table fields */ } }

Update

Change existing rows.

Returns:

{ "success": true, "matchedCount": 0, "modifiedCount": 0 }

Delete

Permanently remove rows.

Returns:

{ "success": true, "matchedCount": 0, "modifiedCount": 0 }

Archive

Soft-remove rows without deleting them. Configured like delete (Archive One / Archive Many in By Query mode).

Returns:

{ "success": true, "matchedCount": 0, "modifiedCount": 0 }

Aggregation

Group and summarize rows (count, sum, average, min, max).

Returns — each row has _id (group key) plus a property per operation alias:

{
  "rows": [ { "_id": null, "count": 0 } ],
  "total": 0
}

Attach to an agent

In the agent builder, open Config → Tools → Manage Tools → Table. Saved queries appear under Global (and agent-scoped queries from the builder panel). You can also attach table functions for one-off table ops.

You can also type # in the agent Task and select the query to mention and attach it.

Use from functions and widgets

Bind the query as a Query resource, then call it:

• Functions: await vt.runQuery(key, input?)
• Widgets: vt.runQuery or vt.watchQuery for live updates when related rows change

Callers pass a plain object whose keys match your input argument names.

Limits

• Target table must exist in the workspace; filter fields must be real table fields.
• Type is chosen at create time and cannot change afterward.
• Result schema is regenerated on update — do not set it manually.
• Runs consume credits and are billed by affected or returned rows.
• Delete moves the query to trash for the workspace retention period.

Where queries are used