SOLR-8240: A request that sends f with mapUniqueKeyOnly=true now fails with a 400 error

[nick-boss-tech]

🤖 AI text below 🤖 (posted on behalf of Nick Shanin)

https://issues.apache.org/jira/browse/SOLR-8240

What happens today

A request to /update/json/docs that sets mapUniqueKeyOnly=true and also sends field mappings (f) succeeds, and the names in f are dropped.

With mapUniqueKeyOnly=true, each record keeps only its uniqueKey and the srcField copy. Every other mapped value goes into the default search field (df) with no field name (pre-change code at the merge-base). A request with f=title:/title puts the title text into df and returns success. The name title never reaches the index.

What this change does

A request that sends f with mapUniqueKeyOnly=true now fails with a 400 error.

The check runs first in handleSplitMode, before any record is read (check). The error text tells the caller to send mapUniqueKeyOnly=false to map fields. This change adds one sentence to the reference guide's mapUniqueKeyOnly section (guide).

The check reads the effective value, so an inherited value counts. A params set or initParams that sets mapUniqueKeyOnly=true makes each request that sends f fail, unless the request sends mapUniqueKeyOnly=false. The techproducts sample sets it for /update/json/docs (params.json). Until SOLR-10424 removes that default, f requests to the sample fail with this error. SOLR-10424 is a dependency: this change should land after it, or with it.

Proof

JsonLoaderTest passes 33 of 33 and TestInitParams passes 8 of 8 at 78ecddf01f5c. The new tests fail on the code before this change.

• JsonLoaderTest.testFieldMappingWithMapUniqueKeyOnlyIsRejected (test) sends f=title:/title with mapUniqueKeyOnly=true. It expects a 400 whose message names mapUniqueKeyOnly.
• TestInitParams.testUpdateJsonDocsInitParamsRejectsFieldMappings (test) covers the inherited case: with mapUniqueKeyOnly=true set in initParams, a request that sends f fails with the same 400, and a request that sends mapUniqueKeyOnly=false succeeds with the fields mapped.
• On the code before this change, the test fails with "Expected exception SolrException but no exception was thrown".
• Counts at 78ecddf01f5c: JsonLoaderTest 33 of 33, TestInitParams 8 of 8. Verified 2026-10-15 at that head.

A choice to check

The request now fails, where the old code let it succeed and drop the names.

The options are:

1. Return a 400 when f and mapUniqueKeyOnly=true both apply. This is the change here. The ticket proposes this error.
2. Accept the request and report the unused f in the response or the log. Clients keep working, but the names are still dropped.

Option 1 costs a new error for clients that send both, or inherit the value. Option 2 keeps those requests working, but the mismatch stays a warning.

Was the 400 the right call?

Limits

The guide's examples and Setting JSON Defaults section are not updated here.

• The tests cover a request that sets the value itself, an inherited initParams default, and a request that overrides that default with mapUniqueKeyOnly=false.
• The "Setting JSON Defaults" section of the same reference guide page still shows mapUniqueKeyOnly as a default. A request that uses that default and sends f gets the 400. This change does not edit that section. Updating it is a planned follow-up pull request.
• The guide's f examples for the techproducts sample are not changed here. Three f=txt:/** examples now return 400, and the split=/exams examples already fail on the sample. SOLR-10424 concerns that default.

Changelog: changelog/unreleased/SOLR-8240-map-unique-key-only-f-conflict.yml

AI assistance

AI agents assisted with research, implementation, review, and drafting. Nick Shanin directed the work and takes responsibility for this contribution.