Records search integration

Outcome

When you finish this guide, clients in your integration can call the records search capability with the record:search permission, correct request shape, and attribute-based access filters — without bypassing datasource exposure rules.

Records search retrieves authorized entity records (identifiers or metadata) from synchronized Business Entities. It does not return a predefined business picture across entities. For certified, decision-shaped perspectives (measures, dimensions, and grain), publish a viewpoint.

Prerequisites

Certified datasources with dimensions and exposed.filterable fields declared
Caller identity granted record:search permission
Records search and AI context understood (intents, policy-first flow)
Viewpoints and joined business context understood when callers need a business picture rather than entity lists
Metadata schema discovery completed for filterable field names in scope

Where it lives

Surface	Access
Records search service	Platform REST capability (same logic on Enterprise MCP where exposed)
Permission	`record:search` on caller token or role
Policy inputs	Dimension bindings on datasource manifests and protection projection
Audit	Search responses include audit reference and exclusion counts

The service does not call vendor APIs directly. It filters synchronized platform records under the caller’s permissions and business-dimension scope.

Multiple datasourceKeys: the platform runs one search per Business Entity and returns each entity’s authorized rows (or IDs). Dimension keys align scope across entities; they do not combine those entities into one joined result shape. Agents that only retrieve those lists receive governed data, but not the business-shaped context needed for decisions — use a viewpoint for that.

How to set

Grant permission — map record:search to integrator, worker, or agent roles that may run cross-datasource discovery. Follow your RBAC manifest pattern; do not grant at user activation time.
Declare filterable fields on each datasource in scope — records search honors normalized names from exposed.filterable and dimension bindings.
Choose intent per request: retrieval, grounding, analytics, or validation.
Compose request body (business terms — no raw route strings in integrator docs):

Field	Required	Purpose
intent	Yes	Why the search runs
resourceTypes	No	Limit to catalog types (`customer`, `document`, …)
datasourceKeys	No	Limit to specific datasources (one search each)
filters	No	Field predicates after policy (`field` → operator → value)
preFilters	No	Predicates applied before policy (advanced MCP flows)
exclude	No	Exclusion predicates
searchMode	No	`ids` (default) or `full` metadata
limit	No	Cap results (platform maximum applies)
dryRun	No	Return metadata without executing search

Filter operators — use structured operators per field: equals, not equals, comparisons, contains, in-list, not-in-list.
Prefer ids mode for RAG — retrieve authorized record IDs, then pass IDs to vector retrieval. Use full mode when UI or agents need complete metadata in one step.
Monitor exclusions — response metadata includes counts removed by policy versus user filters. High policy exclusions usually mean grants or dimension bindings — not bad filters.
Audit — retain audit references for compliance correlation.
Choose viewpoint when the answer is a business picture — revenue by customer, pipeline by stage, actual cost by cost centre, and similar cuts belong on a certified viewpoint read capability, not on multi-datasource records search. How-to: Build a viewpoint entity.

Defaults and examples

Minimal retrieval request (conceptual shape)

{
  "intent": "retrieval",
  "resourceTypes": ["customer"],
  "datasourceKeys": ["example-crm-customers"],
  "filters": {
    "country": { "eq": "Finland" }
  },
  "searchMode": "ids",
  "limit": 100
}

Multi-datasource retrieval (separate entity lists)

{
  "intent": "retrieval",
  "resourceTypes": ["document", "customer"],
  "filters": {
    "country": { "eq": "Finland" }
  },
  "searchMode": "full",
  "limit": 50
}

This returns authorized customer records and authorized document records in scope — not a single joined customer–document projection. For a predefined business picture over related entities, use a viewpoint.

Response highlights

Area	Content
data	Record IDs or full records depending on searchMode
meta.excluded	Counts filtered by policy vs user filters
meta.auditRef	Audit log correlation token

Validate

Run search with dryRun when available to confirm filter shape without returning rows.
Compare exclusion counts for a scoped subject vs over-privileged subject — policy should reduce results.
Confirm unauthorized callers receive permission errors without record:search.
For RAG pipelines, verify vector steps receive only IDs from search — never unscoped corpus queries.
Confirm callers that need measures, grain, and totals use a certified viewpoint — not records search alone.

Common mistakes

Mistake	Fix
Flat filter values without operators	Use `{"field": {"eq": "value"}}` shape
Guessing filter field names	Discover via metadata schema first
Skipping policy review	Inspect exclusion counts in the response
Full corpus vector search	Narrow with records search ids mode first
Missing permission	Add `record:search` to role
Expecting multi-datasource search to return a joined or report-shaped answer	Publish a viewpoint for the certified business perspective
Treating records search as a prerequisite gate for viewpoints	Viewpoints run under Operational Trust on their own read capability
Assuming search loads the whole table then filters	Filters and grants run in SQL before the page LIMIT
Expecting a partial page when policy cannot scale in SQL	Fail closed — fix filters/dimensions or use a supported policy shape

Limits

Records search evaluates supported filters and dimension grants in SQL before LIMIT. Omit limit only when you accept the platform default; deployments enforce a hard maximum and reject unbounded requests. Policy that cannot be expressed safely for scalable search fails closed — do not expect a partial unauthorized page.

ids / searchMode ids is key-constrained: only the identifiers you pass are in scope.

Result-page defaults, hard caps, preFilter semantics, and MCP tool naming may differ slightly by deployment. Confirm maximum limit and dry-run support with your operator.

Records search applies platform policy on synchronized records — it does not fix missing dimension bindings on datasources, and it does not define business measures or grain. Complete dimension and protection configuration before relying on search for production AI context. Own decision-shaped cuts as viewpoints on the Connected System.

Documentation Index