> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/manage-search-profiles.md).

# Create and Manage Search Profiles

Create a Search Profile when you know which records should answer a class of questions and what information those records contain.

## Find Settings in the Dashboard

Open **Components → AI Search**, then choose **Create Search Profile** or select an existing profile.

Profile settings and named Search Indexes are configured on the same page. Use the control map below to find each setting.

On an existing profile, the **Index** panel at the top shows indexing status and maintenance progress. The **Stored columns** summary below it shows stored projection columns.

Choose **Create profile** at the bottom to create a profile, or **Save changes** to update an existing one. **ID** and **Object type** cannot be changed after creation.

### Match Each Control to a Decision

| Section and Control                                                           | Decision                                                    | Initial Setting or Check                                                                              |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Identity → ID, Name, Description                                              | How people and clients identify the profile.                | Use a stable ID and describe what the records can answer.                                             |
| Source → Object type                                                          | Which Object Type supplies records.                         | Select the Object Type whose records contain useful evidence.                                         |
| Source → Query predicate (optional)                                           | Which records are eligible for indexing.                    | Leave empty to include all source records, or add a predicate to select a subset.                     |
| Template → Header template (optional)                                         | What context repeats in every chunk.                        | Leave empty initially; keep it short when used.                                                       |
| Template → Body template                                                      | Which record text becomes searchable.                       | Include useful facts and readable labels; inspect a real sample.                                      |
| Preview (below Template)                                                      | Whether the templates produce the intended searchable text. | Inspect the rendered header and body from one sample record.                                          |
| Chunking → Splitter, Chunk size (characters), Overlap (percent of chunk size) | How text is divided for retrieval.                          | `plain-text-window`, 1,600 characters, 10%.                                                           |
| Chunking → Strict windows (not recommended)                                   | Whether to cut at exact character positions.                | Leave unchecked to preserve boundaries.                                                               |
| Embedding → Model, Dimensions                                                 | Which vector configuration to use.                          | `voyage-4`, 1,024 dimensions.                                                                         |
| Projections                                                                   | Which typed attributes to return and filter on.             | Add only the attributes needed; preview values and types.                                             |
| Preview (below Projections)                                                   | Whether projection expressions return the expected values.  | Inspect values from one sample record.                                                                |
| Indexes → Mode, Top K                                                         | How to retrieve candidates and how many to consider.        | Hybrid, Top K 10 for the first named index.                                                           |
| Indexes → One result per document                                             | Whether to group matches from the same record.              | On initially when the task needs distinct records.                                                    |
| Indexes → Static filters                                                      | Which projected values restrict this preset.                | None initially; fields must refer to projection aliases.                                              |
| Indexes → Rerank → Enabled, Reranker, Top N, Scope                            | Whether and how to reorder candidates.                      | Disabled initially. When enabled, review the reranker, count, and scope. Top N must not exceed Top K. |

If the console cannot load the available rerank presets, enter a known preset ID in **Preset ID** instead of selecting a **Reranker**.

**Strict windows** is the inverse of the API's `preserveBoundaries` setting: unchecked means `preserveBoundaries: true`. Use the visible dashboard label when following the guide.

See [Search Concepts and Configuration](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md) for definitions, supported values, and examples.

## Choose the Source

If your source content is in PDFs, Word documents, or scans, extract their text into fields on the source records before creating the profile. AI Search does not read record attachments. Include the extracted text fields in the [body template](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md#templates).

1. Select one source Object Type.
2. Inspect representative records, including long records and records with missing optional fields.
3. Decide whether all records are eligible. If eligibility is narrower, configure the source query as a JSON object and check it against both an included and excluded record. The source query uses Native Object `$query` field paths with these operators: comparison (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`), logical (`$and`, `$or`, `$nor`, `$not`), element (`$exists`, `$type`), array (`$all`, `$elemMatch`, `$size`), `$mod`, and `$regex` with `$options`. A profile whose query uses any other operator does not save.
4. Identify the fields that contain useful evidence. Resolve whether referenced IDs need descriptive data in the source record.

Source eligibility controls indexing membership. It is separate from a named index's [static filters](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md#static-filters).

## Configure the Profile

1. Give the profile a name and stable ID. Profile IDs use lowercase letters, numbers, and hyphens, with 3–64 characters.
2. Add a required body template and, if useful, a short header. Start with **Generate from schema** or write the template yourself.
3. Inspect the template preview. Confirm whether it uses real data or placeholders.
4. Keep the initial chunking and embedding settings unless you have evidence that they need to change.
5. Add projections for result attributes and static filters you need. Check their expressions and types with actual records.
6. Choose **Add index** to configure at least one named index for a repeatable query configuration. Choose its mode, Top K, grouping, filters, and optional reranking.
7. Choose **Create profile**, then inspect the **Index** status panel at the top of the profile page.

Use [Search Concepts and Configuration](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md) for settings and examples. The control map above gives initial settings for a profile and named index; evaluate them against questions your source records should answer.

## Check Readiness

Wait for the initial build to complete and inspect any reported failures.

Run a test query through the [Native Object API](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/query-and-use-results.md#query-through-the-native-object-api). Include the profile ID and named Search Index ID, and ask a question that a known source record should answer. Check that the results include that record and relevant text. The Search Profile page does not provide a test-search interface.

Keep the profile ID and index ID with your query example so another reader can repeat it.

## Change an Existing Profile

What **Save changes** does, including whether it opens a prompt, depends on what you changed.

| Change                                                                                | What Happens on Save                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Named index settings: mode, Top K, one result per document, static filters, reranking | Saves immediately with no prompt and shows **Search profile saved**. Queries that name the index use the new settings. Stored embeddings do not change.                                                                                                                                                                                                                                                                                                                                                              |
| Projections only                                                                      | Saves with no rebuild prompt. Contextual repairs the existing index in place to update projected values and reuses the stored embeddings. Retiring, re-enabling, or removing a projection saves the same way. A type the stored column cannot hold asks you to confirm **Save and rebuild** instead. See [Add, Rename, Remove, or Retire a Projection](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md#add-rename-remove-or-retire-a-projection). |
| Source query, template, chunking, embedding model, or dimensions                      | Saves the configuration without a rebuild prompt. Inspect the **Index** panel for indexing status after saving.                                                                                                                                                                                                                                                                                                                                                                                                      |

To request a full rebuild, choose **More actions → Rebuild index**, then confirm **Rebuild**. If a rebuild is already in progress, the action is **Restart rebuild**. A rebuild creates a new generation and embeds every matching source record again. Queries use the current index until the rebuild finishes.

If saving detects a projection type conflict, choose **Cancel** to leave the profile unchanged or **Save and rebuild** to save the configuration and rebuild the index.

**Save and rebuild** for a projection type conflict builds a fresh index that declares only the active projections. The serving index keeps answering queries with its current projections until the new index takes over. Then its stored columns and values are discarded. An index that is already being built is replaced and loses its work so far. Every record is embedded again, at the cost of a full rebuild. Filters and clients that read the changed columns see the new types after cutover.

The **Stored columns** summary near the top of the profile page counts the index's columns and any type conflicts. Expand it to see the flagged columns with their stored type and configured type, or use **Show all** to include the remaining columns. A building index gets its own columns only where it differs from the serving index. When stored columns cannot be loaded, a warning replaces the summary; the next save checks the types again. Skipped records appear as one alert for the profile, with **Run repair**.

Only three statuses are flagged:

| Status   | Meaning                                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------------------------- |
| Conflict | The configured type doesn't fit the stored column. Use a new alias or rebuild.                                             |
| Retired  | Not written, returned, or filterable until re-enabled. Values already stored stay in place, and the column keeps its type. |
| Reserved | No longer in the profile. The name and type stay taken in this index until a rebuild.                                      |

Other columns carry no status. An `int` stored type next to a `number` projection accepts whole numbers only and skips a record with a fraction. A stored type of `—` means the index has no column for the projection yet. The profile form shows an existing projection's stored type, and explains `number` and `integer` by the column type a new projection creates.

The source Object Type is fixed after creation in the dashboard.

Record one or more baseline queries before saving. After processing completes, rerun those queries and compare source IDs and evidence. See [Keep Search Up to Date](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/keep-search-up-to-date.md) for repair and rebuild behavior.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/manage-search-profiles.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
