feat: MVA and Float Vector UDF support

Author: sanikolaev

manual/chinese/Extensions/UDFs_and_Plugins/UDFs_and_Plugins.md

@@ -9,11 +9,21 @@ SELECT id, attr1, myudf (attr2, attr3+attr4) ...
 您可以动态加载和卸载 `searchd` 中的 UDF，而无需重启服务器，并且可以在搜索、排序等操作时在表达式中使用它们。UDF 功能的简要总结如下：
 
 * UDF 可以接受整型（32 位和 64 位）、浮点型、字符串、多值属性（MVA）或 `PACKEDFACTORS()` 参数。
-* UDF 可以返回整型、浮点型或字符串值。
+* UDF可以返回整数、浮点数、字符串或MVA值（MULTI、MULTI64、FLOAT_VECTOR）。
 * UDF 可以在查询设置阶段检查参数的数量、类型和名称，并且可以抛出错误。
 
 我们还不支持聚合函数。换句话说，您的 UDF 将一次只为单个文档调用，且应返回该文档的某个值。目前还无法编写能够计算整个共享相同 GROUP BY 键的文档组上的聚合值（如 AVG()）的函数。不过，您可以在内置聚合函数中使用 UDF：即使不支持 MYCUSTOMAVG()，使用 AVG(MYCUSTOMFUNC()) 应该可以正常工作！
 
+## MVA返回类型
+
+除了标量值外，UDF还可以返回多值属性（MVA）。支持的MVA返回类型包括：
+
+* **MULTI**：32位无符号整数数组
+* **MULTI64**：64位有符号整数数组
+* **FLOAT_VECTOR**：浮点数数组
+
+MVA UDF使用相同的`CREATE FUNCTION`语法创建，并指定适当的返回类型，可以像标量UDF一样在SELECT语句中使用。
+
 UDF 具有广泛的应用，包括：
 
 * 集成自定义的数学或字符串函数；

manual/english/Extensions/UDFs_and_Plugins/UDFs_and_Plugins.md

@@ -9,11 +9,21 @@ SELECT id, attr1, myudf (attr2, attr3+attr4) ...
 You can dynamically load and unload UDFs into `searchd` without having to restart the server, and use them in expressions when searching, ranking, etc. A quick summary of the UDF features is as follows:
 
 * UDFs can take integer (both 32-bit and 64-bit), float, string, MVA, or `PACKEDFACTORS()` arguments.
-* UDFs can return integer, float, or string values.
+* UDFs can return integer, float, string, or MVA values (MULTI, MULTI64, FLOAT_VECTOR).
 * UDFs can check the argument number, types, and names during the query setup phase, and raise errors.
 
 We do not yet support aggregation functions. In other words, your UDFs will be called for just a single document at a time and are expected to return some value for that document. Writing a function that can compute an aggregate value like AVG() over the entire group of documents that share the same GROUP BY key is not yet possible. However, you can use UDFs within the built-in aggregate functions: that is, even though MYCUSTOMAVG() is not supported yet, AVG(MYCUSTOMFUNC()) should work just fine!
 
+## MVA Return Types
+
+UDFs can also return Multi-Value Attributes (MVA) in addition to scalar values. The supported MVA return types are:
+
+* **MULTI**: Arrays of 32-bit unsigned integers
+* **MULTI64**: Arrays of 64-bit signed integers  
+* **FLOAT_VECTOR**: Arrays of floating-point numbers
+
+MVA UDFs are created using the same `CREATE FUNCTION` syntax with the appropriate return type, and can be used in SELECT statements just like scalar UDFs.
+
 UDFs offer a wide range of applications, such as:
 
 * incorporating custom mathematical or string functions;

manual/russian/Extensions/UDFs_and_Plugins/UDFs_and_Plugins.md

@@ -9,11 +9,21 @@ SELECT id, attr1, myudf (attr2, attr3+attr4) ...
 Вы можете динамически загружать и выгружать UDF в `searchd` без необходимости перезапуска сервера, и использовать их в выражениях при поиске, ранжировании и т.д. Краткое описание возможностей UDF:
 
 * UDF могут принимать аргументы типа integer (как 32-битные, так и 64-битные), float, string, MVA или `PACKEDFACTORS()`.
-* UDF могут возвращать значения типа integer, float или string.
+* UDF могут возвращать значения целочисленного, вещественного, строкового или MVA типов (MULTI, MULTI64, FLOAT_VECTOR).
 * UDF могут проверять номер, типы и имена аргументов во время стадии настройки запроса и генерировать ошибки.
 
 В настоящее время агрегатные функции не поддерживаются. Другими словами, ваши UDF вызываются только для одного документа за раз и должны возвращать некоторое значение для этого документа. Написать функцию, которая может вычислить агрегатное значение, например AVG() для всей группы документов, имеющих одинаковый ключ GROUP BY, пока невозможно. Однако вы можете использовать UDF внутри встроенных агрегатных функций: другими словами, хотя MYCUSTOMAVG() пока не поддерживается, AVG(MYCUSTOMFUNC()) должна работать без проблем!
 
+## Типы возвращаемых MVA
+
+UDF также могут возвращать многозначные атрибуты (MVA) в дополнение к скалярным значениям. Поддерживаемые типы возвращаемых MVA:
+
+* **MULTI**: Массивы 32-битных беззнаковых целых чисел
+* **MULTI64**: Массивы 64-битных знаковых целых чисел  
+* **FLOAT_VECTOR**: Массивы чисел с плавающей запятой
+
+MVA UDF создаются с использованием того же синтаксиса `CREATE FUNCTION` с соответствующим типом возвращаемого значения и могут использоваться в предложениях SELECT так же, как и скалярные UDF.
+
 UDF предоставляют широкий спектр применений, таких как:
 
 * внедрение собственных математических или строковых функций;

src/ddl.y

@@ -506,6 +506,9 @@ udf_type:
 	| TOK_FLOAT		{ $$.SetValueInt ( SPH_ATTR_FLOAT ); }
 	| TOK_STRING	{ $$.SetValueInt ( SPH_ATTR_STRINGPTR ); }
 	| TOK_INTEGER	{ $$.SetValueInt ( SPH_ATTR_INTEGER ); }
+	| TOK_MULTI		{ $$.SetValueInt ( SPH_ATTR_UINT32SET_PTR ); }
+	| TOK_MULTI64	{ $$.SetValueInt ( SPH_ATTR_INT64SET_PTR ); }
+	| TOK_FLOAT_VECTOR { $$.SetValueInt ( SPH_ATTR_FLOAT_VECTOR_PTR ); }
 	;
 
 drop_function:

src/querycontext.h

@@ -51,7 +51,21 @@ FORCE_INLINE void CalcContextItem ( CSphMatch & tMatch, const ContextCalcItem_t
 	case SPH_ATTR_INT64SET_PTR:
 	case SPH_ATTR_UINT32SET_PTR:
 	case SPH_ATTR_FLOAT_VECTOR_PTR:
-		tMatch.SetAttr ( tCalc.m_tLoc, (SphAttr_t)tCalc.m_pExpr->Int64Eval ( tMatch ) );
+		{
+			// Check if this is a UDF expression that returns raw MVA data
+			// UDF expressions need MvaEval() + packing, while regular expressions use Int64Eval()
+			if ( tCalc.m_pExpr->IsDataPtrAttr() )
+			{
+				ByteBlob_t tMva = tCalc.m_pExpr->MvaEval ( tMatch );
+				BYTE * pPacked = sphPackPtrAttr ( tMva );
+				tMatch.SetAttr ( tCalc.m_tLoc, (SphAttr_t)pPacked );
+			}
+			else
+			{
+				// Regular MVA expressions (including columnar) return packed data directly
+				tMatch.SetAttr ( tCalc.m_tLoc, (SphAttr_t)tCalc.m_pExpr->Int64Eval ( tMatch ) );
+			}
+		}
 		break;
 
 	case SPH_ATTR_DOUBLE:

src/sphinxexpr.cpp

@@ -5574,6 +5574,7 @@ void MoveToArgList ( ISphExpr * pLeft, VecRefPtrs_t<ISphExpr*> &dArgs )
 using UdfInt_fn = sphinx_int64_t ( * ) ( SPH_UDF_INIT *, SPH_UDF_ARGS *, char * );
 using UdfDouble_fn = double ( * ) ( SPH_UDF_INIT *, SPH_UDF_ARGS *, char * );
 using UdfCharptr_fn = char * ( * ) ( SPH_UDF_INIT *, SPH_UDF_ARGS *, char * );
+using UdfMva_fn = ByteBlob_t ( * ) ( SPH_UDF_INIT *, SPH_UDF_ARGS *, char * );
 
 class Expr_Udf_c : public ISphExpr
 {
@@ -5880,6 +5881,186 @@ class Expr_UdfStringptr_c : public Expr_Udf_c
 };
 
 
+class Expr_UdfMva32_c : public Expr_Udf_c
+{
+public:
+	explicit Expr_UdfMva32_c ( UdfCall_t * pCall, QueryProfile_c * pProfiler )
+		: Expr_Udf_c ( pCall, pProfiler )
+	{
+		assert ( pCall->m_pUdf->m_eRetType==SPH_ATTR_UINT32SET_PTR );
+		m_pFn = (UdfMva_fn) m_pCall->m_pUdf->m_fnFunc;
+	}
+
+	ByteBlob_t MvaEval ( const CSphMatch & tMatch ) const final
+	{
+		if ( m_bError )
+			return {nullptr, 0};
+
+		CSphScopedProfile tProf ( m_pProfiler, SPH_QSTATE_EVAL_UDF );
+		FillArgs ( tMatch );
+		auto tRes = m_pFn ( &m_pCall->m_tInit, &m_pCall->m_tArgs, &m_bError );
+		FreeArgs();
+		return tRes;
+	}
+
+	float Eval ( const CSphMatch & ) const final
+	{
+		assert ( 0 && "internal error: mva32 udf evaluated as float" );
+		return 0.0f;
+	}
+
+	int IntEval ( const CSphMatch & ) const final
+	{
+		assert ( 0 && "internal error: mva32 udf evaluated as int" );
+		return 0;
+	}
+
+	int64_t Int64Eval ( const CSphMatch & ) const final
+	{
+		assert ( 0 && "internal error: mva32 udf evaluated as bigint" );
+		return 0;
+	}
+
+	bool IsDataPtrAttr() const final
+	{
+		return true;
+	}
+
+	ISphExpr * Clone () const final
+	{
+		return new Expr_UdfMva32_c ( *this );
+	}
+
+private:
+	Expr_UdfMva32_c ( const Expr_UdfMva32_c& rhs )
+		: Expr_Udf_c ( rhs )
+		, m_pFn ( rhs.m_pFn )
+	{
+	}
+	UdfMva_fn m_pFn; // to avoid dereference on each MvaEval() call
+};
+
+
+class Expr_UdfMva64_c : public Expr_Udf_c
+{
+public:
+	explicit Expr_UdfMva64_c ( UdfCall_t * pCall, QueryProfile_c * pProfiler )
+		: Expr_Udf_c ( pCall, pProfiler )
+	{
+		assert ( pCall->m_pUdf->m_eRetType==SPH_ATTR_INT64SET_PTR );
+		m_pFn = (UdfMva_fn) m_pCall->m_pUdf->m_fnFunc;
+	}
+
+	ByteBlob_t MvaEval ( const CSphMatch & tMatch ) const final
+	{
+		if ( m_bError )
+			return {nullptr, 0};
+
+		CSphScopedProfile tProf ( m_pProfiler, SPH_QSTATE_EVAL_UDF );
+		FillArgs ( tMatch );
+		auto tRes = m_pFn ( &m_pCall->m_tInit, &m_pCall->m_tArgs, &m_bError );
+		FreeArgs();
+		return tRes;
+	}
+
+	float Eval ( const CSphMatch & ) const final
+	{
+		assert ( 0 && "internal error: mva64 udf evaluated as float" );
+		return 0.0f;
+	}
+
+	int IntEval ( const CSphMatch & ) const final
+	{
+		assert ( 0 && "internal error: mva64 udf evaluated as int" );
+		return 0;
+	}
+
+	int64_t Int64Eval ( const CSphMatch & ) const final
+	{
+		assert ( 0 && "internal error: mva64 udf evaluated as bigint" );
+		return 0;
+	}
+
+	bool IsDataPtrAttr() const final
+	{
+		return true;
+	}
+
+	ISphExpr * Clone () const final
+	{
+		return new Expr_UdfMva64_c ( *this );
+	}
+
+private:
+	Expr_UdfMva64_c ( const Expr_UdfMva64_c& rhs )
+		: Expr_Udf_c ( rhs )
+		, m_pFn ( rhs.m_pFn )
+	{
+	}
+	UdfMva_fn m_pFn; // to avoid dereference on each MvaEval() call
+};
+
+
+class Expr_UdfFloatVector_c : public Expr_Udf_c
+{
+public:
+	explicit Expr_UdfFloatVector_c ( UdfCall_t * pCall, QueryProfile_c * pProfiler )
+		: Expr_Udf_c ( pCall, pProfiler )
+	{
+		assert ( pCall->m_pUdf->m_eRetType==SPH_ATTR_FLOAT_VECTOR_PTR );
+		m_pFn = (UdfMva_fn) m_pCall->m_pUdf->m_fnFunc;
+	}
+
+	ByteBlob_t MvaEval ( const CSphMatch & tMatch ) const final
+	{
+		if ( m_bError )
+			return {nullptr, 0};
+
+		CSphScopedProfile tProf ( m_pProfiler, SPH_QSTATE_EVAL_UDF );
+		FillArgs ( tMatch );
+		auto tRes = m_pFn ( &m_pCall->m_tInit, &m_pCall->m_tArgs, &m_bError );
+		FreeArgs();
+		return tRes;
+	}
+
+	float Eval ( const CSphMatch & ) const final
+	{
+		assert ( 0 && "internal error: float_vector udf evaluated as float" );
+		return 0.0f;
+	}
+
+	int IntEval ( const CSphMatch & ) const final
+	{
+		assert ( 0 && "internal error: float_vector udf evaluated as int" );
+		return 0;
+	}
+
+	int64_t Int64Eval ( const CSphMatch & ) const final
+	{
+		assert ( 0 && "internal error: float_vector udf evaluated as bigint" );
+		return 0;
+	}
+
+	bool IsDataPtrAttr() const final
+	{
+		return true;
+	}
+
+	ISphExpr * Clone () const final
+	{
+		return new Expr_UdfFloatVector_c ( *this );
+	}
+
+private:
+	Expr_UdfFloatVector_c ( const Expr_UdfFloatVector_c& rhs )
+		: Expr_Udf_c ( rhs )
+		, m_pFn ( rhs.m_pFn )
+	{
+	}
+	UdfMva_fn m_pFn; // to avoid dereference on each MvaEval() call
+};
+
+
 ISphExpr * ExprParser_t::CreateUdfNode ( int iCall, ISphExpr * pLeft )
 {
 	if ( !CheckStoredArg(pLeft) )
@@ -5898,6 +6079,15 @@ ISphExpr * ExprParser_t::CreateUdfNode ( int iCall, ISphExpr * pLeft )
 		case SPH_ATTR_STRINGPTR:
 			pRes = new Expr_UdfStringptr_c ( m_dUdfCalls[iCall], m_pProfiler );
 			break;
+		case SPH_ATTR_UINT32SET_PTR:
+			pRes = new Expr_UdfMva32_c ( m_dUdfCalls[iCall], m_pProfiler );
+			break;
+		case SPH_ATTR_INT64SET_PTR:
+			pRes = new Expr_UdfMva64_c ( m_dUdfCalls[iCall], m_pProfiler );
+			break;
+		case SPH_ATTR_FLOAT_VECTOR_PTR:
+			pRes = new Expr_UdfFloatVector_c ( m_dUdfCalls[iCall], m_pProfiler );
+			break;
 		default:
 			m_sCreateError.SetSprintf ( "internal error: unhandled type %d in CreateUdfNode()", m_dUdfCalls[iCall]->m_pUdf->m_eRetType );
 			break;
@@ -10269,6 +10459,10 @@ int ExprParser_t::AddNodeUdf ( int iCall, int iArg )
 				case SPH_ATTR_JSON_FIELD:
 					eRes = SPH_UDF_TYPE_JSON;
 					break;
+				case SPH_ATTR_FLOAT_VECTOR:
+				case SPH_ATTR_FLOAT_VECTOR_PTR:
+					eRes = SPH_UDF_TYPE_FLOAT_VECTOR_RETURN;
+					break;
 				default:
 					m_sParserError.SetSprintf ( "internal error: unmapped UDF argument type (arg=%d, type=%u)", i, dArgTypes[i] );
 					return -1;
@@ -10300,6 +10494,8 @@ int ExprParser_t::AddNodeUdf ( int iCall, int iArg )
 	// deduce type
 	tNode.m_eArgType = ( iArg>=0 ) ? m_dNodes[iArg].m_eRetType : SPH_ATTR_INTEGER;
 	tNode.m_eRetType = pCall->m_pUdf->m_eRetType;
+	
+	
 	return m_dNodes.GetLength()-1;
 }
 

src/sphinxudf.h

@@ -29,7 +29,7 @@ extern "C" {
 #endif
 
 /// current udf version
-#define SPH_UDF_VERSION 11
+#define SPH_UDF_VERSION 12
 
 /// error buffer size
 #define SPH_UDF_ERROR_LEN 256
@@ -48,7 +48,10 @@ enum sphinx_udf_argtype
 	SPH_UDF_TYPE_STRING			= 5,			///< non-ASCIIZ string, with a separately stored length
 	SPH_UDF_TYPE_INT64SET		= 6,			///< sorted set of signed 64-bit integers
 	SPH_UDF_TYPE_FACTORS		= 7,			///< packed ranking factors
-	SPH_UDF_TYPE_JSON			= 8				///< whole json or particular field as a string
+	SPH_UDF_TYPE_JSON			= 8,			///< whole json or particular field as a string
+	SPH_UDF_TYPE_UINT32SET_RETURN = 9,		///< return type: sorted set of unsigned 32-bit integers
+	SPH_UDF_TYPE_INT64SET_RETURN = 10,		///< return type: sorted set of signed 64-bit integers
+	SPH_UDF_TYPE_FLOAT_VECTOR_RETURN = 11	///< return type: vector of floats
 };
 
 /// our malloc() replacement type