---
cuppy_hub: salesforce
cuppy_path: reference/data360/search-indexes-and-retrievers.md
cuppy_section: docs
cuppy_doc: QN57-HGCR
cuppy_doc_uuid: 6be78c4f-573d-4bf5-85b2-864adb8419cd
cuppy_permalink: https://cuppy.io/salesforce/d/QN57-HGCR
cuppy_version: 1
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/salesforce/docs/reference/data360/search-indexes-and-retrievers
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: a8a6a4c8ee9491dea49a85639db9d4f86a06821d4ae6b3f6c0041c72a7ff4e32
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# Search indexes, retrievers and Data Libraries

## Search index

A search index chunks and embeds text from one DMO. For Case on Subject and Description, Salesforce's Trailhead shows `Case_chunk` (the text chunks) and `Case_index` (the index) objects, and about 20 minutes to **Ready**.

| Setting | Options (from Salesforce's guide) |
|---|---|
| Search type | **Vector** (semantic) or **Hybrid** (semantic + keyword). Prefer hybrid for business data: account names, SKUs and order numbers need exact keyword hits |
| Fields | The text fields to chunk. Include the fields the answer must quote |
| Chunking | Section-aware chunking; max tokens (1,200 in the guide); overlap; fields to prepend to each chunk (for example Title) |
| Embedding | Salesforce Embedding V2 Small (SFR-v2-small). Smaller chunks need a model with a smaller supported sequence length |

**Structured golden records need text.** An index embeds text fields, and a golden record is mostly IDs and numbers. The pipeline therefore writes one narrative text field per golden record, such as "Acme Corp: 14 orders, lifetime revenue 120,400, last order 2026-09-12, top products …". It builds that text from the unified DMO and the revenue insight into a custom DMO, and indexes that field (`patterns/golden-record-rag-pipeline-for-revenue.md`). The hub's reading: that's the documented index mechanism applied to structured data. Salesforce's guides index text-rich objects such as Case and web pages.

API: `GET`, `POST`, `PATCH` and `DELETE` on `/services/data/v66.0/ssot/search-index[/{name}]`, per the community plugin. Responses carry `runtimeStatus`, `searchType` and `sourceDmoDeveloperName`. Capture a working index's JSON with `GET`, and replay it.

## Retriever

An **individual retriever** queries one search index on one DMO.
- **Configure:** filters (all documents, or field filters), the number of results (20 in Salesforce's example), and the fields to return. Those are `DirectAttributes` from the DMO and `RelatedAttributes` such as the chunk.
- **Save it, then activate it.** An inactive retriever can't be used.
- Build it in Agentforce Studio (Build → Data → Retrievers). The Connect API exposes retrievers at `/ssot/machine-learning/retrievers` for reads. Creating one by API isn't publicly documented; the supported way to move it between orgs is a data kit's **AI Retriever** component (`reference/data360/automation-and-data-kits.md`).

## Ground a prompt template

Salesforce's Trailhead uses a **Knowledge Answers** template:
1. Replace its placeholder with Insert Resource → Retrievers → your retriever.
2. Set search text to `{!$Input:Query}`, output fields to the chunk, and a number of results.
3. Test in Preview with a retriever ID, and check the resolved prompt for chunks.

Calling the template from an agent is a `prompt://` action (`reference/agentforce/agent-script-actions-and-targets.md`).

## Give an agent the retriever

Salesforce's documented path for Agent Script is an **Agentforce Data Library** that wraps the retriever:

```bash
sf agent adl create --source-type retriever --retriever-id <active retriever ID> \
  --name "Revenue Golden Records" --developer-name Revenue_Golden_Records --target-org dev --json
sf agent adl get --library-id <libraryId> --target-org dev --json      # status READY, retrieverId set
```

A RETRIEVER library is ready at once, with no indexing. Then add the `knowledge:` block and the action to the agent:

```agentscript
knowledge:
    rag_feature_config_id: "ARFPC_1JDXX0000000001AAA"
    citations_enabled: True
    citations_url: ""
```

- `rag_feature_config_id` is `ARFPC_` + the library ID, **not** the retriever ID.
- Subagents call the standard `AnswerQuestionsWithKnowledge` action (`target: "standardInvocableAction://streamKnowledgeSearch"`), whose inputs default from `@knowledge.*`. The full action block, copied from Salesforce's sf-skills, is in `guides/data360/ground-a-revenue-agent.md`.
- The linter also accepts a `retriever://` action target, but its inputs aren't documented. Use the Data Library.

**Access the agent needs:**
- The Einstein Agent User must hold a Data 360 permission set or licence. sf-skills names `DataCloudUser`, `GenieUserEnhancedSecurity` or the `GenieDataPlatformStarterPsl` licence, depending on the org.
- The permission set's data space scope must include the index's data space.
- Without these, every answer is empty.

## Failures

| Symptom | Cause → fix |
|---|---|
| Index stuck before Ready | Building takes time (about 20 minutes in Salesforce's example). Poll `runtimeStatus`, and check the source DMO has rows |
| Exact names and numbers not found | A vector-only index. Use hybrid |
| Answers cite the wrong account | Chunks lack the account name. Prepend the name field to every chunk |
| `INVALID_REQUEST_STATE: retriever not active` / `retriever not found` / `retrieverId is required` (`sf agent adl create`) | Activate the retriever, check the ID (prefix `1Cx` or `0pm`, per sf-skills), and pass `--retriever-id` |
| `unresolved reference @knowledge.rag_feature_config_id` | The `knowledge:` block is missing or misplaced |
| Agent always says it has no answer (`knowledgeSummary` empty) | The agent user lacks Data 360 access or data space scope |
| `ADL_UNSUPPORTED_SOURCE_TYPE` | File operations aren't allowed on a RETRIEVER library |


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 376 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/salesforce/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->