OpsDoc

Field declaration

Field access

All field access functions must be called during score calculation (in the score method), after the corresponding field has been declared with requireAttribute.

Variables

Use variables to pass data between multiple sort plug-ins or to include computed values in search results.

Trace

To display multiple variables, call trace once per variable. Parameters passed to trace functions cannot be changed.

Each trace function has two overloads: one without a prefix and one with a CString prefix that labels the output for easier scanning.

requireAttribute

boolean requireAttribute(CString fieldName)

Declares an attribute field for use during score calculation. Only fields that are configured as attribute fields in the OpenSearch console can be declared. Call this function in init; fields not declared during initialization cannot be read in score.

Parameters

Return value

Returns true if the field is successfully declared. Returns false if the field is not an attribute field.

Example

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)

Returns the value of an INT field as a long. If the field is FLOAT or DOUBLE, the return value is rounded to the nearest integer. If the field is LITERAL or ARRAY, 0 is returned.

Parameters

Return value

The field value as a long.

Example

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)

Returns the value of a FLOAT field as a floating-point number.

Parameters

Return value

The field value as a float.

Example

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)

Returns the value of a DOUBLE field as a double-precision floating-point number.

Parameters

Return value

The field value as a double.

Example

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)

Returns the value of a LITERAL field as a CString.

Parameters

Return value

The field value as a CString.

Example

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)

Returns the value of an INT_ARRAY field as a long[]. Returns null if the field does not exist, cannot be converted to the target type, or is not an ARRAY field.

Parameters

Return value

The field value as a long[], or null if the field is missing or incompatible.

Example

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)

Returns the value of a FLOAT_ARRAY field as a float[]. Returns null if the field does not exist, cannot be converted to the target type, or is not an ARRAY field.

Parameters

Return value

The field value as a float[], or null if the field is missing or incompatible.

Example

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)

Returns the value of a DOUBLE_ARRAY field as a double[]. Returns null if the field does not exist, cannot be converted to the target type, or is not an ARRAY field.

Parameters

Return value

The field value as a double[], or null if the field is missing or incompatible.

Example

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)

Returns the value of a LITERAL_ARRAY field as a CString[]. Returns null if the field does not exist, cannot be converted to the target type, or is not an ARRAY field.

Parameters

Return value

The field value as a CString[], or null if the field is missing or incompatible.

Example

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)

Returns the value of a GEO_POINT field as an OpsGeoPoint. Returns null if the field does not exist or the field type is invalid. An OpsGeoPoint object reference is required to use this function.

Parameters

Return value

The field value as an OpsGeoPoint, or null if the field is missing or invalid.

Example

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)

Returns the value of a TIMESTAMP field as an OpsTimestamp. Returns null if the field does not exist or the field type is invalid. An OpsTimestamp object reference is required to use this function.

Parameters

Return value

The field value as an OpsTimestamp, or null if the field is missing or invalid.

Example

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)

Declares a LONG variable for passing data between sort plug-ins or including it in search results. Call this in init. Each plug-in supports a maximum of 30 declared variables — exceeding this limit returns an error.

Parameters

Return value

Returns true if the variable is successfully declared. Returns false otherwise.

Example

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)

Declares a DOUBLE variable for passing data between sort plug-ins or including it in search results. Call this in init. Each plug-in supports a maximum of 30 declared variables — exceeding this limit returns an error.

Parameters

Return value

Returns true if the variable is successfully declared. Returns false otherwise.

Example

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)

Sets the value of a declared LONG variable. Call this during score calculation. The variable must have been declared in init.

Parameters

setDoubleVariable

void setDoubleVariable(CString variableName, long value)

Sets the value of a declared DOUBLE variable. Call this during score calculation. The variable must have been declared in init.

Parameters

getLongVariable

long getLongVariable(CString variableName)

Returns the value of a declared LONG variable. Call this during score calculation. Returns 0 if the variable has not been declared or its value has not been set.

Parameters

Return value

The variable value as a long. Returns 0 if the variable is undeclared or unset.

getDoubleVariable

double getDoubleVariable(CString variableName)

Returns the value of a declared DOUBLE variable. Call this during score calculation. Returns 0 if the variable has not been declared or its value has not been set.

Parameters

Return value

The variable value as a double. Returns 0 if the variable is undeclared or unset.

trace (without prefix)

All trace overloads below output the value directly, without a label.

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)

Parameter

Example (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 (with prefix)

All trace overloads below output a labeled value, making it easier to locate specific variables in trace output.

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)

Parameters

Example (DOUBLE with prefix)

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;
    }
}

requireAttribute returns false

requireAttribute returns false when the specified field is not configured as an attribute field in the OpenSearch console. Verify that the field is listed under Attribute Fields in the console before declaring it in init.

Array field access returns null

docFieldLongArray, docFieldFloatArray, docFieldDoubleArray, and docFieldLiteralArray return null when:

• The field does not exist in the document.

• The field type does not match (for example, calling docFieldLongArray on a FLOAT_ARRAY field).

• The field is not an ARRAY type.

Always null-check the return value before accessing array elements or calling .length.

getLongVariable or getDoubleVariable returns 0 unexpectedly

Both getters return 0 when the variable has not been declared in init or when setLongVariable/setDoubleVariable has not been called before the getter. Confirm that:

1. The variable is declared in init using declareLongVariable or declareDoubleVariable.

2. The setter is called in score before the getter.

If you use the variable value in division or conditional logic, verify the value is non-zero before operating on it.

Variable declaration returns false or triggers an error

Each plug-in supports a maximum of 30 declared variables across both LONG and DOUBLE types. Exceeding this limit causes an error. Audit variable declarations in init and remove any unused ones.

Field value not retrievable during score

If docField* functions return unexpected defaults (such as 0 for numeric types), the field was likely not declared in init via requireAttribute. Field declaration must happen before score calculation — adding requireAttribute calls in score has no effect.