> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/ai-in-umbraco/19.latest/add-ons/search/concepts.md). # Concepts How semantic vector search indexes and retrieves content. ## Vector Embeddings A vector embedding is a list of numbers that represents the meaning of a piece of text. Texts about similar topics produce similar vectors. By comparing vectors, you can find content that is related by meaning rather than matching keywords. Umbraco.AI.Search uses the configured embedding profile to generate vectors. Any provider that supports the embedding capability works, including OpenAI and Amazon Bedrock. ## Indexing Pipeline The search add-on registers an index called `UmbAI_Search` with the CMS Search framework. The index receives the same content change notifications as other indexes such as Examine. When content is published: 1. **Text extraction** - The CMS Search property value handlers extract text from all fields, including nested block content. 2. **HTML stripping** - Tags and entities are removed, whitespace is normalized. 3. **Chunking** - Long text is split into smaller chunks that fit within the embedding model's token limit. 4. **Embedding** - Each chunk is sent to the embedding provider to generate a vector. 5. **Storage** - Vectors are stored in the database with the document ID, culture, and chunk index. ### Culture-Aware Indexing For multilingual content, the indexer generates separate embeddings per culture. Each language variant has its own set of chunks and vectors. Searches can filter by culture to return results in a specific language. ### Text Chunking The recursive text chunker splits content by trying paragraph boundaries first, then sentences, then words. Text chunking preserves semantic coherence within each chunk. Overlap between chunks ensures that concepts spanning a boundary are captured in both chunks. Configure chunk size and overlap in `appsettings.json` under `Umbraco:AI:Search`. ## Search Searches work by embedding the query text and finding stored vectors with the highest cosine similarity. Multiple chunks from the same document are deduplicated, keeping the best score. ### CMS Search API The index is available through the standard CMS Search API. Send a POST request to the search endpoint with the `UmbAI_Search` index alias: {% code title="Search API request" %} ```json { "indexAlias": "UmbAI_Search", "query": "sustainability initiatives", "culture": "en-US" } ``` {% endcode %} ### Agent Tool When the Agent add-on is installed, the `semantic_search` tool is available in chat. It supports two modes: * **Text query** - Find content about a topic. * **Document ID** - Find content similar to an existing page. The document mode retrieves stored embeddings directly, so there is no extra embedding call. ## Access Control ### CMS Search API Protected content (pages with member login restrictions) is filtered based on the `AccessContext` passed in the search request. Public content is always returned. Protected content is only returned when the caller's principal or group IDs match the allowed access IDs stored during indexing. ### Agent Tool The `semantic_search` agent tool needs an acting backoffice user. In the backoffice, the acting user is the signed-in user. In an Umbraco Automate workflow, the acting user is the workspace service account. Without an acting user, the tool returns no results. Each result is checked against the acting user's access before it's returned. A result is only returned when the user could see it in their own backoffice tree: * The user needs access to a backoffice section that shows a tree, such as Content or Media. * A content result must be under one of the user's content start nodes, with Browse permission. Ancestors of a start node are also returned, as the content tree shows them. * A media result must be under one of the user's media start nodes. If a result can't be resolved to check access, it's excluded. ## Database Providers ### SQL Server On SQL Server 2025 and Azure SQL, the store uses `VECTOR_DISTANCE()` for server-side similarity search. On older versions, vectors are loaded into memory and compared using cosine similarity in .NET. Vectors are persisted as JSON arrays in an `nvarchar(max)` column for compatibility across all SQL Server versions. On SQL Server 2025, the column value is cast to the native `vector(N)` type at query time. {% hint style="info" %} The SQL Server `vector` type supports a maximum of 1998 dimensions. If the configured embedding model produces more than 1998 dimensions, the store falls back to brute-force cosine similarity in .NET even on SQL Server 2025. To keep native `VECTOR_DISTANCE()` enabled, choose an embedding model within this limit (for example, `text-embedding-3-small` at 1536 dimensions) or reduce the dimensions on a larger model. {% endhint %} ### SQLite SQLite uses in-memory cosine similarity. This is suitable for local development and testing but not recommended for production workloads. ## Custom Vector Store You can replace the built-in store by implementing `IAIVectorStore` and registering it in a Composer. See [Custom vector store](/ai-in-umbraco/19.latest/add-ons/search/custom-vector-store.md) for details. --- # 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.umbraco.com/ai-in-umbraco/19.latest/add-ons/search/concepts.md?ask=&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.