Motivation
The four SQL fulltext search functions break two conventions:
- Naming. They use snake_case (
search_fields, search_fields_more, search_index, search_index_more) while every other SQL function in the codebase uses either namespace.name (vector.neighbors, graph.astar, ts.timeBucket) or camelCase (shortestPath, dijkstra). They are the only snake_case island in the registry.
- Options.
search_fields_more and search_index_more accept a trailing options blob, but deliver it as an opaque object that is parsed via new JSONObject(value.toString()) then fed to MoreLikeThisConfig.fromJSON. Unknown keys are silently dropped, typos slip through, and the accepted keys are not discoverable from the function signature.
This is a natural moment to bundle both: adopt the options-map pattern introduced with #3879 and add namespaced aliases so the codebase converges on one naming convention.
Proposal
Namespace aliases (backward compatible)
| Legacy (kept) |
New canonical name |
search_fields |
fulltext.searchFields |
search_fields_more |
fulltext.searchFieldsMore |
search_index |
fulltext.searchIndex |
search_index_more |
fulltext.searchIndexMore |
Both names dispatch to the same function instance via the existing getAlias() mechanism. The snake_case names stay registered indefinitely.
Options map
Replace the current opaque metadata argument on *_more with a named options map validated by com.arcadedb.function.sql.FunctionOptions. Accepted keys correspond one-to-one with MoreLikeThisConfig:
SELECT FROM Article
WHERE fulltext.searchFieldsMore(
['title', 'body'],
[#1:0],
{ minTermFreq: 1, minDocFreq: 1, maxQueryTerms: 25,
boostByScore: true, excludeSource: true, maxSourceDocs: 5 }
)
Unknown keys throw a descriptive error. Any existing call site that still passes a JSON string keeps working.
Non-goals
- Not adding new options (
limit, minScore, etc.) to searchFields / searchIndex in this issue. They get aliases only. Growing their options is a separate conversation.
- No grammar changes.
- No behavior changes aside from stricter validation of unknown keys in
*_more.
Deliverables
- Promote the 4 functions to
fulltext.* canonical names, keep the legacy names as aliases.
- Switch
SQLFunctionSearchFieldsMore / SQLFunctionSearchIndexMore to FunctionOptions when the trailing arg is a map.
- Documentation for the new canonical names and options-map form.
- Tests on both naming forms and the options map shape.
Motivation
The four SQL fulltext search functions break two conventions:
search_fields,search_fields_more,search_index,search_index_more) while every other SQL function in the codebase uses eithernamespace.name(vector.neighbors,graph.astar,ts.timeBucket) or camelCase (shortestPath,dijkstra). They are the only snake_case island in the registry.search_fields_moreandsearch_index_moreaccept a trailing options blob, but deliver it as an opaque object that is parsed vianew JSONObject(value.toString())then fed toMoreLikeThisConfig.fromJSON. Unknown keys are silently dropped, typos slip through, and the accepted keys are not discoverable from the function signature.This is a natural moment to bundle both: adopt the options-map pattern introduced with #3879 and add namespaced aliases so the codebase converges on one naming convention.
Proposal
Namespace aliases (backward compatible)
search_fieldsfulltext.searchFieldssearch_fields_morefulltext.searchFieldsMoresearch_indexfulltext.searchIndexsearch_index_morefulltext.searchIndexMoreBoth names dispatch to the same function instance via the existing
getAlias()mechanism. The snake_case names stay registered indefinitely.Options map
Replace the current opaque metadata argument on
*_morewith a named options map validated bycom.arcadedb.function.sql.FunctionOptions. Accepted keys correspond one-to-one withMoreLikeThisConfig:Unknown keys throw a descriptive error. Any existing call site that still passes a JSON string keeps working.
Non-goals
limit,minScore, etc.) tosearchFields/searchIndexin this issue. They get aliases only. Growing their options is a separate conversation.*_more.Deliverables
fulltext.*canonical names, keep the legacy names as aliases.SQLFunctionSearchFieldsMore/SQLFunctionSearchIndexMoretoFunctionOptionswhen the trailing arg is a map.