docs(config): explain how the response-field keys work together - #3490
Merged
Merged
Conversation
query.additional.api.response.fields only adds names to the allow-list the v2 search and scroll APIs filter each document through; it does not make the search engine return the field. A field therefore reaches the search API only when it is also in query.additional.response.fields, and the scroll API only when it is also in query.additional.scroll.response.fields. None of the three comments said so, and the published properties page is generated from them. Say which keys fetch a field and which one lets it through, in fess_config.properties and in the matching FessConfig javadoc. No behaviour change.
marevol
added a commit
to codelibs/fess-docs
that referenced
this pull request
Sep 24, 2026
…combine - config/properties: regenerate the descriptions of query.additional.response.fields, query.additional.api.response.fields and query.additional.scroll.response.fields from the rewritten comments in fess_config.properties (codelibs/fess#3490). The catalogues gain the new msgids and drop the old ones; like every other entry they are untranslated. - api/admin/api-admin-backup: fess.json and doc.json are not scrolled like a .bulk id. The download returns the mapping definition file itself (fess_indices/fess.json, fess_indices/fess/doc.json) as application/octet-stream. Add a row for them, replace the wrong note with one saying the API only downloads and restoring is done from the admin Backup page, and list fess.json among the ids that need a trailing slash. - config/search-scroll: /api/v2/documents/all filters every document through the API response allow-list, which does not contain content. Adding content to query.additional.scroll.response.fields only fetches it; it also has to be added to query.additional.api.response.fields.
marevol
added a commit
to codelibs/fess-docs
that referenced
this pull request
Sep 24, 2026
…duct (#553) * docs(15.9): correct eight places where the docs disagree with the product A release test found these pages describing behaviour that Fess does not have (the same text is in 15.8): - Backup API: a path whose last segment contains a dot and has no trailing slash is treated as a static file request and never reaches the action, so /api/admin/backup/file/fess_config.bulk returns 404. Say to end such ids with "/" and fix both curl examples. - Sort search: an unsupported field or order in sort: inside the query does not raise an error. The query is escaped and searched again, so it is not sorted and usually finds nothing. Only the sort request parameter returns 400. - Response fields: query.additional.api.response.fields only extends the allow-list of the search API; the field also has to be fetched through query.additional.response.fields. Explain both and show an example. - record_count_relation is EQUAL_TO or GREATER_THAN_OR_EQUAL_TO (the TotalHits relation name), not eq/gte, in the search API and the admin search list API. - The search log file is searchlog.log, not search.log. - Log rotation: the bundled log4j2.xml also deletes compressed files by age (fess.log and fess-llm.log 90 days, searchlog.log 90 days, audit.log 360 days). Document the periods and the properties that set them, and that the 10-file limit applies per date. The French page also said 10 MB instead of 100 MB. - Stopwords guide: it was copied from the mapping guide and described source/target fields. The screen has a single word field. Rewrite the overview, the field description and the download/upload format. - Stopwords guide: add a note that each stopwords file is used only by its language's analyzer. A word in en/stopwords.txt is removed from content/title but can still match through content_ja of documents detected as Japanese. All seven languages, 15.9 tree only. * docs(15.9): explain how the fetch and allow-list response-field keys combine - config/properties: regenerate the descriptions of query.additional.response.fields, query.additional.api.response.fields and query.additional.scroll.response.fields from the rewritten comments in fess_config.properties (codelibs/fess#3490). The catalogues gain the new msgids and drop the old ones; like every other entry they are untranslated. - api/admin/api-admin-backup: fess.json and doc.json are not scrolled like a .bulk id. The download returns the mapping definition file itself (fess_indices/fess.json, fess_indices/fess/doc.json) as application/octet-stream. Add a row for them, replace the wrong note with one saying the API only downloads and restoring is done from the admin Backup page, and list fess.json among the ids that need a trailing slash. - config/search-scroll: /api/v2/documents/all filters every document through the API response allow-list, which does not contain content. Adding content to query.additional.scroll.response.fields only fetches it; it also has to be added to query.additional.api.response.fields.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adding a custom field to the search API response takes two settings, but the comments in
fess_config.propertiesdescribe each key on its own:query.additional.response.fields/query.additional.scroll.response.fieldsdecide which fields are fetched from the index (QueryFieldConfig#getResponseFields/#getScrollResponseFields).query.additional.api.response.fieldsonly adds names to the allow-list that the v2 search API (SearchHandler) and scroll API (ScrollSearchHandler) filter each document through (QueryFieldConfig#isApiResponseField). It does not fetch anything.So setting only
query.additional.api.response.fields=authorreturns noauthor, and setting onlyquery.additional.scroll.response.fields=contentreturns nocontentfrom/api/v2/documents/all. The configuration reference page in fess-docs is generated from these comments, so the relationship was missing there as well.Changes
fess_config.propertiesto say which key fetches a field and which one lets it through.FessConfigby hand.No behaviour change.
The fess-docs
properties.rstpage will be regenerated from this file in codelibs/fess-docs#553.