Configure freshness-aware retrieval in Azure AI Search (preview)

Freshness-aware retrieval (preview) lets an indexed knowledge source prefer newer content during agentic retrieval. The knowledge source can include a freshness policy so Azure AI Search biases ranking toward recent documents without requiring callers to send custom ranking logic on each retrieve request.

Freshness is a ranking bias, not a hard filter. Older documents can still appear when they're strongly relevant to the query.

Usage support

Prerequisites

• An indexed knowledge source that creates and maintains an Azure AI Search index, such as a blob knowledge source.

• A knowledge base that references the knowledge source.

• Permission to update knowledge bases. Configure keyless authentication with the Search Service Contributor role assigned to your user account (recommended) or use an admin API key.

When to enable freshness-aware retrieval

Enable freshness-aware retrieval when newer content is generally more useful or trustworthy than older content. Common examples include release notes, policy updates, runbooks, service advisories, and operational guidance.

Don't use freshness as a replacement for filtering. If a query must only return content from a specific date range, use a filter in the retrieve request or knowledge source configuration instead.

Configure the freshness policy

Add a freshness policy to the indexed knowledge source definition. The preview contract uses the policy to apply a recency-aware ranking signal while preserving the rest of the retrieval pipeline.

The following example shows a blob knowledge source with a freshness policy.

var knowledgeSource = new AzureBlobKnowledgeSource(
    name: "news-articles-ks",
    azureBlobParameters: new AzureBlobKnowledgeSourceParameters(connectionString: blobConnectionString, containerName: "news")
    {
        IngestionParameters = new IngestionParameters
        {
            FreshnessPolicy = new FreshnessPolicy
            {
                BoostingDuration = TimeSpan.FromDays(90)
            }
        }
    }
)
{
    Description = "A knowledge source for recent news articles."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);

knowledge_source = AzureBlobKnowledgeSource(
    name="news-articles-ks",
    description="A knowledge source for recent news articles.",
    azure_blob_parameters=AzureBlobKnowledgeSourceParameters(
        connection_string=blob_connection_string,
        container_name="news",
        ingestion_parameters=IngestionParameters(
            freshness_policy=FreshnessPolicy(boosting_duration="P90D"),
        ),
    ),
)

index_client.create_or_update_knowledge_source(knowledge_source)

PUT {{search-endpoint}}/knowledgesources/news-articles-ks?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "news-articles-ks",
  "kind": "azureBlob",
  "description": "A knowledge source for recent news articles.",
  "azureBlobParameters": {
    "connectionString": "{{blob-connection-string}}",
    "containerName": "news",
    "ingestionParameters": {
      "freshnessPolicy": {
        "boostingDuration": "P90D"
      }
    }
  }
}

The freshness policy is part of the source ingestion parameters. The index schema is modified to support a generated freshness field that's compatible with Azure AI Search scoring profile freshness functions. The boostingDuration value uses the same ISO 8601 duration format as scoring profile freshness functions, such as P90D for 90 days. Freshness adds a recency signal to ranking, but query relevance, configured retrieval settings, semantic reranking, and other ranking signals still apply.

You can change boostingDuration on an existing knowledge source by sending another create-or-update request with the new value. The scoring profile updates in place without requiring reingestion.

You can't remove the freshness policy from an existing knowledge source. To disable freshness-aware retrieval, delete the knowledge source and create a new one without freshnessPolicy.

Validate ranking behavior

The freshness field is generated at ingestion time, so the policy applies to content that's ingested after the policy is in place. After content is ingested, run retrieve requests that can return both recent and older content. A successful configuration surfaces newer relevant documents earlier without turning retrieval into a simple date sort.

If ranking doesn't reflect freshness as expected, inspect the last_modified field in the underlying index. Missing, stale, or inconsistent date values reduce the quality of the freshness signal.

Related content

• What is a knowledge source?
• Create a knowledge base
• Query a knowledge base
• Add scoring profiles to boost search scores