OpsDoc proporciona utilidades para acceder a campos de documentos y depurar plug-ins de ordenamiento en Cava. Durante el cálculo de puntuación, utilice una instancia de OpsDoc para leer valores de campos de atributo, compartir datos entre plug-ins mediante variables declaradas y generar información de rastreo durante las pruebas de búsqueda.
El sistema crea instancias de OpsDoc automáticamente; no es necesaria ninguna instanciación manual.
Contexto de puntuación
Una instancia de OpsDoc está disponible en dos fases de un plug-in de ordenamiento:
|
Fase |
Método |
Operaciones disponibles |
|
Inicialización |
|
|
|
Cálculo de puntuación |
|
Todas las funciones |
Acceda a OpsDoc mediante params.getDoc() en cualquiera de las fases.
Los campos y variables declarados en init están disponibles durante el cálculo de puntuación. Si omite la declaración, no se podrán recuperar los valores de los campos y los métodos de obtención de variables devolverán 0 de forma predeterminada.
Funciones
Declaración de campos
|
Firma |
Descripción |
|
|
Declara un campo de atributo para su uso durante el cálculo de puntuación. Llame a esta función en |
Acceso a campos
Todas las funciones de acceso a campos deben llamarse durante el cálculo de puntuación (en el método score), después de que el campo correspondiente se haya declarado con requireAttribute.
|
Firma |
Tipo de campo |
Tipo de retorno |
Retorno cuando falta el campo o hay incompatibilidad de tipo |
|
|
INT |
|
|
|
|
FLOAT |
|
— |
|
|
DOUBLE |
|
— |
|
|
LITERAL |
|
— |
|
|
INT_ARRAY |
|
|
|
|
FLOAT_ARRAY |
|
|
|
|
DOUBLE_ARRAY |
|
|
|
|
LITERAL_ARRAY |
|
|
|
|
GEO_POINT |
|
|
|
|
TIMESTAMP |
|
|
Variables
Utilice variables para pasar datos entre varios plug-ins de ordenamiento o para incluir valores calculados en los resultados de búsqueda.
|
Firma |
Descripción |
|
|
Declara una variable LONG. Llame a esta función en |
|
|
Declara una variable DOUBLE. Llame a esta función en |
|
|
Establece el valor de una variable LONG declarada. Llame a esta función durante el cálculo de puntuación. |
|
|
Establece el valor de una variable DOUBLE declarada. Llame a esta función durante el cálculo de puntuación. |
|
|
Devuelve el valor de una variable LONG. Devuelve |
|
|
Devuelve el valor de una variable DOUBLE. Devuelve |
Rastreo
Las funciones de rastreo solo están disponibles durante las pruebas de búsqueda en la página Search Test de la consola de OpenSearch. Las solicitudes de búsqueda normales no admiten rastreo. Dado que Cava procesa cada solicitud con memoria de ejecución limitada, el uso intensivo de llamadas de rastreo puede causar presión sobre la memoria; llame a las funciones de rastreo únicamente durante la depuración.
Para mostrar varias variables, llame a trace una vez por cada variable. Los parámetros pasados a las funciones de rastreo no se pueden modificar.
Cada función de rastreo tiene dos sobrecargas: una sin prefijo y otra con un CString prefix que etiqueta la salida para facilitar su revisión.
|
Firma |
Tipo rastreado |
|
|
BYTE |
|
|
BYTE |
|
|
SHORT |
|
|
SHORT |
|
|
INT |
|
|
INT |
|
|
LONG |
|
|
LONG |
|
|
FLOAT |
|
|
FLOAT |
|
|
DOUBLE |
|
|
DOUBLE |
|
|
CString |
|
|
CString |
Detalles de las funciones
requireAttribute
boolean requireAttribute(CString fieldName)Declara un campo de atributo para su uso durante el cálculo de puntuación. Solo se pueden declarar los campos configurados como campos de atributo en la consola de OpenSearch. Llame a esta función en init; los campos no declarados durante la inicialización no se pueden leer en score.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre del campo de atributo. Debe ser una constante. |
Valor de retorno
Devuelve true si el campo se declara correctamente. Devuelve false si el campo no es un campo de atributo.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
// Declare the "price" attribute field before score() runs
boolean ret = params.getDoc().requireAttribute("price");
return ret;
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
float floatValue = doc.docFieldFloat("price");
return floatValue;
}
}docFieldLong
long docFieldLong(CString fieldName)Devuelve el valor de un campo INT como long. Si el campo es FLOAT o DOUBLE, el valor de retorno se redondea al entero más cercano. Si el campo es LITERAL o ARRAY, se devuelve 0.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre del campo de atributo. Debe ser una constante. |
Valor de retorno
El valor del campo como long.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return params.getDoc().requireAttribute("count");
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
long count = doc.docFieldLong("count");
return (double)count;
}
}docFieldFloat
float docFieldFloat(CString fieldName)Devuelve el valor de un campo FLOAT como número de punto flotante.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre del campo de atributo. Debe ser una constante. |
Valor de retorno
El valor del campo como float.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return params.getDoc().requireAttribute("count");
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
float count = doc.docFieldFloat("count");
return (double)count;
}
}docFieldDouble
double docFieldDouble(CString fieldName)Devuelve el valor de un campo DOUBLE como número de punto flotante de doble precisión.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre del campo de atributo. Debe ser una constante. |
Valor de retorno
El valor del campo como double.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return params.getDoc().requireAttribute("count");
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
double count = doc.docFieldDouble("count");
return count;
}
}docFieldLiteral
CString docFieldLiteral(CString fieldName)Devuelve el valor de un campo LITERAL como CString.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre del campo de atributo. Debe ser una constante. |
Valor de retorno
El valor del campo como CString.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return params.getDoc().requireAttribute("tag");
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
CString tag = doc.docFieldLiteral("tag");
if (tag.equals("abc")) {
return 100.0;
}
return 0;
}
}docFieldLongArray
long[] docFieldLongArray(CString fieldName)Devuelve el valor de un campo INT_ARRAY como long[]. Devuelve null si el campo no existe, no se puede convertir al tipo objetivo o no es un campo ARRAY.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre del campo de atributo. Debe ser una constante. |
Valor de retorno
El valor del campo como long[], o null si el campo falta o es incompatible.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return params.getDoc().requireAttribute("tags");
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
long[] tags = doc.docFieldLongArray("tags");
// Always null-check array fields before accessing elements
if (tags != null) {
if (tags.length > 0) {
return (double)tags[0];
}
}
return 0;
}
}docFieldFloatArray
float[] docFieldFloatArray(CString fieldName)Devuelve el valor de un campo FLOAT_ARRAY como float[]. Devuelve null si el campo no existe, no se puede convertir al tipo objetivo o no es un campo ARRAY.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre del campo de atributo. Debe ser una constante. |
Valor de retorno
El valor del campo como float[], o null si el campo falta o es incompatible.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return params.getDoc().requireAttribute("tags");
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
float[] tags = doc.docFieldFloatArray("tags");
if (tags != null) {
if (tags.length > 0) {
return (double)tags[0];
}
}
return 0;
}
}docFieldDoubleArray
double[] docFieldDoubleArray(CString fieldName)Devuelve el valor de un campo DOUBLE_ARRAY como double[]. Devuelve null si el campo no existe, no se puede convertir al tipo objetivo o no es un campo ARRAY.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre del campo de atributo. Debe ser una constante. |
Valor de retorno
El valor del campo como double[], o null si el campo falta o es incompatible.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return params.getDoc().requireAttribute("tags");
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
double[] tags = doc.docFieldDoubleArray("tags");
if (tags != null) {
if (tags.length > 0) {
return (double)tags[0];
}
}
return 0;
}
}docFieldLiteralArray
CString[] docFieldLiteralArray(CString fieldName)Devuelve el valor de un campo LITERAL_ARRAY como CString[]. Devuelve null si el campo no existe, no se puede convertir al tipo objetivo o no es un campo ARRAY.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre del campo de atributo. Debe ser una constante. |
Valor de retorno
El valor del campo como CString[], o null si el campo falta o es incompatible.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return params.getDoc().requireAttribute("tags");
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
CString[] tags = doc.docFieldLiteralArray("tags");
if (tags != null) {
if (tags.length > 0 && tags[0].equals("abc")) {
return 100.0;
}
}
return 0;
}
}docFieldGeoPoint
OpsGeoPoint docFieldGeoPoint(CString fieldName)Devuelve el valor de un campo GEO_POINT como OpsGeoPoint. Devuelve null si el campo no existe o si el tipo de campo no es válido. Se requiere una referencia de objeto OpsGeoPoint para usar esta función.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre del campo de atributo. Debe ser una constante. |
Valor de retorno
El valor del campo como OpsGeoPoint, o null si el campo falta o no es válido.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.framework.OpsGeoPoint;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return params.getDoc().requireAttribute("location");
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
OpsGeoPoint location = doc.docFieldGeoPoint("location");
double longitude = location.getLongitude();
if (longitude < 0 || longitude > 180.0) {
return 0;
}
return 1.0;
}
}docFieldTimestamp
OpsTimestamp docFieldTimestamp(CString fieldName)Devuelve el valor de un campo TIMESTAMP como OpsTimestamp. Devuelve null si el campo no existe o si el tipo de campo no es válido. Se requiere una referencia de objeto OpsTimestamp para usar esta función.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre del campo de atributo. Debe ser una constante. |
Valor de retorno
El valor del campo como OpsTimestamp, o null si el campo falta o no es válido.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.framework.OpsTimestamp;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return params.getDoc().requireAttribute("timestamp");
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
OpsTimestamp timestamp = doc.docFieldTimestamp("timestamp");
return (double)timestamp.getValue();
}
}declareLongVariable
boolean declareLongVariable(CString variableName, boolean needSeraialize)Declara una variable LONG para pasar datos entre plug-ins de ordenamiento o incluirla en los resultados de búsqueda. Llame a esta función en init. Cada plug-in admite un máximo de 30 variables declaradas; superar este límite genera un error.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre de la variable. Debe ser una constante. |
|
|
|
Indica si se debe incluir la variable en los documentos de resultados de búsqueda. Debe ser una constante. Valores válidos: |
Valor de retorno
Devuelve true si la variable se declara correctamente. Devuelve false en caso contrario.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
// Declare "v_int64" and include it in search result documents
return params.getDoc().declareLongVariable("v_int64", true);
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
doc.setLongVariable("v_int64", 100);
long longValue = doc.getLongVariable("v_int64");
doc.trace("long value1: ", longValue);
return 0;
}
}declareDoubleVariable
boolean declareDoubleVariable(CString variableName, boolean needSeraialize)Declara una variable DOUBLE para pasar datos entre plug-ins de ordenamiento o incluirla en los resultados de búsqueda. Llame a esta función en init. Cada plug-in admite un máximo de 30 variables declaradas; superar este límite genera un error.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre de la variable. Debe ser una constante. |
|
|
|
Indica si se debe incluir la variable en los documentos de resultados de búsqueda. Debe ser una constante. Valores válidos: |
Valor de retorno
Devuelve true si la variable se declara correctamente. Devuelve false en caso contrario.
Ejemplo
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return params.getDoc().declareDoubleVariable("v_double", true);
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
doc.setDoubleVariable("v_double", 100);
long doubleValue = doc.getDoubleVariable("v_double");
doc.trace("double value1: ", doubleValue);
return 0;
}
}setLongVariable
void setLongVariable(CString variableName, long value)Establece el valor de una variable LONG declarada. Llame a esta función durante el cálculo de puntuación. La variable debe haberse declarado en init.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre de la variable. |
|
|
|
Valor a asignar. |
setDoubleVariable
void setDoubleVariable(CString variableName, long value)Establece el valor de una variable DOUBLE declarada. Llame a esta función durante el cálculo de puntuación. La variable debe haberse declarado en init.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre de la variable. |
|
|
|
Valor a asignar. |
getLongVariable
long getLongVariable(CString variableName)Devuelve el valor de una variable LONG declarada. Llame a esta función durante el cálculo de puntuación. Devuelve 0 si la variable no se ha declarado o si no se ha establecido su valor.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre de la variable. |
Valor de retorno
El valor de la variable como long. Devuelve 0 si la variable no está declarada o no se ha establecido.
getDoubleVariable
double getDoubleVariable(CString variableName)Devuelve el valor de una variable DOUBLE declarada. Llame a esta función durante el cálculo de puntuación. Devuelve 0 si la variable no se ha declarado o si no se ha establecido su valor.
Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Nombre de la variable. |
Valor de retorno
El valor de la variable como double. Devuelve 0 si la variable no está declarada o no se ha establecido.
trace (sin prefijo)
Todas las sobrecargas de trace siguientes generan el valor directamente, sin etiqueta.
void trace(byte value)
void trace(short value)
void trace(int value)
void trace(long value)
void trace(float value)
void trace(double value)
void trace(CString value)Parámetro
|
Parámetro |
Tipo |
Descripción |
|
|
Variable |
El valor que se mostrará en la salida de rastreo. |
Ejemplo (BYTE)
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return true;
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
byte value = 1;
doc.trace(value);
return 0.0;
}
}trace (con prefijo)
Todas las sobrecargas de trace siguientes generan un valor etiquetado, lo que facilita la localización de variables específicas en la salida de rastreo.
void trace(CString prefix, byte value)
void trace(CString prefix, short value)
void trace(CString prefix, int value)
void trace(CString prefix, long value)
void trace(CString prefix, float value)
void trace(CString prefix, double value)
void trace(CString prefix, CString value)Parámetros
|
Parámetro |
Tipo |
Descripción |
|
|
|
Etiqueta que se antepone a la salida de rastreo. Ayuda a localizar la variable durante las pruebas de búsqueda. |
|
|
Variable |
El valor que se mostrará. |
Ejemplo (DOUBLE con prefijo)
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsDoc;
class BasicSimilarityScorer {
boolean init(OpsScorerInitParams params) {
return true;
}
double score(OpsScoreParams params) {
OpsDoc doc = params.getDoc();
double value = 1.0;
doc.trace("double value: ", value);
return 0.0;
}
}Errores comunes
requireAttribute devuelve false
requireAttribute devuelve false cuando el campo especificado no está configurado como campo de atributo en la consola de OpenSearch. Compruebe que el campo aparece en Attribute Fields en la consola antes de declararlo en init.
El acceso a campos de matriz devuelve null
docFieldLongArray, docFieldFloatArray, docFieldDoubleArray y docFieldLiteralArray devuelven null cuando:
El campo no existe en el documento.
El tipo de campo no coincide (por ejemplo, llamar a
docFieldLongArrayen un campo FLOAT_ARRAY).El campo no es de tipo ARRAY.
Compruebe siempre si el valor de retorno es nulo antes de acceder a elementos de la matriz o llamar a .length.
getLongVariable o getDoubleVariable devuelve 0 inesperadamente
Ambos métodos de obtención devuelven 0 cuando la variable no se ha declarado en init o cuando no se ha llamado a setLongVariable/setDoubleVariable antes del método de obtención. Confirme lo siguiente:
La variable está declarada en
initmediantedeclareLongVariableodeclareDoubleVariable.Se llama al método de establecimiento en
scoreantes que al método de obtención.
Si utiliza el valor de la variable en divisiones o lógica condicional, compruebe que el valor no sea cero antes de operar con él.
La declaración de variable devuelve false o genera un error
Cada plug-in admite un máximo de 30 variables declaradas en total, sumando los tipos LONG y DOUBLE. Superar este límite provoca un error. Revise las declaraciones de variables en init y elimine las que no se utilicen.
No se puede recuperar el valor del campo durante score
Si las funciones docField* devuelven valores predeterminados inesperados (como 0 para tipos numéricos), es probable que el campo no se haya declarado en init mediante requireAttribute. La declaración de campos debe realizarse antes del cálculo de puntuación; agregar llamadas a requireAttribute en score no tiene ningún efecto.