Exclude acronyms from multisearch candidate retrieval

[jrhoads]

Purpose

Fix ror-community/ror-roadmap#345: multisearch PHRASE/COMMON/FUZZY/HEURISTICS must not retrieve organizations via acronym name values (e.g. UCLA choosing https://ror.org/03qgg3111 because its acronym is UCLA).

Approach

Single search already queries nested affiliation_match.names, populated without acronyms at index time. Multisearch incorrectly used flat names.value.norm, which includes acronyms because names is not nested in the v2 mapping.

Retarget multisearch text strategies to the same acronym-free nested field. Restore a top-level acronyms keyword field for the intentional MATCHING_TYPE_ACRONYM path (add_match_query).

Key Modifications

• rorapi/common/es_utils.py: add_phrase_query_affiliation_names, add_common_query_affiliation_names, add_fuzzy_query_affiliation_names (nested on affiliation_match.names).
• rorapi/common/matching.py: PHRASE/COMMON/FUZZY/HEURISTICS use those helpers instead of names.value.norm.
• rorapi/v2/index_template_es7.json: acronyms keyword with folding_normalizer.
• rorapi/common/index_helpers.py: populate acronyms in enrich_org_for_index.
• Tests: unit query shape + enrich; integration check that UCLA multisearch does not choose 03qgg3111.

Important Technical Details

• Reindex required after deploy: recreate index and reindex (createindex / setup or dump) so acronyms exists on all documents. affiliation_match is already populated; nested multisearch queries work once data is present. Until reindex, ACRONYM matching may not hit the new field.
• Does not nest the main names object; advanced search on names.value unchanged.
• get_score acronym boost unchanged for the ACRONYM path; wrong PHRASE candidates should no longer be retrieved via acronyms.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Reviewer, please remember our guidelines:

• Be humble in the language and feedback you give, ask don't tell.
• Consider using positive language as opposed to neutral when offering feedback. This is to avoid the negative bias that can occur with neutral language appearing negative.
• Offer suggestions on how to improve code e.g. simplification or expanding clarity.
• Ensure you give reasons for the changes you are proposing.

Test plan

• CI (test-pr / test and flow-guard pass; ruff soft-fails repo-wide with continue-on-error, unrelated)
• Unit: tests_es_utils_v2 (nested affiliation query shapes), tests_index_helpers (acronyms enrich)
• After deploy + reindex: ?affiliation=UCLA&multisearch must not return https://ror.org/03qgg3111 as chosen=True; integration test in tests_matching_v2.py when run against a current index

  

[Copilot]

Copilot review overview

🟡 Changes recommended

Acronym matching now fails when an acronym appears within a longer affiliation string.

Review effort: Balanced
Findings: 1

Open (1)

• Use extracted acronym for keyword matching · New

What changed in this PR

Retargets multisearch candidate retrieval to acronym-free affiliation names while preserving explicit acronym matching.

Changes:

• Adds nested affiliation-name query helpers.
• Restores and populates the dedicated acronym index field.
• Adds unit and integration coverage.

File	Description
rorapi/​common/​es_utils.py	Adds nested affiliation-name queries.
rorapi/​common/​matching.py	Uses the new query helpers.
rorapi/​common/​index_helpers.py	Populates indexed acronyms.
rorapi/​v2/​index_template_es7.json	Maps the acronym keyword field.
rorapi/​tests/​tests_unit/​tests_es_utils_v2.py	Tests query structures.
rorapi/​tests/​tests_unit/​tests_index_helpers.py	Tests acronym enrichment.
rorapi/​tests/​tests_integration/​tests_matching_v2.py	Covers the UCLA regression.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.