moreLikeThis in Foundry IQ (Azure AI Search)

Note

Foundry IQ (Azure AI Search) provides direct indexing and query APIs alongside higher-level knowledge source and knowledge base APIs for managed retrieval. Use the Azure portal, REST APIs, or Azure SDKs to configure these capabilities, or connect agents to knowledge bases in the Microsoft Foundry portal.

Use the moreLikeThis parameter in the Search Documents API to find documents similar to a document already in your index. The parameter is generally available in REST API version 2026-10-01. Foundry IQ (Azure AI Search) derives query terms from the source document's searchable fields and excludes that document from the results.

Examples

These examples use the four-document index from Create an index with permission filter fields and its indexing workflow. Complete that setup first.

Replace <SEARCH_SERVICE_ENDPOINT> with your endpoint and <SEARCH_ACCESS_TOKEN> with a caller token authorized to query the index. Replace <USER_ACCESS_TOKEN> with the raw delegated user token for the <USER_OBJECT_ID> used in the upload.

Simple query

Omit search when you use moreLikeThis. Any nonnull search text, including "search": "*", conflicts with moreLikeThis and causes a request error.

The following POST request uses source document key 21 and the top-level searchable content field:

POST <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')/docs/search.post.search?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
x-ms-query-source-authorization: <USER_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json

{
  "moreLikeThis": "21",
  "searchFields": "content",
  "select": "id,content",
  "top": 4,
  "count": true
}

Reference: Search Documents (POST).

Troubleshoot empty similarity results

Similarity doesn't guarantee a nonempty result. If no document with the specified key exists, the request returns 200 OK with an empty value array.

If this positive query is empty, use the query example to check that source document 21 and candidate 101 are searchable and readable with the same credentials.

Even when both documents are readable, a small corpus might not meet the similarity query's term-frequency requirements. Document distribution can affect whether those requirements are met.

Apply filters

Combine moreLikeThis with a filter to restrict candidate results. This request selects gardening documents, excluding the astronomy candidate from the positive query:

POST <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')/docs/search.post.search?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
x-ms-query-source-authorization: <USER_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json

{
  "moreLikeThis": "21",
  "searchFields": "content",
  "select": "id,content",
  "top": 4,
  "count": true,
  "filter": "category eq 'gardening'"
}

Reference: Search Documents (POST).

Select fields and limit results

Use top to limit the number of results and select to choose returned fields. Use the comma-separated searchFields parameter to select searchable fields. If you omit it, normal searchable-field resolution applies. Because moreLikeThis doesn't support complex subfields, explicitly select suitable top-level searchable fields when your index contains complex fields.

The examples request at most four results and return id and content. The results still exclude the source document.

Native document permissions

On an index with native permission filtering enabled, moreLikeThis checks the source document's permissions before using its content. It also filters candidate documents independently through the index's ACL and RBAC scope permissions.

For permission-filtered queries, pass the delegated user's token in x-ms-query-source-authorization. The header requires an index with permission filtering enabled. For supported permission flows, see Query-time token roles and permission flows. The example uses direct user grants for the source and candidate documents.

Purview and agentic queries aren't supported with moreLikeThis.

Next steps