well_query_records

Tool of Well

Query records from Well's database. ⚠️ WORKFLOW: 1. Call well_get_schema(root) FIRST to discover available fields 2. Select ONLY the fields you need (5-15 typically) 3. Call well_query_records with those specific fields ROOTS (read-only — all 32): companies, people, connectors, invoices, documents, transactions, accounts, payment_means, workspace_connectors, memberships, cards, checks, ledger_accounts, journals, journal_entries, tax_rates, exchange_rates, invoice_transactions, categories, account_balances, tasks, workspaces, invoice_payment_means, chat_conversations, blueprint_runs, workspace_connector_sync_logs, media, emails, phones, web_links, locations, invoice_items (The accounting graph — ledger_accounts, journals, journal_entries — and balances/rates are read-only projections owned by the sync/posting pipelines; query them for financial context, you cannot create/update them here. Sub-resources like emails/phones/locations are usually richer when read via their parent company/person.) INSTALLED CONNECTORS: to see which tools/providers the workspace has connected and their connection status, query root "workspace_connectors" (fields: ["workspace_connectors","status"], ["workspace_connectors","connector","name"], ["workspace_connectors","connector","slug"], ["workspace_connectors","installed_capabilities"]). "connectors" is the installable catalog; "workspace_connector_sync_logs" is per-sync history. The installed_capabilities.available_tools list names the actions a connected provider exposes (run one with well_invoke_connector_tool). EXAMPLE - Get all invoices for dashboard: well_query_records({ root: "invoices", fields: [ ["invoices", "invoice_number"], ["invoices", "grand_total"], ["invoices", "issue_date"], ["invoices", "issuer", "name"], ["invoices", "receiver", "name"] ], limit: 50 }) ⚠️ RULES: - ALWAYS select specific fields (not allFields) for best performance - Field paths from schema: "invoices.issuer.name" → ["invoices", "issuer", "name"] - Default 50 records per request, max 500. Use cursor pagination for more. PAGINATION (cursor-based): - First call: omit cursor. Response includes nextCursor. - Next page: pass the returned nextCursor as cursor. - Last page: nextCursor is null. Example: Page 1: well_query_records({ root: "invoices", fields: [...], limit: 50 }) → { rows: [...], nextCursor: "eyJpZCI6MTAwfQ==" } Page 2: well_query_records({ root: "invoices", fields: [...], limit: 50, cursor: "eyJpZCI6MTAwfQ==" }) → { rows: [...], nextCursor: null } // last page FILTERING (whereClause): - Uses Hasura-style operators on field names. - Safe operators (work on ALL field types): _eq, _neq, _in, _nin, _is_null - Numeric/date only: _gt, _gte, _lt, _lte - Text only: _like, _ilike - When unsure of a field's type, prefer _eq or _in (they always work). - Combine with _and, _or, _not - For relationship fields, use nested syntax: { "issuer": { "name": { "_ilike": "%acme%" } } } Examples: { "status": { "_eq": "unpaid" } } { "grand_total": { "_gt": 1000 } } { "local_currency": { "_eq": "EUR" } } { "_and": [{ "status": { "_eq": "unpaid" } }, { "grand_total": { "_gte": 500 } }] } { "issuer": { "name": { "_ilike": "%acme%" } } } SORTING (orderBy): - Sort by any field: { field: "grand_total", direction: "desc" } - Default sort is by primary key ascending. Returns { rows, totalCount, nextCursor, success }.