SQL fulltext search_* functions: adopt options map and add fulltext.* namespace aliases (original) (raw)

Motivation

The four SQL fulltext search functions break two conventions:

1. 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.
2. 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)

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.