findRecords
Search and filter records with structured queries, including metrics, grouping, and relationship traversal. Use for listing or answering data questions in RushDB MCP Server.
Instructions
Primary read/query/list/search tool for records. Use findRecords to find records, search records, list records, retrieve matching records, filter records, or answer questions from data. Use this instead of exportRecords unless the user explicitly asks for CSV/export/download. Search records with a structured SearchQuery. BEFORE building any query with dates, metrics, groupBy, relationship traversal, or vector search — call getSearchQuerySpec to load the complete syntax reference. INTENT: metrics/analytics request (count/total/sum/avg/breakdown/top N by metric) → MUST include select + groupBy. NEVER fetch raw records to count/sum manually. RESPONSE: { data:[...records], total:N } — for simple "how many" read total directly; no count select needed. HARD RULES: (1) NEVER set limit when select is present — restricts the record scan and produces mathematically wrong results. Omit limit for all metrics queries. (2) labels contains root records only; put related labels inside where traversal blocks with $alias when referenced. (3) groupBy never accepts alias-only values like "$record"; use "$record.name" or a select key. (4) Ambiguous/incomplete named references should use $contains on a display property confirmed via schema discovery, not exact equality. (5) Related-count rankings keep the requested parent/entity as root; count the related alias and order desc for most/more or asc for least/less/fewer.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip | |
| limit | No | Max records for listing queries (default 10, max 1000). NEVER set when select is present — restricts the scan and produces wrong results. | |
| where | No | Filter conditions. Field names must match exactly what findProperties/getSchemaMarkdown returns. Exact match can be field: value or field: { $eq: value }. For incomplete named references, prefer $contains on a display property confirmed via schema discovery instead of exact equality. For the complete operator reference (string/number/boolean/datetime/vector/$eq/$exists/$type/logical/$alias/$relation incl. multihop hops/$cycle/$id) call getSearchQuerySpec. | |
| labels | No | Filter by record labels | |
| select | No | Map of output-key → select expression. Supports: $sum, $avg, $min, $max, $count, $collect, $timeBucket, math, and references. See getSearchQuerySpec for full select/groupBy/collect/timeBucket reference. | |
| groupBy | No | Two modes: (A) Dimensional — "$alias.propertyName" strings, one row per distinct value; (B) Self-group — select key names, collapses to one row. Do not use alias-only values such as "$record" or "$related". Call getSearchQuerySpec for full reference. | |
| orderBy | No | Sorting configuration: key = field, value = asc|desc |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | ||
| total | Yes |