Query and search

Exact queries (operators per field type), roll-ups, totals by date bucket, full-text search.

Start with: records_query, records_aggregate, records_search, search_configure.

6 operations. Discover them from an agent with agentdb_capabilities {"category": "query_search"}.

#`records_aggregate`

stable added in 0.2.0-alpha.8 read-only

Server-side totals: metrics [{op: count|sum|avg|min|max, field?, as?}] over records matching where (same format as records_query), optionally group_by up to 3 fields (date/datetime as {"field","bucket":"hour|day|week|month|year"}). Returns groups [{group, metrics}]. sum/avg need integer, boolean, number, duration, decimal or currency fields (decimal and currency are exact; currency needs one currency per group). Absent values are ignored by sum/avg/min/max and form their own null group. Like records_query it may return performance with an index recommendation; explain=true returns duration_ms and a plan summary.

MCP tool: records_aggregate
REST: POST /v1/workspaces/{ws}/aggregate scope records:read

Arguments

Argument	Type	Required	Description
`object`	`string`	yes	Object type name, e.g. contact.
`where`	`object`		object
`group_by`	`string \| object[]`		string \| object[], up to 3 items
`metrics`	`object[]`		object[], up to 10 items, default [{"op":"count"}]
`sort`	`object`		object
`limit`	`integer`		integer, 1–1000, default 100
`include_archived`	`boolean`		boolean, default false
`explain`	`boolean`		boolean
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_aggregate",
  "arguments": {
    "object": "deal",
    "where": {
      "all": [
        {
          "field": "stage",
          "op": "eq",
          "value": "open"
        }
      ]
    },
    "group_by": [
      {
        "field": "closed_on",
        "bucket": "month"
      }
    ],
    "metrics": [
      {
        "op": "count"
      },
      {
        "op": "sum",
        "field": "amount"
      }
    ]
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_aggregate",
    "arguments": {
      "object": "deal",
      "where": {
        "all": [
          {
            "field": "stage",
            "op": "eq",
            "value": "open"
          }
        ]
      },
      "group_by": [
        {
          "field": "closed_on",
          "bucket": "month"
        }
      ],
      "metrics": [
        {
          "op": "count"
        },
        {
          "op": "sum",
          "field": "amount"
        }
      ]
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/aggregate" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"object":"deal","where":{"all":[{"field":"stage","op":"eq","value":"open"}]},"group_by":[{"field":"closed_on","bucket":"month"}],"metrics":[{"op":"count"},{"op":"sum","field":"amount"}]}'

#`records_query`

stable added in 0.2.0-alpha.4 or earlier read-only

Exact typed query. where.all is an AND of {field, op, value} conditions or one-level {relationship, direction, where} conditions. Built-in fields id, created_at, updated_at are queryable. Absent values only match is_null. Results are ordered by one sort field then id; use cursor=next_cursor for the next page. Large objects: the result may include performance {index_recommended, field, reason, evidence, suggested_operation: indexes_create, suggested_arguments, can_create}; explain=true always returns performance with duration_ms and a plan summary (use it to compare before and after an index).

MCP tool: records_query
REST: POST /v1/workspaces/{ws}/query scope records:read

Arguments

Argument	Type	Required	Description
`object`	`string`	yes	Object type name, e.g. contact.
`where`	`object`		object
`sort`	`object[]`		object[], up to 1 items
`limit`	`integer`		integer, 1–200, default 50
`cursor`	`string`		string, up to 2000 characters
`include_archived`	`boolean`		boolean
`fields`	`string[]`		string[], up to 200 items
`rollups`	`object[]`		object[], up to 5 items
`explain`	`boolean`		boolean
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_query",
  "arguments": {
    "object": "deal",
    "where": {
      "all": [
        {
          "field": "stage",
          "op": "eq",
          "value": "open"
        }
      ]
    },
    "sort": [
      {
        "field": "amount",
        "order": "desc"
      }
    ],
    "limit": 20
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_query",
    "arguments": {
      "object": "deal",
      "where": {
        "all": [
          {
            "field": "stage",
            "op": "eq",
            "value": "open"
          }
        ]
      },
      "sort": [
        {
          "field": "amount",
          "order": "desc"
        }
      ],
      "limit": 20
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/query" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"object":"deal","where":{"all":[{"field":"stage","op":"eq","value":"open"}]},"sort":[{"field":"amount","order":"desc"}],"limit":20}'

#`records_search`

stable added in 1.0.0-rc.6 read-only

Full-text search over text-like fields of one object (enable once per object with search_configure). Every word must occur (match=all) or any word (match=any); the last word matches as a prefix. Ranked (BM25), with highlighted snippets, an optional exact where filter and next_cursor paging. Hidden fields are never searched.

MCP tool: records_search
REST: POST /v1/workspaces/{ws}/search scope records:read

Arguments

Argument	Type	Required	Description
`object`	`string`	yes	Object type name, e.g. contact.
`query`	`string`	yes	Words to search for. (min length 1, max length 200)
`match`	`"all" \| "any"`		string, one of: all, any, default "all"
`fields`	`string[]`		string[], up to 50 items
`where`	`object`		object
`include_archived`	`boolean`		boolean
`highlight`	`boolean`		boolean, default true
`limit`	`integer`		integer, 1–100, default 20
`cursor`	`string`		string, up to 2000 characters
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_search",
  "arguments": {
    "object": "contact",
    "query": "ada example",
    "match": "all",
    "limit": 10
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_search",
    "arguments": {
      "object": "contact",
      "query": "ada example",
      "match": "all",
      "limit": 10
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/search" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"object":"contact","query":"ada example","match":"all","limit":10}'

#`records_search_semantic`

experimental added in 1.0.0-rc.6 read-only

Semantic ranking of records by meaning (OFF by default; FEATURE_DISABLED unless the operator enabled a provider). Ranks the records an exact where filter selects; never replaces exact filters. Experimental: may change before 2.0.

Experimental: may change before 2.0. Off by default; only the local test provider exists, and ranking may change with a real one.

MCP tool: records_search_semantic
REST: POST /v1/workspaces/{ws}/search/semantic scope records:read

Arguments

Argument	Type	Required	Description
`object`	`string`	yes	Object type name, e.g. contact.
`query`	`string`	yes	Words to search for. (min length 1, max length 1000)
`where`	`object`		object
`limit`	`integer`		integer, 1–50, default 10
`include_archived`	`boolean`		boolean
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_search_semantic",
  "arguments": {
    "object": "note",
    "query": "customer asked about pricing",
    "limit": 5
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_search_semantic",
    "arguments": {
      "object": "note",
      "query": "customer asked about pricing",
      "limit": 5
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/search/semantic" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"object":"note","query":"customer asked about pricing","limit":5}'

#`search_config`

stable added in 1.0.0-rc.6 read-only

Objects with a full-text index and their indexed fields.

MCP tool: search_config
REST: GET /v1/workspaces/{ws}/search/config scope schema:read
CLI: agentdb search config

Arguments

Argument	Type	Required	Description
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "search_config",
  "arguments": {}
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "search_config",
    "arguments": {}
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/search/config" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

CLI

agentdb search config [options]

#`search_configure`

stable added in 1.0.0-rc.6 changes data

Enable (and build) or disable the full-text index of an object. Default: every text-like field (text, rich_text, email, url, phone, enum, status, multi_select, list, address). The index then stays current on every write.

MCP tool: search_configure
REST: POST /v1/workspaces/{ws}/search/configure scope schema:write
CLI: agentdb search configure

Arguments

Argument	Type	Required	Description
`object`	`string`	yes	Object type name, e.g. contact.
`enabled`	`boolean`		boolean, default true
`fields`	`string[]`		string[], up to 50 items
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "search_configure",
  "arguments": {
    "object": "contact",
    "enabled": true,
    "fields": [
      "first_name",
      "last_name",
      "email"
    ]
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "search_configure",
    "arguments": {
      "object": "contact",
      "enabled": true,
      "fields": [
        "first_name",
        "last_name",
        "email"
      ]
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/search/configure" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"object":"contact","enabled":true,"fields":["first_name","last_name","email"]}'

CLI

agentdb search configure [options] <object>

Query and search

#records_aggregate

Arguments

Example

#records_query

Arguments

Example

#records_search

Arguments

Example

#records_search_semantic

Arguments

Example

#search_config

Arguments

Example

#search_configure

Arguments

Example

#`records_aggregate`

#`records_query`

#`records_search`

#`records_search_semantic`

#`search_config`

#`search_configure`